-DHCPCTL(3) DHCP Programmer's 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_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 communi
- cate with and manipulate a running ISC DHCP server. All functions return
- a value of isc_result_t. The return values reflects the result of opera
- tions to local data structures. If an operation fails on the server for
- any reason, then the error result will be returned through the second pa
- rameter 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 as
- signed to it.
-
- For example:
-
- s =3D 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 =3D dhcpctl_wait_for_completion(cxn, &wv);
- if (s !=3D ISC_R_SUCCESS)
- local_failure(s);
- else if (wv !=3D 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 =3D NULL;
- dhcpctl_handle lease;
- time_t thetime;
-
- s =3D dhcpctl_get_value (&value, lease, "ends");
- assert(s =3D=3D ISC_R_SUCCESS && value->len =3D=3D 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 be sent to the remote for processing. The
- changes made to the atributes on the handle will be applied to remote ob
- ject 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 giv
- en 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().
-
- dhcpctl_new_object() creates a local handle for an object on the 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 set
- ting:
-
- 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 al
- ready set in the handle.
-
- DHCPCTL_EXCL
- return and error if the object exists and DHCPCTL_CREATE was al
- so 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 compelely
- deallocated until the last reference is released.
-
-EXAMPLES
-
- The following program will connect to the DHCP server running on the lo
- cal 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 =3D NULL;
- dhcpctl_data_string value =3D NULL;
- dhcpctl_handle connection =3D NULL;
- dhcpctl_handle lease =3D 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 !=3D 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-intro(1)
-
- DHCP Nov 15, 2000 5
-
+.\" -*- nroff -*-
+.\"
+.\" Project: DHCP
+.\" File: dhcpctl.3
+.\" RCSId: $Id: dhcpctl.3,v 1.3 2001/04/16 17:44:11 tamino Exp $
+.\"
+.\" Copyright (C) 2000 Nominum, Inc.
+.\"
+.\" Description: dhcpctl man page.
+.\"
+.\"
+.Dd Nov 15, 2000
+.Dt DHCPCTL 3
+.Os DHCP 3
+.ds vT DHCP Programmer's Manual
+.\"
+.\"
+.\"
+.Sh NAME
+.Nm dhcpctl_initialize
+.Nd dhcpctl library initialization.
+.\"
+.\"
+.\"
+.Sh SYNOPSIS
+.Fd #include <dhcpctl/dhcpctl.h>
+.Fd
+.Ft dhcpctl_status
+.Fo dhcpctl_initialize
+.Fa void
+.Fc
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_connect
+.Fa "dhcpctl_handle *cxn"
+.Fa "const char *host"
+.Fa "int port"
+.Fa "dhcpctl_handle auth"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_wait_for_completion
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_status *status"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_get_value
+.Fa "dhcpctl_data_string *value"
+.Fa "dhcpctl_handle object"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_get_boolean
+.Fa "int *value"
+.Fa "dhcpctl_handle object"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_value
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_data_string value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_string_value
+.Fa "dhcpctl_handle object"
+.Fa "const char *value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_boolean_value
+.Fa "dhcpctl_handle object"
+.Fa "int value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_int_value
+.Fa "dhcpctl_handle object"
+.Fa "int value"
+.Fa "const char *name"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_update
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_refresh
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_object_remove
+.Fa "dhcpctl_handle connection"
+.Fa "dhcpctl_handle object"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_set_callback
+.Fa "dhcpctl_handle object"
+.Fa "void *data"
+.Fa "void (*function) (dhcpctl_handle, dhcpctl_status, void *)"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_new_authenticator
+.Fa "dhcpctl_handle *object"
+.Fa "const char *name"
+.Fa "const char *algorithm"
+.Fa "const char *secret"
+.Fa "unsigned secret_len"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_new_object
+.Fa "dhcpctl_handle *object"
+.Fa "dhcpctl_handle connection"
+.Fa "const char *object_type"
+.Fc
+.\"
+.\"
+.\"
+.Ft dhcpctl_status
+.Fo dhcpctl_open_object
+.Fa "dhcpctl_handle object"
+.Fa "dhcpctl_handle connection"
+.Fa "int flags"
+.Fc
+.\"
+.\"
+.\"
+.Ft isc_result_t
+.Fo omapi_data_string_new
+.Fa dhcpctl_data_string *data
+.Fa unsigned int length
+.Fa const char *filename,
+.Fa int lineno
+.Fc
+.\"
+.\"
+.\"
+.Ft isc_result_t
+.Fo dhcpctl_data_string_dereference
+.Fa "dhcpctl_data_string *"
+.Fa "const char *"
+.Fa "int"
+.Fc
+.Sh 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
+.Dv 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
+.Fn dhcpctl_wait_for_completion
+call.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_initialize
+sets up the data structures the library needs to do its work. This function
+must be called once before any other.
+.Pp
+.Fn 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.
+.Pp
+For example:
+.Bd -literal -offset indent
+s = dhcpctl_connect(&cxn, "127.0.0.1", 7911, NULL);
+.Ed
+.Pp
+connects to the DHCP server on the localhost via port 7911 (the standard
+OMAPI port). No authentication is used for the connection.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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.
+.Bd -literal -offset indent
+s = dhcpctl_wait_for_completion(cxn, &wv);
+if (s != ISC_R_SUCCESS)
+ local_failure(s);
+else if (wv != ISC_R_SUCCESS)
+ server_failure(wc);
+.Ed
+.Pp
+The call to
+.Fn dhcpctl_wait_for_completion
+won't return until the remote message processing completes or the connection
+to the server is lost.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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
+.Fn dhcpctl_new_object
+and opened with
+.Fn dhcpctl_open_object .
+The value is returned via the parameter named
+.Dq value .
+The last parameter is the name of attribute to retrieve.
+.Bd -literal -offset indent
+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);
+.Ed
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_get_boolean
+extracts a boolean valued attribute from the object handle.
+.\"
+.\"
+.\"
+.Pp
+The
+.Fn dhcpctl_set_value ,
+.Fn dhcpctl_set_string_value ,
+.Fn dhcpctl_set_boolean_value ,
+and
+.Fn dhcpctl_set_int_value
+functions all set a value on the object handle.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_object_update
+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.
+.\"
+.\"
+.\"
+.Pp
+.Fn 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.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_object_remove
+queues a request for the removal on the server of the object referenced by the
+handle.
+.\"
+.\"
+.\"
+.Pp
+The
+.Fn 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
+.Fn 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
+.Fn dhcpctl_set_callback .
+.\"
+.\"
+.\"
+.Pp
+The
+.Fn dhcpctl_new_authenticator
+creates a new authenticator object to be used for signing the messages
+that cross over the network. The
+.Dq name ,
+.Dq algorithm ,
+and
+.Dq 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
+.Fn dhcpctl_connect .
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_new_object
+creates a local handle for an object on the the server. The
+.Dq object_type
+parameter is the ascii name of the type of object being accessed. e.g.
+.Qq lease .
+This function only sets up local data structures, it does not queue any
+messages
+to be sent to the remote side,
+.Fn dhcpctl_open_object
+does that.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_open_object
+builds and queues the request to the remote side. This function is used with
+handle created via
+.Fn dhcpctl_new_object .
+The flags argument is a bit mask with the following values available for
+setting:
+.Bl -tag -offset indent -width 20
+.It DHCPCTL_CREATE
+if the object does not exist then the remote will create it
+.It DHCPCTL_UPDATE
+update the object on the remote side using the
+attributes already set in the handle.
+.It DHCPCTL_EXCL
+return and error if the object exists and DHCPCTL_CREATE
+was also specified
+.El
+.\"
+.\"
+.\"
+.Pp
+The
+.Fn omapi_data_string_new
+function allocates a new
+.Ft dhcpctl_data_string
+object. The data string will be large enough to hold
+.Dq length
+bytes of data. The
+.Dq file
+and
+.Dq lineno
+arguments are the source file location the call is made from, typically by
+using the
+.Dv __FILE__
+and
+.Dv __LINE__
+macros or the
+.Dv MDL
+macro defined in
+.
+.\"
+.\"
+.\"
+.Pp
+.Fn dhcpctl_data_string_dereference
+deallocates a data string created by
+.Fn omapi_data_string_new .
+The memory for the object won't be compelely deallocated until the last
+reference is released.
+.Sh EXAMPLES
+.Pp
+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.
+.Bd -literal -offset indent
+#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));
+}
+.Ed
+.Sh SEE ALSO
+omapi-intro(1)
projects / thirdparty / dhcp.git / commitdiff
