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
communicate with and manipulate a running ISC DHCP server. All functions
return 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 address pointed at by the first
argument will have a new connection object 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 standard 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 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. 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 below:
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 standard OMAPI port). No authentication is used for the connection. It allows 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 considered 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 timeout (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 desired. 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 EXPERIMENTAL.
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 parameter 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 object 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 handling 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 parameter 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
remote 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 already 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 until 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 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 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 https://www.isc.org
November 15, 2000 | DHCP 3 |