1DHCPCTL(3) BSD Library Functions Manual DHCPCTL(3)
2
4 dhcpctl_initialize — dhcpctl library initialization.
5
7 #include <dhcpctl.h>
8 dhcpctl_status
11 dhcpctl_initialize(void);
12 dhcpctl_status
14 dhcpctl_connect(dhcpctl_handle *cxn, const char *host, int port,
15 dhcpctl_handle auth);
16 dhcpctl_status
18 dhcpctl_wait_for_completion(dhcpctl_handle object,
19 dhcpctl_status *status);
20 dhcpctl_status
22 dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
23 const char *name);
24 dhcpctl_status
26 dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);
27 dhcpctl_status
29 dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
30 const char *name);
31 dhcpctl_status
33 dhcpctl_set_string_value(dhcpctl_handle object, const char *value,
34 const char *name);
35 dhcpctl_status
37 dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
38 const char *name);
39 dhcpctl_status
41 dhcpctl_set_int_value(dhcpctl_handle object, int value,
42 const char *name);
43 dhcpctl_status
45 dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);
46 dhcpctl_status
48 dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);
49 dhcpctl_status
51 dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);
52 dhcpctl_status
54 dhcpctl_set_callback(dhcpctl_handle object, void *data,
55 void (*function) (dhcpctl_handle, dhcpctl_status, void *));
56 dhcpctl_status
58 dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
59 const char *algorithm, const char *secret, unsigned secret_len);
60 dhcpctl_status
62 dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection,
63 const char *object_type);
64 dhcpctl_status
66 dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection,
67 int flags);
68 isc_result_t
70 omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length,
71 const, char, *filename,, int, lineno);
72 isc_result_t
74 dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,
75 int);
76
78 The dhcpctl set of functions provide an API that can be used to communi‐
79 cate with and manipulate a running ISC DHCP server. All functions return
80 a value of isc_result_t. The return values reflects the result of opera‐
81 tions to local data structures. If an operation fails on the server for
82 any reason, then the error result will be returned through the second
83 parameter of the dhcpctl_wait_for_completion() call.
84 dhcpctl_initialize() sets up the data structures the library needs to do
86 its work. This function must be called once before any other.
87 dhcpctl_connect() opens a connection to the DHCP server at the given host
89 and port. If an authenticator has been created for the connection, then
90 it is given as the 4th argument. On a successful return the address
91 pointed at by the first argument will have a new connection object
92 assigned to it.
93 For example:
95 s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
97 connects to the DHCP server on the localhost via port 7911 (the standard
99 OMAPI port). No authentication is used for the connection.
100 dhcpctl_wait_for_completion() flushes a pending message to the server and
102 waits for the response. The result of the request as processed on the
103 server is returned via the second parameter.
104 s = dhcpctl_wait_for_completion(cxn, &wv);
106 if (s != ISC_R_SUCCESS)
107 local_failure(s);
108 else if (wv != ISC_R_SUCCESS)
109 server_failure(wc);
110 The call to dhcpctl_wait_for_completion() won't return until the remote
112 message processing completes or the connection to the server is lost.
113 dhcpctl_get_value() extracts a value of an attribute from the handle. The
115 value can be of any length and is treated as a sequence of bytes. The
116 handle must have been created first with dhcpctl_new_object() and opened
117 with dhcpctl_open_object(). The value is returned via the parameter
118 named “value”. The last parameter is the name of attribute to retrieve.
119 dhcpctl_data_string value = NULL;
121 dhcpctl_handle lease;
122 time_t thetime;
123 s = dhcpctl_get_value (&value, lease, "ends");
125 assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
126 memcpy(&thetime, value->value, value->len);
127 dhcpctl_get_boolean() extracts a boolean valued attribute from the object
129 handle.
130 The dhcpctl_set_value(), dhcpctl_set_string_value(),
132 dhcpctl_set_boolean_value(), and dhcpctl_set_int_value() functions all
133 set a value on the object handle.
134 dhcpctl_object_update() function queues a request for all the changes
136 made to the object handle be be sent to the remote for processing. The
137 changes made to the atributes on the handle will be applied to remote
138 object if permitted.
139 dhcpctl_object_refresh() queues up a request for a fresh copy of all the
141 attribute values to be sent from the remote to refresh the values in the
142 local object handle.
143 dhcpctl_object_remove() queues a request for the removal on the server of
145 the object referenced by the handle.
146 The dhcpctl_set_callback() function sets up a user-defined function to be
148 called when an event completes on the given object handle. This is needed
149 for asynchronous handling of events, versus the synchronous handling
150 given by dhcpctl_wait_for_completion(). When the function is called the
151 first parameter is the object the event arrived for, the second is the
152 status of the message that was processed, the third is the same value as
153 the second parameter given to dhcpctl_set_callback().
154 The dhcpctl_new_authenticator() creates a new authenticator object to be
156 used for signing the messages that cross over the network. The “name”,
157 “algorithm”, and “secret” values must all match what the server uses and
158 are defined in its configuration file. The created object is returned
159 through the first parameter and must be used as the 4th parameter to
160 dhcpctl_connect(). Note that the 'secret' value must not be base64
161 encoded, which is different from how the value appears in the dhcpd.conf
162 file.
163 dhcpctl_new_object() creates a local handle for an object on the the
165 server. The “object_type” parameter is the ascii name of the type of
166 object being accessed. e.g. "lease". This function only sets up local
167 data structures, it does not queue any messages to be sent to the remote
168 side, dhcpctl_open_object() does that.
169 dhcpctl_open_object() builds and queues the request to the remote side.
171 This function is used with handle created via dhcpctl_new_object(). The
172 flags argument is a bit mask with the following values available for set‐
173 ting:
174 DHCPCTL_CREATE
176 if the object does not exist then the remote will create it
177 DHCPCTL_UPDATE
179 update the object on the remote side using the attributes
180 already set in the handle.
181 DHCPCTL_EXCL
183 return and error if the object exists and DHCPCTL_CREATE was
184 also specified
185 The omapi_data_string_new() function allocates a new dhcpctl_data_string
187 object. The data string will be large enough to hold “length” bytes of
188 data. The “file” and “lineno” arguments are the source file location the
189 call is made from, typically by using the __FILE__ and __LINE__ macros or
190 the MDL macro defined in
191 dhcpctl_data_string_dereference() deallocates a data string created by
193 omapi_data_string_new(). The memory for the object won't be freed until
194 the last reference is released.
195
197 The following program will connect to the DHCP server running on the
198 local host and will get the details of the existing lease for IP address
199 10.0.0.101. It will then print out the time the lease is due to expire.
200 Note that most error checking has been ommitted for brevity.
201 #include <stdarg.h>
203 #include <sys/time.h>
204 #include <sys/socket.h>
205 #include <stdio.h>
206 #include <netinet/in.h>
207 #include <isc/result.h>
209 #include <dhcpctl.h>
210 int main (int argc, char **argv) {
212 dhcpctl_data_string ipaddrstring = NULL;
213 dhcpctl_data_string value = NULL;
214 dhcpctl_handle connection = NULL;
215 dhcpctl_handle lease = NULL;
216 isc_result_t waitstatus;
217 struct in_addr convaddr;
218 time_t thetime;
219 dhcpctl_initialize ();
221 dhcpctl_connect (&connection, "127.0.0.1",
223 7911, 0);
224 dhcpctl_new_object (&lease, connection,
226 "lease");
227 memset (&ipaddrstring, 0, sizeof
229 ipaddrstring);
230 inet_pton(AF_INET, "10.0.0.101",
232 &convaddr);
233 omapi_data_string_new (&ipaddrstring,
235 4, MDL);
236 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
237 dhcpctl_set_value (lease, ipaddrstring,
239 "ip-address");
240 dhcpctl_open_object (lease, connection, 0);
242 dhcpctl_wait_for_completion (lease,
244 &waitstatus);
245 if (waitstatus != ISC_R_SUCCESS) {
246 /* server not authoritative */
247 exit (0);
248 }
249 dhcpctl_data_string_dereference(&ipaddrstring,
251 MDL);
252 dhcpctl_get_value (&value, lease, "ends");
254 memcpy(&thetime, value->value, value->len);
256 dhcpctl_data_string_dereference(&value, MDL);
258 fprintf (stdout, "ending time is %s",
260 ctime(&thetime));
261 }
262
264 omapi(3), omshell(3), dhcpd(8), dhclient(8), dhcpd.conf(5),
265 dhclient.conf(5).
266
268 dhcpctl was written by Ted Lemon of Nominum, Inc. This preliminary docu‐
269 mentation was written by James Brister of Nominum, Inc.
270DHCP 3 Nov 15, 2000 DHCP 3