Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DHCPCTL(3)		    Library Functions Manual		    DHCPCTL(3)

NAME
       dhcpctl_initialize -- dhcpctl library initialization.

SYNOPSIS
       #include	<dhcpctl/dhcpctl.h>

       dhcpctl_status
       dhcpctl_initialize(void);

       dhcpctl_status
       dhcpctl_connect(dhcpctl_handle *cxn,	const char *host,    int port,
	   dhcpctl_handle auth);

       dhcpctl_status
       dhcpctl_timed_connect(dhcpctl_handle *cxn, const	char *host,  int port,
	   dhcpctl_handle auth,	dhcpctl_status *status);

       dhcpctl_status
       dhcpctl_disconnect(dhcpctl_handle *cxn, int force);

       dhcpctl_status
       dhcpctl_wait_for_completion(dhcpctl_handle object,
	   dhcpctl_status *status);

       dhcpctl_status
       dhcpctl_timed_wait_for_completion(dhcpctl_handle	object,
	   dhcpctl_status *status, struct timeval *timeout);

       dhcpctl_status
       dhcpctl_get_value(dhcpctl_data_string *value,	dhcpctl_handle object,
	   const char *name);

       dhcpctl_status
       dhcpctl_get_boolean(int *value,			dhcpctl_handle object,
	   const char *name);

       dhcpctl_status
       dhcpctl_set_value(dhcpctl_handle	object,	    dhcpctl_data_string	value,
	   const char *name);

       dhcpctl_status
       dhcpctl_set_string_value(dhcpctl_handle object,	    const char *value,
	   const char *name);

       dhcpctl_status
       dhcpctl_set_boolean_value(dhcpctl_handle	object,		    int	value,
	   const char *name);

       dhcpctl_status
       dhcpctl_set_int_value(dhcpctl_handle object,		    int	value,
	   const char *name);

       dhcpctl_status
       dhcpctl_object_update(dhcpctl_handle connection,
	   dhcpctl_handle object);

       dhcpctl_status
       dhcpctl_object_refresh(dhcpctl_handle connection,
	   dhcpctl_handle object);

       dhcpctl_status
       dhcpctl_object_remove(dhcpctl_handle connection,
	   dhcpctl_handle object);

       dhcpctl_status
       dhcpctl_set_callback(dhcpctl_handle object,		   void	*data,
	   void	(*function) (dhcpctl_handle, dhcpctl_status, void *));

       dhcpctl_status
       dhcpctl_new_authenticator(dhcpctl_handle	*object,     const char	*name,
	   const char *algorithm, const	char *secret, unsigned secret_len);

       dhcpctl_status
       dhcpctl_new_object(dhcpctl_handle *object,   dhcpctl_handle connection,
	   const char *object_type);

       dhcpctl_status
       dhcpctl_open_object(dhcpctl_handle object,   dhcpctl_handle connection,
	   int flags);

       isc_result_t
       omapi_data_string_new(dhcpctl_data_string,    *data,   unsigned,	  int,
	   length, const, char,	*filename,, int, lineno);

       isc_result_t
       dhcpctl_data_string_dereference(dhcpctl_data_string *,	 const char *,
	   int);

