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_wait_for_completion
(
dhcpctl_handle
object,
dhcpctl_status *status);
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_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_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