NAME
SYNOPSIS
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
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
call.
sets up the data structures the library needs to do its work. This function
must be called once before any other.
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.
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
won't return until the remote message processing completes or the connection
to the server is lost.
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
and opened with
The value is returned via the parameter named
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);
extracts a boolean valued attribute from the object handle.
The
and
functions all set a value on the object handle.
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.
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.
queues a request for the removal on the server of the object referenced by the
handle.
The
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
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
The
creates a new authenticator object to be used for signing the messages
that cross over the network. The
and
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
Note that the 'secret' value must not be base64 encoded, which is different
from how the value appears in the dhcpd.conf file.
creates a local handle for an object on the the server. The
parameter is the ascii name of the type of object being accessed. e.g.
This function only sets up local data structures, it does not queue any
messages
to be sent to the remote side,
does that.
builds and queues the request to the remote side. This function is used with
handle created via
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
function allocates a new
object. The data string will be large enough to hold
bytes of data. The
and
arguments are the source file location the call is made from, typically by
using the
and
macros or the
macro defined in
.
deallocates a data string created by
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 ommitted for brevity.
#include <stdarg.h>
#include <sys/time.h>
#include <sys/socket.h>
#include <stdio.h>
#include <netinet/in.h>
#include <isc/result.h>
#include <dhcpctl/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(3), dhcpd(8), dhclient(8), dhcpd.conf(5), dhclient.conf(5).
AUTHOR
was written by Ted Lemon of Nominum, Inc.
This preliminary documentation was written by James Brister of Nominum, Inc.
