1DHCPCTL(3)               BSD Library Functions Manual               DHCPCTL(3)
2

NAME

4     dhcpctl_initialize — dhcpctl library initialization.
5

SYNOPSIS

7     #include <dhcpctl/dhcpctl.h>
8
9     dhcpctl_status
10     dhcpctl_initialize(void);
11
12     dhcpctl_status
13     dhcpctl_connect(dhcpctl_handle *cxn, const char *host, int port,
14         dhcpctl_handle auth);
15
16     dhcpctl_status
17     dhcpctl_wait_for_completion(dhcpctl_handle object,
18         dhcpctl_status *status);
19
20     dhcpctl_status
21     dhcpctl_get_value(dhcpctl_data_string *value, dhcpctl_handle object,
22         const char *name);
23
24     dhcpctl_status
25     dhcpctl_get_boolean(int *value, dhcpctl_handle object, const char *name);
26
27     dhcpctl_status
28     dhcpctl_set_value(dhcpctl_handle object, dhcpctl_data_string value,
29         const char *name);
30
31     dhcpctl_status
32     dhcpctl_set_string_value(dhcpctl_handle object, const char *value,
33         const char *name);
34
35     dhcpctl_status
36     dhcpctl_set_boolean_value(dhcpctl_handle object, int value,
37         const char *name);
38
39     dhcpctl_status
40     dhcpctl_set_int_value(dhcpctl_handle object, int value,
41         const char *name);
42
43     dhcpctl_status
44     dhcpctl_object_update(dhcpctl_handle connection, dhcpctl_handle object);
45
46     dhcpctl_status
47     dhcpctl_object_refresh(dhcpctl_handle connection, dhcpctl_handle object);
48
49     dhcpctl_status
50     dhcpctl_object_remove(dhcpctl_handle connection, dhcpctl_handle object);
51
52     dhcpctl_status
53     dhcpctl_set_callback(dhcpctl_handle object, void *data,
54         void (*function) (dhcpctl_handle, dhcpctl_status, void *));
55
56     dhcpctl_status
57     dhcpctl_new_authenticator(dhcpctl_handle *object, const char *name,
58         const char *algorithm, const char *secret, unsigned secret_len);
59
60     dhcpctl_status
61     dhcpctl_new_object(dhcpctl_handle *object, dhcpctl_handle connection,
62         const char *object_type);
63
64     dhcpctl_status
65     dhcpctl_open_object(dhcpctl_handle object, dhcpctl_handle connection,
66         int flags);
67
68     isc_result_t
69     omapi_data_string_new(dhcpctl_data_string, *data, unsigned, int, length,
70         const, char, *filename,, int, lineno);
71
72     isc_result_t
73     dhcpctl_data_string_dereference(dhcpctl_data_string *, const char *,
74         int);
75

DESCRIPTION

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
84     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
87     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
93     For example:
94
95           s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
96
97     connects to the DHCP server on the localhost via port 7911 (the standard
98     OMAPI port). No authentication is used for the connection.
99
100     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
104           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
110     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
113     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
119           dhcpctl_data_string value = NULL;
120           dhcpctl_handle lease;
121           time_t thetime;
122
123           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
127     dhcpctl_get_boolean() extracts a boolean valued attribute from the object
128     handle.
129
130     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
134     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
139     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
143     dhcpctl_object_remove() queues a request for the removal on the server of
144     the object referenced by the handle.
145
146     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
154     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
163     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
169     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
174           DHCPCTL_CREATE
175               if the object does not exist then the remote will create it
176
177           DHCPCTL_UPDATE
178               update the object on the remote side using the attributes
179               already set in the handle.
180
181           DHCPCTL_EXCL
182               return and error if the object exists and DHCPCTL_CREATE was
183               also specified
184
185     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
191     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

EXAMPLES

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
201           #include <sys/time.h>
202           #include <stdio.h>
203           #include <stdlib.h>
204           #include <string.h>
205           #include <stdarg.h>
206
207           #include <sys/socket.h>
208           #include <netinet/in.h>
209           #include <arpa/inet.h>
210
211           #include "omapip/result.h"
212           #include "dhcpctl.h"
213
214           int main (int argc, char **argv) {
215                   dhcpctl_data_string ipaddrstring = NULL;
216                   dhcpctl_data_string value = NULL;
217                   dhcpctl_handle connection = NULL;
218                   dhcpctl_handle lease = NULL;
219                   isc_result_t waitstatus;
220                   struct in_addr convaddr;
221                   time_t thetime;
222
223                   dhcpctl_initialize ();
224
225                   dhcpctl_connect (&connection, "127.0.0.1",
226                                    7911, 0);
227
228                   dhcpctl_new_object (&lease, connection,
229                                       "lease");
230
231                   memset (&ipaddrstring, 0, sizeof
232                           ipaddrstring);
233
234                   inet_pton(AF_INET, "10.0.0.101",
235                             &convaddr);
236
237                   omapi_data_string_new (&ipaddrstring,
238                                          4, MDL);
239                   memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
240
241                   dhcpctl_set_value (lease, ipaddrstring,
242                                      "ip-address");
243
244                   dhcpctl_open_object (lease, connection, 0);
245
246                   dhcpctl_wait_for_completion (lease,
247                                                &waitstatus);
248                   if (waitstatus != ISC_R_SUCCESS) {
249                           /* server not authoritative */
250                           exit (0);
251                   }
252
253                   dhcpctl_data_string_dereference(&ipaddrstring,
254                                                   MDL);
255
256                   dhcpctl_get_value (&value, lease, "ends");
257
258                   memcpy(&thetime, value->value, value->len);
259
260                   dhcpctl_data_string_dereference(&value, MDL);
261
262                   fprintf (stdout, "ending time is %s",
263                            ctime(&thetime));
264           }
265

SEE ALSO

267     omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
268     dhclient.conf(5).
269

AUTHOR

271     dhcpctl was written by Ted Lemon of Nominum, Inc.  This preliminary docu‐
272     mentation was written by James Brister of Nominum, Inc.
273
274DHCP 3                           Nov 15, 2000                           DHCP 3
Impressum