[thirdparty/dhcp.git] / dhcpctl / dhcpctl.3

.\" -*- nroff -*-
.\"
.\" Project:      DHCP
.\" File:         dhcpctl.3
.\" RCSId:        $Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp $
.\" 
.\" Copyright (c) 2011 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 2000-2003 by Internet Software Consortium
.\" Copyright (c) 2000 Nominum, Inc.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"   Internet Systems Consortium, Inc.
.\"   950 Charter Street
.\"   Redwood City, CA 94063
.\"   <info@isc.org>
.\"   https://www.isc.org/
.\"     
.\" Description:	dhcpctl man page.
.\" 
.\"
.Dd Nov 15, 2000
.Dt DHCPCTL 3
.Os DHCP 3
.ds vT DHCP Programmer's Manual
.\"
.\"
.\"
.Sh NAME
.Nm dhcpctl_initialize
.Nd dhcpctl library initialization.
.\"
.\"
.\"
.Sh SYNOPSIS
.Fd #include <dhcpctl/dhcpctl.h>
.Ft dhcpctl_status
.Fo dhcpctl_initialize
.Fa void
.Fc
.\"
.Ft dhcpctl_status
.Fo dhcpctl_connect
.Fa "dhcpctl_handle *cxn"
.Fa "const char *host"
.Fa "int port"
.Fa "dhcpctl_handle auth"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_wait_for_completion
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_status *status"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_get_value
.Fa "dhcpctl_data_string *value"
.Fa "dhcpctl_handle object"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_get_boolean
.Fa "int *value"
.Fa "dhcpctl_handle object"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_value
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_data_string value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_string_value
.Fa "dhcpctl_handle object"
.Fa "const char *value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_boolean_value
.Fa "dhcpctl_handle object"
.Fa "int value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_int_value
.Fa "dhcpctl_handle object"
.Fa "int value"
.Fa "const char *name"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_update
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_refresh
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_object_remove
.Fa "dhcpctl_handle connection"
.Fa "dhcpctl_handle object"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_set_callback
.Fa "dhcpctl_handle object"
.Fa "void *data"
.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_new_authenticator
.Fa "dhcpctl_handle *object"
.Fa "const char *name"
.Fa "const char *algorithm"
.Fa "const char *secret"
.Fa "unsigned secret_len"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_new_object
.Fa "dhcpctl_handle *object"
.Fa "dhcpctl_handle connection"
.Fa "const char *object_type"
.Fc
.\"
.\"
.\"
.Ft dhcpctl_status
.Fo dhcpctl_open_object
.Fa "dhcpctl_handle object"
.Fa "dhcpctl_handle connection"
.Fa "int flags"
.Fc
.\"
.\"
.\"
.Ft isc_result_t
.Fo omapi_data_string_new
.Fa dhcpctl_data_string *data
.Fa unsigned int length
.Fa const char *filename,
.Fa int lineno
.Fc
.\"
.\"
.\"
.Ft isc_result_t
.Fo dhcpctl_data_string_dereference
.Fa "dhcpctl_data_string *"
.Fa "const char *"
.Fa "int"
.Fc
.Sh DESCRIPTION
The dhcpctl set of functions provide an API that can be used to communicate
with and manipulate a running ISC DHCP server. All functions return a value of
.Dv isc_result_t .
The return values reflects the result of operations to local data
structures. If an operation fails on the server for any reason, then the error
result will be returned through the
second parameter of the 
.Fn dhcpctl_wait_for_completion 
call.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_initialize
sets up the data structures the library needs to do its work. This function
must be called once before any other.
.Pp
.Fn dhcpctl_connect
opens a connection to the DHCP server at the given host and port. If an
authenticator has been created for the connection, then it is given as the 4th
argument. On a successful return the address pointed at by the first
argument will have a new connection object assigned to it.
.Pp
For example:
.Bd -literal -offset indent
s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
.Ed
.Pp
connects to the DHCP server on the localhost via port 7911 (the standard
OMAPI port). No authentication is used for the connection.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_wait_for_completion
flushes a pending message to the server and waits for the response. The result
of the request as processed on the server is returned via the second
parameter.
.Bd -literal -offset indent
s = dhcpctl_wait_for_completion(cxn, &wv);
if (s != ISC_R_SUCCESS) 
	local_failure(s);
