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_wait_for_completion(dhcpctl_handle object,
18 dhcpctl_status *status);
19 dhcpctl_status
21 dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
22 const char *name);
23 dhcpctl_status
25 dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);
26 dhcpctl_status
28 dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
29 const char *name);
30 dhcpctl_status
32 dhcpctl_set_string_value(dhcpctl_handle object, const char *value,
33 const char *name);
34 dhcpctl_status
36 dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
37 const char *name);
38 dhcpctl_status
40 dhcpctl_set_int_value(dhcpctl_handle object, int value,
41 const char *name);
42 dhcpctl_status
44 dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);
45 dhcpctl_status
47 dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);
48 dhcpctl_status
50 dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);
51 dhcpctl_status
53 dhcpctl_set_callback(dhcpctl_handle object, void *data,
54 void (*function) (dhcpctl_handle, dhcpctl_status, void *));
55 dhcpctl_status
57 dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
58 const char *algorithm, const char *secret, unsigned secret_len);
59 dhcpctl_status
61 dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection,
62 const char *object_type);
63 dhcpctl_status
65 dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection,
66 int flags);
67 isc_result_t
69 omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length,
70 const, char, *filename,, int, lineno);
71 isc_result_t
73 dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,
74 int);
75
77 The dhcpctl set of functions provide an API that can be used to communi‐
78 cate with and manipulate a running ISC DHCP server. All functions return
79 a value of isc_result_t. The return values reflects the result of opera‐
80 tions to local data structures. If an operation fails on the server for
81 any reason, then the error result will be returned through the second
82 parameter of the dhcpctl_wait_for_completion() call.
83 dhcpctl_initialize() sets up the data structures the library needs to do
85 its work. This function must be called once before any other.
86 dhcpctl_connect() opens a connection to the DHCP server at the given host
88 and port. If an authenticator has been created for the connection, then
89 it is given as the 4th argument. On a successful return the address
90 pointed at by the first argument will have a new connection object
91 assigned to it.
92 For example:
94 s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
96 connects to the DHCP server on the localhost via port 7911 (the standard
98 OMAPI port). No authentication is used for the connection.
99 dhcpctl_wait_for_completion() flushes a pending message to the server and
101 waits for the response. The result of the request as processed on the
102 server is returned via the second parameter.
103 s = dhcpctl_wait_for_completion(cxn, &wv);
105 if (s != ISC_R_SUCCESS)
106 local_failure(s);
107 else if (wv != ISC_R_SUCCESS)
108 server_failure(wc);
109 The call to dhcpctl_wait_for_completion() won't return until the remote
111 message processing completes or the connection to the server is lost.
112 dhcpctl_get_value() extracts a value of an attribute from the handle. The
114 value can be of any length and is treated as a sequence of bytes. The
115 handle must have been created first with dhcpctl_new_object() and opened
116 with dhcpctl_open_object(). The value is returned via the parameter
117 named “value”. The last parameter is the name of attribute to retrieve.
118 dhcpctl_data_string value = NULL;
120 dhcpctl_handle lease;
121 time_t thetime;
122 s = dhcpctl_get_value (&value, lease, "ends");
124 assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
125 memcpy(&thetime, value->value, value->len);
126 dhcpctl_get_boolean() extracts a boolean valued attribute from the object
128 handle.
129 The dhcpctl_set_value(), dhcpctl_set_string_value(),
131 dhcpctl_set_boolean_value(), and dhcpctl_set_int_value() functions all
132 set a value on the object handle.
133 dhcpctl_object_update() function queues a request for all the changes
135 made to the object handle be be sent to the remote for processing. The
136 changes made to the atributes on the handle will be applied to remote
137 object if permitted.
138 dhcpctl_object_refresh() queues up a request for a fresh copy of all the
140 attribute values to be sent from the remote to refresh the values in the
141 local object handle.
142 dhcpctl_object_remove() queues a request for the removal on the server of
144 the object referenced by the handle.
145 The dhcpctl_set_callback() function sets up a user-defined function to be
147 called when an event completes on the given object handle. This is needed
148 for asynchronous handling of events, versus the synchronous handling
149 given by dhcpctl_wait_for_completion(). When the function is called the
150 first parameter is the object the event arrived for, the second is the
151 status of the message that was processed, the third is the same value as
152 the second parameter given to dhcpctl_set_callback().
153 The dhcpctl_new_authenticator() creates a new authenticator object to be
155 used for signing the messages that cross over the network. The “name”,
156 “algorithm”, and “secret” values must all match what the server uses and
157 are defined in its configuration file. The created object is returned
158 through the first parameter and must be used as the 4th parameter to
159 dhcpctl_connect(). Note that the 'secret' value must not be base64
160 encoded, which is different from how the value appears in the dhcpd.conf
161 file.
162 dhcpctl_new_object() creates a local handle for an object on the the
164 server. The “object_type” parameter is the ascii name of the type of
165 object being accessed. e.g. "lease". This function only sets up local
166 data structures, it does not queue any messages to be sent to the remote
167 side, dhcpctl_open_object() does that.
168 dhcpctl_open_object() builds and queues the request to the remote side.
170 This function is used with handle created via dhcpctl_new_object(). The
171 flags argument is a bit mask with the following values available for set‐
172 ting:
173 DHCPCTL_CREATE
175 if the object does not exist then the remote will create it
176 DHCPCTL_UPDATE
178 update the object on the remote side using the attributes
179 already set in the handle.
180 DHCPCTL_EXCL
182 return and error if the object exists and DHCPCTL_CREATE was
183 also specified
184 The omapi_data_string_new() function allocates a new dhcpctl_data_string
186 object. The data string will be large enough to hold “length” bytes of
187 data. The “file” and “lineno” arguments are the source file location the
188 call is made from, typically by using the __FILE__ and __LINE__ macros or
189 the MDL macro defined in
190 dhcpctl_data_string_dereference() deallocates a data string created by
192 omapi_data_string_new(). The memory for the object won't be freed until
193 the last reference is released.
194
196 The following program will connect to the DHCP server running on the
197 local host and will get the details of the existing lease for IP address
198 10.0.0.101. It will then print out the time the lease is due to expire.
199 Note that most error checking has been ommitted for brevity.
200 #include <stdarg.h>
202 #include <sys/time.h>
203 #include <sys/socket.h>
204 #include <stdio.h>
205 #include <netinet/in.h>
206 #include <isc/result.h>
208 #include <dhcpctl/dhcpctl.h>
209 int main (int argc, char **argv) {
211 dhcpctl_data_string ipaddrstring = NULL;
212 dhcpctl_data_string value = NULL;
213 dhcpctl_handle connection = NULL;
214 dhcpctl_handle lease = NULL;
215 isc_result_t waitstatus;
216 struct in_addr convaddr;
217 time_t thetime;
218 dhcpctl_initialize ();
220 dhcpctl_connect (&connection, "127.0.0.1",
222 7911, 0);
223 dhcpctl_new_object (&lease, connection,
225 "lease");
226 memset (&ipaddrstring, 0, sizeof
228 ipaddrstring);
229 inet_pton(AF_INET, "10.0.0.101",
231 &convaddr);
232 omapi_data_string_new (&ipaddrstring,
234 4, MDL);
235 memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
236 dhcpctl_set_value (lease, ipaddrstring,
238 "ip-address");
239 dhcpctl_open_object (lease, connection, 0);
241 dhcpctl_wait_for_completion (lease,
243 &waitstatus);
244 if (waitstatus != ISC_R_SUCCESS) {
245 /* server not authoritative */
246 exit (0);
247 }
248 dhcpctl_data_string_dereference(&ipaddrstring,
250 MDL);
251 dhcpctl_get_value (&value, lease, "ends");
253 memcpy(&thetime, value->value, value->len);
255 dhcpctl_data_string_dereference(&value, MDL);
257 fprintf (stdout, "ending time is %s",
259 ctime(&thetime));
260 }
261
263 omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
264 dhclient.conf(5).
265
267 dhcpctl was written by Ted Lemon of Nominum, Inc. This preliminary docu‐
268 mentation was written by James Brister of Nominum, Inc.
269DHCP 3 Nov 15, 2000 DHCP 3