DHCPCTL(3)                 DHCP Programmer's Manual                 DHCPCTL(3)

NNAAMMEE
     ddhhccppccttll__iinniittiiaalliizzee - dhcpctl library initialization.

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ddhhccppccttll//ddhhccppccttll..hh>>

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__iinniittiiaalliizzee(_v_o_i_d);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__ccoonnnneecctt(_d_h_c_p_c_t_l___h_a_n_d_l_e _*_c_x_n, _c_o_n_s_t _c_h_a_r _*_h_o_s_t, _i_n_t _p_o_r_t,
             _d_h_c_p_c_t_l___h_a_n_d_l_e _a_u_t_h);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__wwaaiitt__ffoorr__ccoommpplleettiioonn(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t,
             _d_h_c_p_c_t_l___s_t_a_t_u_s _*_s_t_a_t_u_s);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__ggeett__vvaalluuee(_d_h_c_p_c_t_l___d_a_t_a___s_t_r_i_n_g _*_v_a_l_u_e, _d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t,
             _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__ggeett__bboooolleeaann(_i_n_t _*_v_a_l_u_e, _d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__sseett__vvaalluuee(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _d_h_c_p_c_t_l___d_a_t_a___s_t_r_i_n_g _v_a_l_u_e,
             _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__sseett__ssttrriinngg__vvaalluuee(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _c_o_n_s_t _c_h_a_r _*_v_a_l_u_e,
             _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__sseett__bboooolleeaann__vvaalluuee(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _i_n_t _v_a_l_u_e,
             _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__sseett__iinntt__vvaalluuee(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _i_n_t _v_a_l_u_e,
             _c_o_n_s_t _c_h_a_r _*_n_a_m_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__oobbjjeecctt__uuppddaattee(_d_h_c_p_c_t_l___h_a_n_d_l_e _c_o_n_n_e_c_t_i_o_n, _d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__oobbjjeecctt__rreeffrreesshh(_d_h_c_p_c_t_l___h_a_n_d_l_e _c_o_n_n_e_c_t_i_o_n, _d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__oobbjjeecctt__rreemmoovvee(_d_h_c_p_c_t_l___h_a_n_d_l_e _c_o_n_n_e_c_t_i_o_n, _d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__sseett__ccaallllbbaacckk(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _v_o_i_d _*_d_a_t_a,
             _v_o_i_d _(_*_f_u_n_c_t_i_o_n_) _(_d_h_c_p_c_t_l___h_a_n_d_l_e_, _d_h_c_p_c_t_l___s_t_a_t_u_s_, _v_o_i_d _*_));

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__nneeww__aauutthheennttiiccaattoorr(_d_h_c_p_c_t_l___h_a_n_d_l_e _*_o_b_j_e_c_t, _c_o_n_s_t _c_h_a_r _*_n_a_m_e,
             _c_o_n_s_t _c_h_a_r _*_a_l_g_o_r_i_t_h_m, _c_o_n_s_t _c_h_a_r _*_s_e_c_r_e_t, _u_n_s_i_g_n_e_d _s_e_c_r_e_t___l_e_n);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__nneeww__oobbjjeecctt(_d_h_c_p_c_t_l___h_a_n_d_l_e _*_o_b_j_e_c_t, _d_h_c_p_c_t_l___h_a_n_d_l_e _c_o_n_n_e_c_t_i_o_n,
             _c_o_n_s_t _c_h_a_r _*_o_b_j_e_c_t___t_y_p_e);

     _d_h_c_p_c_t_l___s_t_a_t_u_s
     ddhhccppccttll__ooppeenn__oobbjjeecctt(_d_h_c_p_c_t_l___h_a_n_d_l_e _o_b_j_e_c_t, _d_h_c_p_c_t_l___h_a_n_d_l_e _c_o_n_n_e_c_t_i_o_n,
             _i_n_t _f_l_a_g_s);

     _i_s_c___r_e_s_u_l_t___t
     oommaappii__ddaattaa__ssttrriinngg__nneeww(_d_h_c_p_c_t_l___d_a_t_a___s_t_r_i_n_g, _*_d_a_t_a, _u_n_s_i_g_n_e_d, _i_n_t, _l_e_n_g_t_h,
             _c_o_n_s_t, _c_h_a_r, _*_f_i_l_e_n_a_m_e_,, _i_n_t, _l_i_n_e_n_o);

     _i_s_c___r_e_s_u_l_t___t
     ddhhccppccttll__ddaattaa__ssttrriinngg__ddeerreeffeerreennccee(_d_h_c_p_c_t_l___d_a_t_a___s_t_r_i_n_g _*, _c_o_n_s_t _c_h_a_r _*,
             _i_n_t);

DDEESSCCRRIIPPTTIIOONN
     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 ddhhccppccttll__wwaaiitt__ffoorr__ccoommpplleettiioonn() call.

     ddhhccppccttll__iinniittiiaalliizzee() sets up the data structures the library needs to do
     its work. This function must be called once before any other.

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

     ddhhccppccttll__wwaaiitt__ffoorr__ccoommpplleettiioonn() 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 ddhhccppccttll__wwaaiitt__ffoorr__ccoommpplleettiioonn() won't return until the remote
     message processing completes or the connection to the server is lost.

     ddhhccppccttll__ggeett__vvaalluuee() 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 ddhhccppccttll__nneeww__oobbjjeecctt() and opened
     with ddhhccppccttll__ooppeenn__oobbjjeecctt().  The value is returned via the parameter
     named ``value''.  The last parameter is the name of attribute to re-
     trieve.

           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);

     ddhhccppccttll__ggeett__bboooolleeaann() extracts a boolean valued attribute from the object
     handle.

     The ddhhccppccttll__sseett__vvaalluuee(), ddhhccppccttll__sseett__ssttrriinngg__vvaalluuee(),
     ddhhccppccttll__sseett__bboooolleeaann__vvaalluuee(), and ddhhccppccttll__sseett__iinntt__vvaalluuee() functions all
     set a value on the object handle.

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

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

     ddhhccppccttll__oobbjjeecctt__rreemmoovvee() queues a request for the removal on the server of
     the object referenced by the handle.

     The ddhhccppccttll__sseett__ccaallllbbaacckk() 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 ddhhccppccttll__wwaaiitt__ffoorr__ccoommpplleettiioonn().  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 ddhhccppccttll__sseett__ccaallllbbaacckk().

     The ddhhccppccttll__nneeww__aauutthheennttiiccaattoorr() 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
     ddhhccppccttll__ccoonnnneecctt().  Note that the 'secret' value must not be base64 en-
     coded, which is different from how the value appears in the dhcpd.conf
     file.

     ddhhccppccttll__nneeww__oobbjjeecctt() 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, ddhhccppccttll__ooppeenn__oobbjjeecctt() does that.

     ddhhccppccttll__ooppeenn__oobbjjeecctt() builds and queues the request to the remote side.
     This function is used with handle created via ddhhccppccttll__nneeww__oobbjjeecctt().  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 oommaappii__ddaattaa__ssttrriinngg__nneeww() function allocates a new _d_h_c_p_c_t_l___d_a_t_a___s_t_r_i_n_g
     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

     ddhhccppccttll__ddaattaa__ssttrriinngg__ddeerreeffeerreennccee() deallocates a data string created by
     oommaappii__ddaattaa__ssttrriinngg__nneeww().  The memory for the object won't be freed until
     the last reference is released.

EEXXAAMMPPLLEESS
     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 = 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));
           }

SSEEEE AALLSSOO
     omapi(3), omshell(1), dhcpd(8), dhclient(8), dhcpd.conf(5),
     dhclient.conf(5).

AAUUTTHHOORR
     _d_h_c_p_c_t_l was written by Ted Lemon of Nominum, Inc.  This preliminary docu-
     mentation was written by James Brister of Nominum, Inc.

 DHCP                            Nov 15, 2000                                5