else if (wv != ISC_R_SUCCESS)
	server_failure(wc);
.Ed
.Pp
The call to 
.Fn dhcpctl_wait_for_completion
won't return until the remote message processing completes or the connection
to the server is lost.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_get_value
extracts a value of an attribute from the handle. The value can be of any
length and is treated as a sequence of bytes.  The handle must have been
created first with
.Fn dhcpctl_new_object
and opened with
.Fn dhcpctl_open_object .
The value is returned via the parameter named
.Dq value .
The last parameter is the name of attribute to retrieve.
.Bd -literal -offset indent
dhcpctl_data_string value = NULL;
dhcpctl_handle lease;
time_t thetime;

s = dhcpctl_get_value (&value, lease, "ends");
assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
memcpy(&thetime, value->value, value->len);
.Ed
.\"
.\"
.\"
.Pp
.Fn dhcpctl_get_boolean
extracts a boolean valued attribute from the object handle.
.\"
.\"
.\"
.Pp
The
.Fn dhcpctl_set_value ,
.Fn dhcpctl_set_string_value ,
.Fn dhcpctl_set_boolean_value ,
and
.Fn dhcpctl_set_int_value
functions all set a value on the object handle. 
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_update
function queues a request for
all the changes made to the object handle be be sent to the remote
for processing. The changes made to the atributes on the handle will be
applied to remote object if permitted.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_refresh
queues up a request for a fresh copy of all the attribute values to be sent
from the remote to
refresh the values in the local object handle.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_object_remove
queues a request for the removal on the server of the object referenced by the
handle.
.\"
.\"
.\"
.Pp
The 
.Fn dhcpctl_set_callback
function sets up a user-defined function to be called when an event completes
on the given object handle. This is needed for asynchronous handling of
events, versus the synchronous handling given by
.Fn dhcpctl_wait_for_completion .
When the function is called the first parameter is the object the event
arrived for, the second is the status of the message that was processed, the
third is the same value as the second parameter given to 
.Fn dhcpctl_set_callback .
.\"
.\"
.\"
.Pp
The 
.Fn dhcpctl_new_authenticator
creates a new authenticator object to be used for signing the messages
that cross over the network. The 
.Dq name ,
.Dq algorithm ,
and 
.Dq secret
values must all match what the server uses and are defined in its
configuration file. The created object is returned through the first parameter
and must be used as the 4th parameter to 
.Fn dhcpctl_connect .
Note that the 'secret' value must not be base64 encoded, which is different
from how the value appears in the dhcpd.conf file.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_new_object
creates a local handle for an object on the the server. The 
.Dq object_type
parameter is the ascii name of the type of object being accessed. e.g. 
.Qq lease .
This function only sets up local data structures, it does not queue any 
messages
to be sent to the remote side,
.Fn dhcpctl_open_object
does that.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_open_object
builds and queues the request to the remote side. This function is used with
handle created via
.Fn dhcpctl_new_object .
The flags argument is a bit mask with the following values available for
setting:
.Bl -tag -offset indent -width 20
.It DHCPCTL_CREATE
if the object does not exist then the remote will create it
.It DHCPCTL_UPDATE
update the object on the remote side using the
attributes already set in the handle.
.It DHCPCTL_EXCL
return and error if the object exists and DHCPCTL_CREATE
was also specified
.El
.\"
.\"
.\"
.Pp
The 
.Fn omapi_data_string_new
function allocates a new
.Ft dhcpctl_data_string
object. The data string will be large enough to hold 
.Dq length
bytes of data. The
.Dq file 
and
.Dq lineno
arguments are the source file location the call is made from, typically by
using the 
.Dv __FILE__
and
.Dv __LINE__
macros or the 
.Dv MDL
macro defined in
.
.\"
.\"
.\"
.Pp
.Fn dhcpctl_data_string_dereference
deallocates a data string created by
.Fn omapi_data_string_new .
The memory for the object won't be freed until the last reference is
released.
.Sh EXAMPLES
.Pp 
The following program will connect to the DHCP server running on the local
host and will get the details of the existing lease for IP address
10.0.0.101. It will then print out the time the lease is due to expire. Note
that most error checking has been ommitted for brevity.  
.Bd -literal -offset indent
#include <sys/time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdarg.h>