DESCRIPTION
       The  dhcpctl set	of functions provide an	API that can be	used to	commu-
       nicate with and manipulate a running ISC	DHCP server. All functions re-
       turn a value of 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 dhcpctl_wait_for_completion() call.

       dhcpctl_initialize() sets up the	data structures	the library  needs  to
       do its work. This function must be called once before any other.

       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  ad-
       dress  pointed  at by the first argument	will have a new	connection ob-
       ject assigned to	it.

       For example:

	     s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);

       connects	to the DHCP server on the localhost via	port 7911  (the	 stan-
       dard OMAPI port). No authentication is used for the connection.

       dhcpctl_timed_connect()	opens  a  connection to	the DHCP server	at the
       given host and port. If an authenticator	has been created for the  con-
       nection,	 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.  How long	the function waits  for	 complete  the
       connection  is  dictated	by the value of	the parameter, timeout.	If the
       value is	null, it will wait indefinitely	Otherwise it will wait for the
       amount of time specified	by timeout (tv_sec:tv_usec).  Values  of  zero
       for both	fields are valid but not recommended.  An example is shown be-
       low:

       For example:

	     struct timeval timeout;
	     timeout.tv_sec = 5;   /* wait for 5 seconds */
	     timeout.tv_usec = 0;

	     s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL,	&timeout);

       connects	 to  the DHCP server on	the localhost via port 7911 (the stan-
       dard OMAPI port). No authentication is used for the connection.	It al-
       lows 5 seconds for the connect to complete.

       dhcpctl_disconnect() closes the open connection specified by the	 first
       parameter,  cxn.	  Note	that this call will free the connection	object
       and cxn will be set to
	nul.  If the second parameter,force, is	nonzero, the  connection  will
       be  closed  immediately.	 Otherwise the receiving end will be shut down
       but any unsent data will	be sent	before actually	 closing  the  socket.
       Note  that disconnecting	only destroys the connection object, any other
       objects previously created will still exist.

       For example:

	     s = dhcpctl_disconnect(&cxn, 1);

       will close the connection immediately.  This funcion should be  consid-
       ered EXPERIMENTAL.

       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.

	     s = dhcpctl_wait_for_completion(cxn, &wv);
	     if	(s != ISC_R_SUCCESS)
		     local_failure(s);
	     else if (wv != ISC_R_SUCCESS)
		     server_failure(wc);

       The call	to dhcpctl_wait_for_completion() won't return until the	remote
       message processing completes or the connection to the server is lost.

       dhcpctl_timed_wait_for_completion()  flushes  a	pending	message	to the
       server and waits	for the	response.  How long the	function waits	for  a
       response	 is  dictated by the value of the third	parameter, timeout. If
       the value is null, it will wait indefinitely or until the connection is
       lost. Otherwise it will wait for	the amount of time specified by	 time-
       out  (tv_sec:tv_usec). Values of	zero for both fields are valid but not
       recommended.  The result	of the request as processed on the  server  is
       returned	via the	second parameter.  An example is shown below:

	     struct timeval timeout;
	     timeout.tv_sec = 5;   /* wait for 5 seconds */
	     timeout.tv_usec = 0;

	     s = dhcpctl_wait_for_completion(cxn, &wv, &timeout);
	     if	(s != ISC_R_SUCCESS) {
		     local_failure(s);
	     } else if (wv != ISC_R_SUCCESS) {
		     server_failure(wc);
	     }

       If  the function	times out, the status returned will be ISC_R_TIMEDOUT.
       Please note that	even though the	function is no longer  waiting	for  a
       response, the server does not abandon the request and may still respond
       by writing the response to the socket. A	subsequent call	to either this
       function	 or  dhcpctl_wait_for_completion() will	see that data and read
       it. Depending on	the application	logic flow this	may or may not be  de-
       sired.	Currently though only mechanism	for "flushing" this data is to
       close the connection by calling disconnet(), and	then reconnecting  via
       connect().   Please  note this function should be considered EXPERIMEN-
       TAL.

       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  dhcpctl_new_object()  and
       opened with dhcpctl_open_object().  The value is	returned via the para-
       meter  named  "value".	The last parameter is the name of attribute to
       retrieve.

	     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);

       dhcpctl_get_boolean() extracts a	boolean	valued attribute from the  ob-
       ject handle.

       The	     dhcpctl_set_value(),	   dhcpctl_set_string_value(),
       dhcpctl_set_boolean_value(), and	dhcpctl_set_int_value()	functions  all
       set a value on the object handle.

       dhcpctl_object_update()	function  queues a request for all the changes
       made to the object handle be sent to the	 remote	 for  processing.  The
       changes	made to	the attributes on the handle will be applied to	remote
       object if permitted.

       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.

       dhcpctl_object_remove() queues a	request	for the	removal	on the	server
       of the object referenced	by the handle.

       The  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 han-
       dling  given  by	 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 dhcpctl_set_callback().

       The dhcpctl_new_authenticator() creates a new authenticator  object  to
       be  used	 for  signing  the  messages  that cross over the network. The
       "name", "algorithm", and	"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 para-
       meter to	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.

       dhcpctl_new_object() creates a  local  handle  for  an  object  on  the
       server.	The  "object_type"  parameter is the ascii name	of the type of
       object being accessed. e.g.  "lease".  This function only sets up local
       data structures,	it does	not queue any messages to be sent to  the  re-
       mote side, dhcpctl_open_object()	does that.

       dhcpctl_open_object() builds and	queues the request to the remote side.
       This  function  is  used	 with handle created via dhcpctl_new_object().
       The flags argument is a bit mask	with the  following  values  available
       for setting:

	     DHCPCTL_CREATE
		 if the	object does not	exist then the remote will create it

	     DHCPCTL_UPDATE
		 update	the object on the remote side using the	attributes al-
		 ready set in the handle.

	     DHCPCTL_EXCL
		 return	 and error if the object exists	and DHCPCTL_CREATE was
		 also specified

       The    omapi_data_string_new()	  function     allocates     a	   new
       dhcpctl_data_string  object.  The  data	string will be large enough to
       hold "length" bytes of data. The	"file" and "lineno" arguments are  the
       source  file  location  the  call  is made from,	typically by using the
       __FILE__	and __LINE__ macros or the MDL macro defined in

       dhcpctl_data_string_dereference() deallocates a data string created  by
       omapi_data_string_new().	  The memory for the object won't be freed un-
       til the last reference is released.

EXAMPLES
       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 ad-
       dress 10.0.0.101. It will then print out	the time the lease is  due  to
       expire. Note that most error checking has been omitted for brevity.

	     #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));
	     }

SEE ALSO
       omapi(3),    omshell(1),	   dhcpd(8),	dhclient(8),	dhcpd.conf(5),
       dhclient.conf(5).

AUTHOR
       dhcpctl is maintained by	ISC.  To learn	more  about  Internet  Systems
       Consortium, see

DHCP 3				 Nov 15, 2000			    DHCPCTL(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dhcpctl&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help