dhcpctl*()

Description:

The dhcpctl*() set of functions provides an API that you can use to communicate with and manipulate a running ISC DHCP server. All functions return a value of type isc_result_t or dhcpctl_status; these types are equivalent. 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 is 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. You must call this function once before calling any of the others.

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's given as the fourth argument. On a successful return, the address pointed at by the first argument has 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() doesn'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 value parameter. 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.

dhcpctl_set_value(), dhcpctl_set_string_value(), dhcpctl_set_boolean_value(), dhcpctl_set_int_value()

Set a value on the object handle.

dhcpctl_object_update()

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 attributes on the handle are 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.

dhcpctl_set_callback()

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().

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 fourth 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 doesn't 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 bitmask with the following values available for setting:

DHCPCTL_CREATE

If the object doesn't exist, then the remote creates it.

DHCPCTL_UPDATE

Update the object on the remote side using the attributes already set in the handle.

DHCPCTL_EXCL

Return an error if the object exists and DHCPCTL_CREATE was also specified.

omapi_data_string_new()

Allocates a new dhcpctl_data_string object. The data string is 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. Some of the OMAPI code uses an MDL macro, but it isn't defined in a public header. If you want to use MDL, you can define it as:

#define MDL __FILE__, __LINE__

dhcpctl_data_string_dereference()

Deallocates a data string created by omapi_data_string_new(). The memory for the object isn't be freed until the last reference is released.

Examples:

The following program connects to the DHCP server running on the local host and gets the details of the existing lease for IP address 10.0.0.101. It then prints the time the lease is due to expire. Note that most error checking has been omitted for brevity.

#include <stdarg.h>
#include <sys/time.h>
#include <sys/socket.h>
#include <stdio.h>
#include <netinet/in.h>

#include <isc-dhcp/result.h>
#include <dhcp/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));
}

Classification:

NetBSD

Contributing author:

dhcpctl*() was written by Ted Lemon of Nominum, Inc. The preliminary documentation was written by James Brister of Nominum, Inc.