#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>

#include "omapip/result.h"
#include "dhcpctl.h"

int main (int argc, char **argv) {
	dhcpctl_data_string ipaddrstring = NULL;
	dhcpctl_data_string value = NULL;
	dhcpctl_handle connection = NULL;
	dhcpctl_handle lease = NULL;
	isc_result_t waitstatus;
	struct in_addr convaddr;
	time_t thetime;

        dhcpctl_initialize ();

        dhcpctl_connect (&connection, "127.0.0.1",
			 7911, 0);
	
        dhcpctl_new_object (&lease, connection,
			    "lease");

        memset (&ipaddrstring, 0, sizeof
		ipaddrstring);

        inet_pton(AF_INET, "10.0.0.101",
		  &convaddr);

	omapi_data_string_new (&ipaddrstring,
			       4, MDL);
	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);

	dhcpctl_set_value (lease, ipaddrstring,
			   "ip-address");

	dhcpctl_open_object (lease, connection, 0);

	dhcpctl_wait_for_completion (lease,
				     &waitstatus);
        if (waitstatus != ISC_R_SUCCESS) {
		/* server not authoritative */
		exit (0);
        }

	dhcpctl_data_string_dereference(&ipaddrstring,
					MDL);

        dhcpctl_get_value (&value, lease, "ends");

	memcpy(&thetime, value->value, value->len);

	dhcpctl_data_string_dereference(&value, MDL);

	fprintf (stdout, "ending time is %s",
		 ctime(&thetime));
}
.Ed
.Sh SEE ALSO
omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
.Sh AUTHOR
.Em dhcpctl
was written by Ted Lemon of Nominum, Inc.
This preliminary documentation was written by James Brister of Nominum, Inc.
Commit	Line	Data
45cf20c6 BC	1	.\" -- nroff --
	2	.\"
	3	.\" Project: DHCP
	4	.\" File: dhcpctl.3
fc06ee4f	5	.\" RCSId: $Id: dhcpctl.3,v 1.9 2011/04/25 23:43:16 sar Exp $
45cf20c6	6	.\"
fc06ee4f	7	.\" Copyright (c) 2011 by Internet Systems Consortium, Inc. ("ISC")
a47d6336	8	.\" Copyright (c) 2004,2009 by Internet Systems Consortium, Inc. ("ISC")
98311e4b DH	9	.\" Copyright (c) 2000-2003 by Internet Software Consortium
	10	.\" Copyright (c) 2000 Nominum, Inc.
	11	.\"
	12	.\" Permission to use, copy, modify, and distribute this software for any
	13	.\" purpose with or without fee is hereby granted, provided that the above
	14	.\" copyright notice and this permission notice appear in all copies.
	15	.\"
	16	.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
	17	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	18	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
	19	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	20	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	21	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
	22	.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	23	.\"
	24	.\" Internet Systems Consortium, Inc.
	25	.\" 950 Charter Street
	26	.\" Redwood City, CA 94063
	27	.\" <info@isc.org>
