DHCPCTL(3) | Library Functions Manual | DHCPCTL(3) |
NAME¶
dhcpctl_initialize — dhcpctl library initialization.SYNOPSIS¶
#include <dhcpctl/dhcpctl.h> dhcpctl_statusdhcpctl_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 ofisc_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);
s = dhcpctl_wait_for_completion(cxn, &wv); if (s != ISC_R_SUCCESS) local_failure(s); else if (wv != ISC_R_SUCCESS) server_failure(wc);
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_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
__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 ommitted 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 was written by Ted Lemon of Nominum, Inc. This preliminary documentation was written by James Brister of Nominum, Inc.November 15, 2000 | DHCP 3 |