1DHCPCTL(3) BSD Library Functions Manual DHCPCTL(3)
2
4 dhcpctl_initialize — dhcpctl library initialization.
5
7 #include <dhcpctl/dhcpctl.h>
8 dhcpctl_status
10 dhcpctl_initialize(void);
11 dhcpctl_status
13 dhcpctl_connect(dhcpctl_handle *cxn, const char *host, int port,
14 dhcpctl_handle auth);
15 dhcpctl_status
17 dhcpctl_timed_connect(dhcpctl_handle *cxn, const char *host, int port,
18 dhcpctl_handle auth, dhcpctl_status *status);
19 dhcpctl_status
21 dhcpctl_disconnect(dhcpctl_handle *cxn, int force);
22 dhcpctl_status
24 dhcpctl_wait_for_completion(dhcpctl_handle object,
25 dhcpctl_status *status);
26 dhcpctl_status
28 dhcpctl_timed_wait_for_completion(dhcpctl_handle object,
29 dhcpctl_status *status, struct timeval *timeout);
30 dhcpctl_status
32 dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
33 const char *name);
34 dhcpctl_status
36 dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);
37 dhcpctl_status
39 dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
40 const char *name);
41 dhcpctl_status
43 dhcpctl_set_string_value(dhcpctl_handle object, const char *value,
44 const char *name);
45 dhcpctl_status
47 dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
48 const char *name);
49 dhcpctl_status
51 dhcpctl_set_int_value(dhcpctl_handle object, int value,
52 const char *name);
53 dhcpctl_status
55 dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);
56 dhcpctl_status
58 dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);
59 dhcpctl_status
61 dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);
62 dhcpctl_status
64 dhcpctl_set_callback(dhcpctl_handle object, void *data,
65 void (*function) (dhcpctl_handle, dhcpctl_status, void *));
66 dhcpctl_status
68 dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
69 const char *algorithm, const char *secret, unsigned secret_len);
70 dhcpctl_status
72 dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection,
73 const char *object_type);
74 dhcpctl_status
76 dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection,
77 int flags);
78 isc_result_t
80 omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length,
81 const, char, *filename,, int, lineno);
82 isc_result_t
84 dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,
85 int);
86
88 The dhcpctl set of functions provide an API that can be used to communi‐
89 cate with and manipulate a running ISC DHCP server. All functions return
90 a value of isc_result_t. The return values reflects the result of opera‐
91 tions to local data structures. If an operation fails on the server for
92 any reason, then the error result will be returned through the second pa‐
93 rameter of the dhcpctl_wait_for_completion() call.
94 dhcpctl_initialize() sets up the data structures the library needs to do
96 its work. This function must be called once before any other.
97 dhcpctl_connect() opens a connection to the DHCP server at the given host
99 and port. If an authenticator has been created for the connection, then
100 it is given as the 4th argument. On a successful return the address
101 pointed at by the first argument will have a new connection object as‐
102 signed to it.
103 For example:
105 s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
107 connects to the DHCP server on the localhost via port 7911 (the standard
109 OMAPI port). No authentication is used for the connection.
110 dhcpctl_timed_connect() opens a connection to the DHCP server at the
112 given host and port. If an authenticator has been created for the connec‐
113 tion, then it is given as the 4th argument. On a successful return the
114 address pointed at by the first argument will have a new connection ob‐
115 ject assigned to it. How long the function waits for complete the con‐
116 nection is dictated by the value of the parameter, timeout. If the value
117 is null, it will wait indefinitely Otherwise it will wait for the amount
118 of time specified by timeout (tv_sec:tv_usec). Values of zero for both
119 fields are valid but not recommended. An example is shown below:
120 For example:
122 struct timeval timeout;
124 timeout.tv_sec = 5; /* wait for 5 seconds */
125 timeout.tv_usec = 0;
126 s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL, &timeout);
128 connects to the DHCP server on the localhost via port 7911 (the standard
130 OMAPI port). No authentication is used for the connection. It allows 5
131 seconds for the connect to complete.
132 dhcpctl_disconnect() closes the open connection specified by the first
134 parameter, cxn. Note that this call will free the connection object and
135 cxn will be set to
136 nul. If the second parameter,force, is nonzero, the connection will be
137 closed immediately. Otherwise the receiving end will be shut down but any
138 unsent data will be sent before actually closing the socket. Note that
139 disconnecting only destroys the connection object, any other objects pre‐
140 viously created will still exist.
141 For example:
143 s = dhcpctl_disconnect(&cxn, 1);
145 will close the connection immediately. This funcion should be considered
147 EXPERIMENTAL.
148 dhcpctl_wait_for_completion() flushes a pending message to the server and
150 waits for the response. The result of the request as processed on the
151 server is returned via the second parameter.
152 s = dhcpctl_wait_for_completion(cxn, &wv);
154 if (s != ISC_R_SUCCESS)
155 local_failure(s);
156 else if (wv != ISC_R_SUCCESS)
157 server_failure(wc);
158 The call to dhcpctl_wait_for_completion() won't return until the remote
160 message processing completes or the connection to the server is lost.
161 dhcpctl_timed_wait_for_completion() flushes a pending message to the
163 server and waits for the response. How long the function waits for a re‐
164 sponse is dictated by the value of the third parameter, timeout. If the
165 value is null, it will wait indefinitely or until the connection is lost.
166 Otherwise it will wait for the amount of time specified by timeout
167 (tv_sec:tv_usec). Values of zero for both fields are valid but not recom‐
168 mended. The result of the request as processed on the server is returned
169 via the second parameter. An example is shown below:
170 struct timeval timeout;
173 timeout.tv_sec = 5; /* wait for 5 seconds */
174 timeout.tv_usec = 0;
175 s = dhcpctl_wait_for_completion(cxn, &wv, &timeout);
177 if (s != ISC_R_SUCCESS) {
178 local_failure(s);
179 } else if (wv != ISC_R_SUCCESS) {
180 server_failure(wc);
181 }
182 If the function times out, the status returned will be ISC_R_TIMEDOUT.
184 Please note that even though the function is no longer waiting for a re‐
185 sponse, the server does not abandon the request and may still respond by
186 writing the response to the socket. A subsequent call to either this
187 function or dhcpctl_wait_for_completion() will see that data and read it.
188 Depending on the application logic flow this may or may not be desired.
189 Currently though only mechanism for "flushing" this data is to close the
190 connection by calling disconnet(), and then reconnecting via connect().
191 Please note this function should be considered EXPERIMENTAL.
192 dhcpctl_get_value() extracts a value of an attribute from the handle. The
195 value can be of any length and is treated as a sequence of bytes. The
196 handle must have been created first with dhcpctl_new_object() and opened
197 with dhcpctl_open_object(). The value is returned via the parameter
198 named “value”. The last parameter is the name of attribute to retrieve.
199 dhcpctl_data_string value = NULL;
201 dhcpctl_handle lease;
202 time_t thetime;
203 s = dhcpctl_get_value (&value, lease, "ends");
205 assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
206 memcpy(&thetime, value->value, value->len);
207 dhcpctl_get_boolean() extracts a boolean valued attribute from the object
209 handle.
210 The dhcpctl_set_value(), dhcpctl_set_string_value(),
212 dhcpctl_set_boolean_value(), and dhcpctl_set_int_value() functions all
213 set a value on the object handle.
214 dhcpctl_object_update() function queues a request for all the changes
216 made to the object handle be sent to the remote for processing. The
217 changes made to the attributes on the handle will be applied to remote
218 object if permitted.
219 dhcpctl_object_refresh() queues up a request for a fresh copy of all the
221 attribute values to be sent from the remote to refresh the values in the
222 local object handle.
223 dhcpctl_object_remove() queues a request for the removal on the server of
225 the object referenced by the handle.
226 The dhcpctl_set_callback() function sets up a user-defined function to be
228 called when an event completes on the given object handle. This is needed
229 for asynchronous handling of events, versus the synchronous handling
230 given by dhcpctl_wait_for_completion(). When the function is called the
231 first parameter is the object the event arrived for, the second is the
232 status of the message that was processed, the third is the same value as
233 the second parameter given to dhcpctl_set_callback().
234 The dhcpctl_new_authenticator() creates a new authenticator object to be
236 used for signing the messages that cross over the network. The “name”,
237 “algorithm”, and “secret” values must all match what the server uses and
238 are defined in its configuration file. The created object is returned
239 through the first parameter and must be used as the 4th parameter to
240 dhcpctl_connect(). Note that the 'secret' value must not be base64 en‐
241 coded, which is different from how the value appears in the dhcpd.conf
242 file.
243 dhcpctl_new_object() creates a local handle for an object on the server.
245 The “object_type” parameter is the ascii name of the type of object being
246 accessed. e.g. "lease". This function only sets up local data struc‐
247 tures, it does not queue any messages to be sent to the remote side,
248 dhcpctl_open_object() does that.
249 dhcpctl_open_object() builds and queues the request to the remote side.
251 This function is used with handle created via dhcpctl_new_object(). The
252 flags argument is a bit mask with the following values available for set‐
253 ting:
254 DHCPCTL_CREATE
256 if the object does not exist then the remote will create it
257 DHCPCTL_UPDATE
259 update the object on the remote side using the attributes al‐
260 ready set in the handle.
261 DHCPCTL_EXCL
263 return and error if the object exists and DHCPCTL_CREATE was
264 also specified
265 The omapi_data_string_new() function allocates a new dhcpctl_data_string
267 object. The data string will be large enough to hold “length” bytes of
268 data. The “file” and “lineno” arguments are the source file location the
269 call is made from, typically by using the __FILE__ and __LINE__ macros or
270 the MDL macro defined in
271 dhcpctl_data_string_dereference() deallocates a data string created by
273 omapi_data_string_new(). The memory for the object won't be freed until
274 the last reference is released.
275
277 The following program will connect to the DHCP server running on the lo‐
278 cal host and will get the details of the existing lease for IP address
279 10.0.0.101. It will then print out the time the lease is due to expire.
280 Note that most error checking has been omitted for brevity.
281 #include <sys/time.h>
283 #include <stdio.h>
284 #include <stdlib.h>
285 #include <string.h>
286 #include <stdarg.h>
287 #include <sys/socket.h>
289 #include <netinet/in.h>
290 #include <arpa/inet.h>
291 #include "omapip/result.h"
293 #include "dhcpctl.h"
294 int main (int argc, char **argv) {
296 dhcpctl_data_string ipaddrstring = NULL;
297 dhcpctl_data_string value = NULL;
298 dhcpctl_handle connection = NULL;
299 dhcpctl_handle lease = NULL;
300 isc_result_t waitstatus;
301 struct in_addr convaddr;
302 time_t thetime;
303 dhcpctl_initialize ();
305 dhcpctl_connect (&connection, "127.0.0.1",
307 7911, 0);
308 dhcpctl_new_object (&lease, connection,
310 "lease");
311 memset (&ipaddrstring, 0, sizeof
313 ipaddrstring);
314 inet_pton(AF_INET, "10.0.0.101",
316 &convaddr);
317 omapi_data_string_new (&ipaddrstring,
319 4, MDL);
320 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
321 dhcpctl_set_value (lease, ipaddrstring,
323 "ip-address");
324 dhcpctl_open_object (lease, connection, 0);
326 dhcpctl_wait_for_completion (lease,
328 &waitstatus);
329 if (waitstatus != ISC_R_SUCCESS) {
330 /* server not authoritative */
331 exit (0);
332 }
333 dhcpctl_data_string_dereference(&ipaddrstring,
335 MDL);
336 dhcpctl_get_value (&value, lease, "ends");
338 memcpy(&thetime, value->value, value->len);
340 dhcpctl_data_string_dereference(&value, MDL);
342 fprintf (stdout, "ending time is %s",
344 ctime(&thetime));
345 }
346
348 omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
349 dhclient.conf(5).
350
352 dhcpctl is maintained by ISC. To learn more about Internet Systems Con‐
353 sortium, see
354DHCP 3 Nov 15, 2000 DHCP 3