2c85ac9b	28	.\" https://www.isc.org/
45cf20c6 BC	29	.\"
	30	.\" Description: dhcpctl man page.
	31	.\"
	32	.\"
	33	.Dd Nov 15, 2000
	34	.Dt DHCPCTL 3
	35	.Os DHCP 3
	36	.ds vT DHCP Programmer's Manual
	37	.\"
	38	.\"
	39	.\"
	40	.Sh NAME
	41	.Nm dhcpctl_initialize
	42	.Nd dhcpctl library initialization.
	43	.\"
	44	.\"
	45	.\"
	46	.Sh SYNOPSIS
	47	.Fd #include <dhcpctl/dhcpctl.h>
45cf20c6 BC	48	.Ft dhcpctl_status
	49	.Fo dhcpctl_initialize
	50	.Fa void
	51	.Fc
	52	.\"
	53	.Ft dhcpctl_status
	54	.Fo dhcpctl_connect
	55	.Fa "dhcpctl_handle *cxn"
	56	.Fa "const char *host"
	57	.Fa "int port"
	58	.Fa "dhcpctl_handle auth"
	59	.Fc
	60	.\"
	61	.\"
	62	.\"
	63	.Ft dhcpctl_status
	64	.Fo dhcpctl_wait_for_completion
	65	.Fa "dhcpctl_handle object"
	66	.Fa "dhcpctl_status *status"
	67	.Fc
	68	.\"
	69	.\"
	70	.\"
	71	.Ft dhcpctl_status
	72	.Fo dhcpctl_get_value
	73	.Fa "dhcpctl_data_string *value"
	74	.Fa "dhcpctl_handle object"
	75	.Fa "const char *name"
	76	.Fc
	77	.\"
	78	.\"
	79	.\"
	80	.Ft dhcpctl_status
	81	.Fo dhcpctl_get_boolean
	82	.Fa "int *value"
	83	.Fa "dhcpctl_handle object"
	84	.Fa "const char *name"
	85	.Fc
	86	.\"
	87	.\"
	88	.\"
	89	.Ft dhcpctl_status
	90	.Fo dhcpctl_set_value
	91	.Fa "dhcpctl_handle object"
	92	.Fa "dhcpctl_data_string value"
	93	.Fa "const char *name"
	94	.Fc
	95	.\"
	96	.\"
	97	.\"
	98	.Ft dhcpctl_status
	99	.Fo dhcpctl_set_string_value
	100	.Fa "dhcpctl_handle object"
	101	.Fa "const char *value"
	102	.Fa "const char *name"
	103	.Fc
	104	.\"
	105	.\"
	106	.\"
	107	.Ft dhcpctl_status
	108	.Fo dhcpctl_set_boolean_value
	109	.Fa "dhcpctl_handle object"
	110	.Fa "int value"
	111	.Fa "const char *name"
112	.Fc
113	.\"
114	.\"
115	.\"
116	.Ft dhcpctl_status
117	.Fo dhcpctl_set_int_value
118	.Fa "dhcpctl_handle object"
119	.Fa "int value"
120	.Fa "const char *name"
121	.Fc
122	.\"
123	.\"
124	.\"
125	.Ft dhcpctl_status
126	.Fo dhcpctl_object_update
127	.Fa "dhcpctl_handle connection"
128	.Fa "dhcpctl_handle object"
129	.Fc
130	.\"
131	.\"
132	.\"
133	.Ft dhcpctl_status
134	.Fo dhcpctl_object_refresh
135	.Fa "dhcpctl_handle connection"
136	.Fa "dhcpctl_handle object"
137	.Fc
138	.\"
139	.\"
140	.\"
141	.Ft dhcpctl_status
142	.Fo dhcpctl_object_remove
143	.Fa "dhcpctl_handle connection"
144	.Fa "dhcpctl_handle object"
145	.Fc
146	.\"
147	.\"
148	.\"
149	.Ft dhcpctl_status
150	.Fo dhcpctl_set_callback
151	.Fa "dhcpctl_handle object"
152	.Fa "void *data"
153	.Fa "void (function) (dhcpctl_handle, dhcpctl_status, void )"
154	.Fc
155	.\"
156	.\"
157	.\"
158	.Ft dhcpctl_status
159	.Fo dhcpctl_new_authenticator
160	.Fa "dhcpctl_handle *object"
161	.Fa "const char *name"
162	.Fa "const char *algorithm"
163	.Fa "const char *secret"
164	.Fa "unsigned secret_len"
165	.Fc
166	.\"
167	.\"
168	.\"
169	.Ft dhcpctl_status
170	.Fo dhcpctl_new_object
171	.Fa "dhcpctl_handle *object"
172	.Fa "dhcpctl_handle connection"
173	.Fa "const char *object_type"
174	.Fc
175	.\"
176	.\"
177	.\"
178	.Ft dhcpctl_status
179	.Fo dhcpctl_open_object
180	.Fa "dhcpctl_handle object"
181	.Fa "dhcpctl_handle connection"
182	.Fa "int flags"
183	.Fc
184	.\"
185	.\"
186	.\"
187	.Ft isc_result_t
188	.Fo omapi_data_string_new
189	.Fa dhcpctl_data_string *data
190	.Fa unsigned int length
191	.Fa const char *filename,
192	.Fa int lineno
193	.Fc
194	.\"
195	.\"
196	.\"
197	.Ft isc_result_t
198	.Fo dhcpctl_data_string_dereference
199	.Fa "dhcpctl_data_string *"
200	.Fa "const char *"
201	.Fa "int"
202	.Fc
203	.Sh DESCRIPTION
204	The dhcpctl set of functions provide an API that can be used to communicate
205	with and manipulate a running ISC DHCP server. All functions return a value of
206	.Dv isc_result_t .
207	The return values reflects the result of operations to local data
208	structures. If an operation fails on the server for any reason, then the error
209	result will be returned through the
210	second parameter of the
211	.Fn dhcpctl_wait_for_completion
212	call.
213	.\"
214	.\"
215	.\"
216	.Pp
217	.Fn dhcpctl_initialize
218	sets up the data structures the library needs to do its work. This function
219	must be called once before any other.
220	.Pp
221	.Fn dhcpctl_connect
222	opens a connection to the DHCP server at the given host and port. If an
223	authenticator has been created for the connection, then it is given as the 4th
224	argument. On a successful return the address pointed at by the first
225	argument will have a new connection object assigned to it.
226	.Pp
227	For example:
228	.Bd -literal -offset indent
229	s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
230	.Ed
231	.Pp
232	connects to the DHCP server on the localhost via port 7911 (the standard
233	OMAPI port). No authentication is used for the connection.
234	.\"
235	.\"
236	.\"
237	.Pp
238	.Fn dhcpctl_wait_for_completion
239	flushes a pending message to the server and waits for the response. The result
240	of the request as processed on the server is returned via the second
241	parameter.
242	.Bd -literal -offset indent
243	s = dhcpctl_wait_for_completion(cxn, &wv);
244	if (s != ISC_R_SUCCESS)
245	local_failure(s);
246	else if (wv != ISC_R_SUCCESS)
247	server_failure(wc);
248	.Ed
249	.Pp
250	The call to
251	.Fn dhcpctl_wait_for_completion
252	won't return until the remote message processing completes or the connection
253	to the server is lost.
254	.\"
255	.\"
256	.\"
257	.Pp
258	.Fn dhcpctl_get_value
259	extracts a value of an attribute from the handle. The value can be of any
260	length and is treated as a sequence of bytes. The handle must have been
261	created first with
262	.Fn dhcpctl_new_object
263	and opened with
264	.Fn dhcpctl_open_object .
265	The value is returned via the parameter named
266	.Dq value .
267	The last parameter is the name of attribute to retrieve.
268	.Bd -literal -offset indent
269	dhcpctl_data_string value = NULL;
270	dhcpctl_handle lease;
271	time_t thetime;
272
273	s = dhcpctl_get_value (&value, lease, "ends");
274	assert(s == ISC_R_SUCCESS && value->len == sizeof(thetime));
275	memcpy(&thetime, value->value, value->len);
276	.Ed
277	.\"
278	.\"
279	.\"
280	.Pp
281	.Fn dhcpctl_get_boolean
282	extracts a boolean valued attribute from the object handle.
283	.\"
284	.\"
285	.\"
286	.Pp
287	The
288	.Fn dhcpctl_set_value ,
289	.Fn dhcpctl_set_string_value ,
290	.Fn dhcpctl_set_boolean_value ,
291	and
292	.Fn dhcpctl_set_int_value
293	functions all set a value on the object handle.
294	.\"
295	.\"
296	.\"
297	.Pp
298	.Fn dhcpctl_object_update
299	function queues a request for
300	all the changes made to the object handle be be sent to the remote
301	for processing. The changes made to the atributes on the handle will be
302	applied to remote object if permitted.
303	.\"
304	.\"
305	.\"
306	.Pp
307	.Fn dhcpctl_object_refresh
308	queues up a request for a fresh copy of all the attribute values to be sent
309	from the remote to
310	refresh the values in the local object handle.
311	.\"
312	.\"
313	.\"
314	.Pp
315	.Fn dhcpctl_object_remove
316	queues a request for the removal on the server of the object referenced by the
317	handle.
318	.\"
319	.\"
320	.\"
321	.Pp
322	The
323	.Fn dhcpctl_set_callback
324	function sets up a user-defined function to be called when an event completes
325	on the given object handle. This is needed for asynchronous handling of
326	events, versus the synchronous handling given by
327	.Fn dhcpctl_wait_for_completion .
328	When the function is called the first parameter is the object the event
329	arrived for, the second is the status of the message that was processed, the
330	third is the same value as the second parameter given to
331	.Fn dhcpctl_set_callback .
332	.\"
333	.\"
334	.\"
335	.Pp
336	The
337	.Fn dhcpctl_new_authenticator
338	creates a new authenticator object to be used for signing the messages
339	that cross over the network. The
340	.Dq name ,
341	.Dq algorithm ,
342	and
343	.Dq secret
344	values must all match what the server uses and are defined in its
345	configuration file. The created object is returned through the first parameter
346	and must be used as the 4th parameter to
347	.Fn dhcpctl_connect .
98311e4b DH	348	Note that the 'secret' value must not be base64 encoded, which is different
98311e4b DH	349	from how the value appears in the dhcpd.conf file.
45cf20c6 BC	350	.\"
	351	.\"
	352	.\"
	353	.Pp
	354	.Fn dhcpctl_new_object
	355	creates a local handle for an object on the the server. The
	356	.Dq object_type
	357	parameter is the ascii name of the type of object being accessed. e.g.
	358	.Qq lease .
	359	This function only sets up local data structures, it does not queue any
	360	messages
	361	to be sent to the remote side,
	362	.Fn dhcpctl_open_object
	363	does that.
	364	.\"
	365	.\"
	366	.\"
	367	.Pp
	368	.Fn dhcpctl_open_object
	369	builds and queues the request to the remote side. This function is used with
	370	handle created via
	371	.Fn dhcpctl_new_object .
	372	The flags argument is a bit mask with the following values available for
	373	setting:
	374	.Bl -tag -offset indent -width 20
	375	.It DHCPCTL_CREATE
	376	if the object does not exist then the remote will create it
	377	.It DHCPCTL_UPDATE
	378	update the object on the remote side using the
	379	attributes already set in the handle.
	380	.It DHCPCTL_EXCL
	381	return and error if the object exists and DHCPCTL_CREATE
	382	was also specified
	383	.El
	384	.\"
	385	.\"
	386	.\"
	387	.Pp
	388	The
	389	.Fn omapi_data_string_new
	390	function allocates a new
	391	.Ft dhcpctl_data_string
	392	object. The data string will be large enough to hold
	393	.Dq length
	394	bytes of data. The
	395	.Dq file
	396	and
	397	.Dq lineno
	398	arguments are the source file location the call is made from, typically by
	399	using the
	400	.Dv __FILE__
	401	and
	402	.Dv __LINE__
	403	macros or the
	404	.Dv MDL
	405	macro defined in
	406	.
	407	.\"
	408	.\"
	409	.\"
	410	.Pp
	411	.Fn dhcpctl_data_string_dereference
	412	deallocates a data string created by
	413	.Fn omapi_data_string_new .
d758ad8c TL	414	The memory for the object won't be freed until the last reference is
d758ad8c TL	415	released.
45cf20c6 BC	416	.Sh EXAMPLES
	417	.Pp
	418	The following program will connect to the DHCP server running on the local
	419	host and will get the details of the existing lease for IP address
	420	10.0.0.101. It will then print out the time the lease is due to expire. Note
fc06ee4f	421	that most error checking has been ommitted for brevity.
45cf20c6	422	.Bd -literal -offset indent
45cf20c6	423	#include <sys/time.h>
45cf20c6	424	#include <stdio.h>
fc06ee4f SR	425	#include <stdlib.h>
	426	#include <string.h>
	427	#include <stdarg.h>
	428
	429	#include <sys/socket.h>
45cf20c6	430	#include <netinet/in.h>
fc06ee4f	431	#include <arpa/inet.h>
45cf20c6	432
fc06ee4f SR	433	#include "omapip/result.h"
fc06ee4f SR	434	#include "dhcpctl.h"
45cf20c6 BC	435
	436	int main (int argc, char **argv) {
	437	dhcpctl_data_string ipaddrstring = NULL;
	438	dhcpctl_data_string value = NULL;
	439	dhcpctl_handle connection = NULL;
	440	dhcpctl_handle lease = NULL;
	441	isc_result_t waitstatus;
	442	struct in_addr convaddr;
	443	time_t thetime;
	444
	445	dhcpctl_initialize ();
	446
	447	dhcpctl_connect (&connection, "127.0.0.1",
	448	7911, 0);
	449
	450	dhcpctl_new_object (&lease, connection,
	451	"lease");
	452
	453	memset (&ipaddrstring, 0, sizeof
	454	ipaddrstring);
	455
	456	inet_pton(AF_INET, "10.0.0.101",
	457	&convaddr);
	458
	459	omapi_data_string_new (&ipaddrstring,
	460	4, MDL);
	461	memcpy(ipaddrstring->value, &convaddr.s_addr, 4);
	462
	463	dhcpctl_set_value (lease, ipaddrstring,
	464	"ip-address");
	465
	466	dhcpctl_open_object (lease, connection, 0);
	467
	468	dhcpctl_wait_for_completion (lease,
	469	&waitstatus);
	470	if (waitstatus != ISC_R_SUCCESS) {
	471	/* server not authoritative */
	472	exit (0);
	473	}
	474
	475	dhcpctl_data_string_dereference(&ipaddrstring,
	476	MDL);
	477
	478	dhcpctl_get_value (&value, lease, "ends");
	479
	480	memcpy(&thetime, value->value, value->len);
	481
	482	dhcpctl_data_string_dereference(&value, MDL);
	483
	484	fprintf (stdout, "ending time is %s",
	485	ctime(&thetime));
	486	}
	487	.Ed
	488	.Sh SEE ALSO
fac2bbb0	489	omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
98311e4b DH	490	.Sh AUTHOR
	491	.Em dhcpctl
	492	was written by Ted Lemon of Nominum, Inc.
	493	This preliminary documentation was written by James Brister of Nominum, Inc.