Home | History | Annotate | Line # | Download | only in doc
api+protocol revision 1.1
      1  1.1  christos This file documents the protocol that the ISC DHCP server and ISC
      2  1.1  christos Object Management clients (clients that use the ISC Object Management
      3  1.1  christos API) speak between one another.
      4  1.1  christos 
      5  1.1  christos Protocol:
      6  1.1  christos 
      7  1.1  christos All multi-byte numbers are represented in network byte order.
      8  1.1  christos 
      9  1.1  christos On startup, each side sends a status message indicating what version
     10  1.1  christos of the protocol they are speaking.   The status message looks like
     11  1.1  christos this:
     12  1.1  christos 
     13  1.1  christos +---------+---------+
     14  1.1  christos | version | hlength |
     15  1.1  christos +---------+---------+
     16  1.1  christos 
     17  1.1  christos version - a 32-bit fixed-point number with the decimal point between
     18  1.1  christos 	  the third and second decimal digits from the left,
     19  1.1  christos 	  representing the version of the protocol.   The current
     20  1.1  christos 	  protocol version is 1.00.   If the field were considered as
     21  1.1  christos 	  a 32-bit integer, this would correspond to a value of 100
     22  1.1  christos 	  decimal, or 0x64.
     23  1.1  christos 
     24  1.1  christos hlength - a 32-bit integer representing the length of the fixed-length
     25  1.1  christos 	  header in subsequent messages.   This is normally 56, but
     26  1.1  christos 	  can be changed to a value larger than 56 by either side
     27  1.1  christos 	  without upgrading the revision number.
     28  1.1  christos 
     29  1.1  christos 
     30  1.1  christos The startup message is not authenticated.   Either side may reject the
     31  1.1  christos other side's startup message as invalid by simply closing the
     32  1.1  christos connection.   The only fixed part of the startup message is the
     33  1.1  christos version number - future versions may delete hlength, or add further
     34  1.1  christos startup information.
     35  1.1  christos 
     36  1.1  christos Following the startup message, all messages have the same format.
     37  1.1  christos Currently, the format includes a fixed-length header (the length in
     38  1.1  christos hlength, above)
     39  1.1  christos 
     40  1.1  christos +--------+----+--------+----+-----+---------+------------+------------+-----+
     41  1.1  christos | authid | op | handle | id | rid | authlen | msg values | obj values | sig |
     42  1.1  christos +--------+----+--------+----+-----+---------+------------+------------+-----+
     43  1.1  christos 
     44  1.1  christos The fixed-length header consists of:
     45  1.1  christos 
     46  1.1  christos authid = a 32-bit authenticator handle.
     47  1.1  christos 	For an original message (one not in response to some other
     48  1.1  christos 	message), this will be chosen by the originator.   For a
     49  1.1  christos 	message in response to another message, the authenticator for
     50  1.1  christos 	that message is used, except if the response is an error
     51  1.1  christos 	message indicating that the authenticator used was unknown,
     52  1.1  christos 	in which case the null authenticator is used.   Messages that
     53  1.1  christos 	are generated as the result of a notify registration use the
     54  1.1  christos 	authenticator used in the original notify registration.
     55  1.1  christos 	The authenticator itself is generated by having one side of
     56  1.1  christos 	the connection send an object of type "authenticator" to the
     57  1.1  christos 	other side with values that indicate what kind of
     58  1.1  christos 	authentication mechanism to use and what key to use.   The two
     59  1.1  christos 	most likely things here are a Kerberos V principal name or the
     60  1.1  christos 	name of a shared secret that can be used to calculate an MD5
     61  1.1  christos 	hash.   The mechanism for doing this has yet to be finalized.
     62  1.1  christos 	If authid is zero, the message is not authenticated.
     63  1.1  christos 
     64  1.1  christos op = 32-bit opcode, one of:
     65  1.1  christos 	open = 1
     66  1.1  christos 	refresh = 2
     67  1.1  christos 	update = 3
     68  1.1  christos 	notify = 4
     69  1.1  christos 	error = 5
     70  1.1  christos 	delete = 6
     71  1.1  christos handle = 32-bit object handle
     72  1.1  christos 	A handle on the object being opened, created, refreshed or
     73  1.1  christos 	updated.   If no handle is yet available (e.g., with open and
     74  1.1  christos 	new), then the value zero is sent.
     75  1.1  christos id = 32-bit transaction id of the message - a monotonically increasing
     76  1.1  christos      number that starts with some randomly chosen number at the
     77  1.1  christos      beginning of the life of the connection.   The value should never
     78  1.1  christos      be zero.
     79  1.1  christos rid = 32-bit transaction ID of the message to which this message is a
     80  1.1  christos       response, or zero if this message is not in response to a
     81  1.1  christos       message from the other side.
     82  1.1  christos 
     83  1.1  christos authlen = a 32-bit number representing the length of the authenticator
     84  1.1  christos 
     85  1.1  christos msg values = a series of name+value pairs, specific to this message.
     86  1.1  christos 	 Each name+value pair starts with a 16-bit name length,
     87  1.1  christos 	 followed by that many bytes of name, followed by a 32-bit
     88  1.1  christos 	 value length, followed by that many bytes of value.   If the
     89  1.1  christos 	 length is zero, this is a value of the blank string.   If the
     90  1.1  christos 	 length is all ones (2^32-1), then there is no value - for an
     91  1.1  christos 	 update, this means the value for this name and the name
     92  1.1  christos 	 itself should be deleted from the object, which may or may
     93  1.1  christos 	 not be possible.   The list of name/value pairs ends with a
     94  1.1  christos 	 zero-length name, which is not followed by a value
     95  1.1  christos 	 length/value pair.
     96  1.1  christos 
     97  1.1  christos obj values = a series of name+value pairs, as above, specific to the
     98  1.1  christos 	object being created, updated or refreshed.
     99  1.1  christos 
    100  1.1  christos signature = authlen bytes of data signing the message.   The signature
    101  1.1  christos 	    algorithm is a property of the authenticator handle.
    102  1.1  christos 
    103  1.1  christos Message types:
    104  1.1  christos 
    105  1.1  christos 1: open
    106  1.1  christos    relevant input values:
    107  1.1  christos 	object-type = the name of the type of object
    108  1.1  christos 	open:create = boolean - create the object if it doesn't yet exist
    109  1.1  christos 	open:exclusive = boolean - don't open the object if it does exist
    110  1.1  christos 	open:update = boolean - update the object with included values
    111  1.1  christos 		      if it matches.
    112  1.1  christos 	the handle should always be the null handle
    113  1.1  christos 
    114  1.1  christos    The input value must also contain key information for the type of
    115  1.1  christos    object being searched that uniquely identifies an object, or search
    116  1.1  christos    information that matches only one object.  Each object has a key
    117  1.1  christos    specification (a key is something that uniquely identifies an
    118  1.1  christos    object), so see the key specification for that object to see
    119  1.1  christos    what to send here.   An open message with the create flag set must
    120  1.1  christos    specify a key, and not merely matching criteria.   Some objects may
    121  1.1  christos    allow more than one key, and it may be that the union of those keys
    122  1.1  christos    is required to uniquely identify the object, or it may be that any
    123  1.1  christos    one such key will uniquely identify the object.   The documentation
    124  1.1  christos    for the type of object will specify this.
    125  1.1  christos 
    126  1.1  christos    An open message will result in an immediate response message whose
    127  1.1  christos    opcode will either be "error" or "update".   The error message may
    128  1.1  christos    include an error:reason value containing a text string explaining
    129  1.1  christos    the error, and will always include an error:code value which will
    130  1.1  christos    be the numeric error code for what went wrong.   Possible error
    131  1.1  christos    codes are:
    132  1.1  christos 
    133  1.1  christos 	not found - no such object exists
    134  1.1  christos 	already exists - object already exists, and exclusive flag was
    135  1.1  christos 			 set.
    136  1.1  christos 	not unique - more than one object matching the specification
    137  1.1  christos 		     exists.
    138  1.1  christos 	permission denied - the authenticator ID specified does not
    139  1.1  christos 			    have authorization to access this object,
    140  1.1  christos 			    or if the update flag was specified, to
    141  1.1  christos 			    update the object.
    142  1.1  christos 
    143  1.1  christos    If the response is an update message, the update message will
    144  1.1  christos    include the object handle and all of the name/value pairs
    145  1.1  christos    associated with that object.
    146  1.1  christos 
    147  1.1  christos 2: refresh
    148  1.1  christos 
    149  1.1  christos    no input values except the handle need be specified.   The null
    150  1.1  christos    handle may not be specified.   If the handle is valid, and the
    151  1.1  christos    authenticator ID specified has permission to examine the object,
    152  1.1  christos    then an update message will be sent for that object.   Otherwise,
    153  1.1  christos    one of the following errors will be sent:
    154  1.1  christos 
    155  1.1  christos 	invalid handle - the handle does not refer to a known object
    156  1.1  christos 	permisson denied - the handle refers to an object that the
    157  1.1  christos 			   requestor does not have permission to
    158  1.1  christos 			   examine. 
    159  1.1  christos 
    160  1.1  christos 3: update
    161  1.1  christos 
    162  1.1  christos    Requests that the contents of the specified object be updated with
    163  1.1  christos    the values included.   Values that are not specified are not
    164  1.1  christos    updated.   The response will be either an error message or an
    165  1.1  christos    update-ok message.   If rid is nonzero, no response will be
    166  1.1  christos    generated, even if there was an error.   Possible errors include:
    167  1.1  christos 
    168  1.1  christos 	invalid handle - no such object was found
    169  1.1  christos 	permission denied - the handle refers to an object that the
    170  1.1  christos 			    requestor does not have permission to
    171  1.1  christos 			    modify.
    172  1.1  christos 	not confirmed - the update could not be committed due to some
    173  1.1  christos 			kind of resource problem, for example
    174  1.1  christos 			insufficient memory or a disk failure.
    175  1.1  christos 
    176  1.1  christos 4: notify
    177  1.1  christos 
    178  1.1  christos    Requests that whenever the object with the specified handle is
    179  1.1  christos    modified, an update be sent.   If there is something wrong with the
    180  1.1  christos    request, an error message will be returned immediately.
    181  1.1  christos    Otherwise, whenever a change is made to the object, an update
    182  1.1  christos    message will be sent containing whatever changes were made (or
    183  1.1  christos    possibly all the values associated with the object, depending on
    184  1.1  christos    the implementation).   Possible errors:
    185  1.1  christos 
    186  1.1  christos 	invalid handle
    187  1.1  christos 	permission denied - the handle refers to an object that the
    188  1.1  christos 			    requestor does not have permission to
    189  1.1  christos 			    examine.
    190  1.1  christos 	not supported - the object implementation does not support
    191  1.1  christos 			notifications
    192  1.1  christos 
    193  1.1  christos 5: status
    194  1.1  christos 
    195  1.1  christos    Sends a status code in response to a message.  Always sent in
    196  1.1  christos    response to a message sent by the other side.  There should never
    197  1.1  christos    be a response to this message.
    198  1.1  christos 
    199  1.1  christos 6: delete
    200  1.1  christos 
    201  1.1  christos    Deletes the specified object.   Response will be either request-ok,
    202  1.1  christos    or error.   Possible errors include:
    203  1.1  christos 
    204  1.1  christos 	invalid handle - no such object was found
    205  1.1  christos 	permission denied - the handle refers to an object that the
    206  1.1  christos 			    requestor does not have permission to
    207  1.1  christos 			    modify.
    208  1.1  christos 	not confirmed - the deletion could not be committed due to
    209  1.1  christos 			some kind of resource problem, for example
    210  1.1  christos 			insufficient memory or a disk failure.
    211  1.1  christos 
    212  1.1  christos 7: notify-cancel
    213  1.1  christos 
    214  1.1  christos    Like notify, but requests that an existing notification be cancelled.
    215  1.1  christos 
    216  1.1  christos 8: notify-cancelled
    217  1.1  christos 
    218  1.1  christos    Indicates that because of a local change, a notification that had
    219  1.1  christos    been registered can no longer be performed.   This could be as a
    220  1.1  christos    result of the permissions on a object changing, or an object being
    221  1.1  christos    deleted.   There should never be a response to this message.
    222  1.1  christos 
    223  1.1  christos internals:
    224  1.1  christos 
    225  1.1  christos Both client and server use same protocol and infrastructure.   There
    226  1.1  christos are many object types, each of which is stored in a registry.
    227  1.1  christos Objects whose type is not recognized can either be handled by the
    228  1.1  christos generic object type, which is registered with the type "*".   If no
    229  1.1  christos generic object type is registered, then objects with unknown types are
    230  1.1  christos simply not supported.   On the client, there are probably no special
    231  1.1  christos object handlers (although this is by no means forbidden).   On the
    232  1.1  christos server, probably everything is a special object.
    233  1.1  christos 
    234  1.1  christos Each object type has the following methods:
    235  1.1  christos 
    236  1.1  christos 
    237  1.1  christos 
    238  1.1  christos 
    239  1.1  christos dhcpctl_status dhcpctl_connect (dhcpctl_handle *connection,
    240  1.1  christos 				char *server_name, int port,
    241  1.1  christos 				dhcpctl_handle *authinfo)
    242  1.1  christos 	synchronous
    243  1.1  christos 	returns nonzero status code if it didn't connect, zero otherwise
    244  1.1  christos 	stores connection handle through connection, which can be used
    245  1.1  christos 	for subsequent access to the specified server. 
    246  1.1  christos 	server_name is the name of the server, and port is the TCP
    247  1.1  christos 	port on which it is listening.
    248  1.1  christos 	authinfo is the handle to an object containing authentication
    249  1.1  christos 	information.
    250  1.1  christos 
    251  1.1  christos dhcpctl_status dhcpctl_open_object (dhcpctl_handle h,
    252  1.1  christos 				    dhcpctl_handle connection,
    253  1.1  christos 				    int flags)
    254  1.1  christos 	asynchronous - just queues the request
    255  1.1  christos 	returns nonzero status code if open couldn't be queued
    256  1.1  christos 	returns zero if open was queued
    257  1.1  christos 	h is a handle to an object created by dhcpctl_new_object
    258  1.1  christos 	connection is a connection to a DHCP server
    259  1.1  christos 	flags include:
    260  1.1  christos 	   DHCPCTL_CREATE - if the object doesn't exist, create it
    261  1.1  christos 	   DHCPCTL_UPDATE - update the object on the server using the
    262  1.1  christos 			    attached parameters 
    263  1.1  christos 	   DHCPCTL_EXCL - error if the object exists and DHCPCTL_CREATE
    264  1.1  christos 			  was also specified
    265  1.1  christos 
    266  1.1  christos dhcpctl_status dhcpctl_new_object (dhcpctl_handle *h,
    267  1.1  christos 				   dhcpctl_handle connection,
    268  1.1  christos 				   char *object_type)
    269  1.1  christos 	synchronous - creates a local handle for a host entry.
    270  1.1  christos 	returns nonzero status code if the local host entry couldn't
    271  1.1  christos 	be created
    272  1.1  christos 	stores handle to host through h if successful, and returns zero.
    273  1.1  christos 	object_type is a pointer to a NUL-terminated string containing
    274  1.1  christos 	the ascii name of the type of object being accessed - e.g., "host"
    275  1.1  christos 
    276  1.1  christos dhcpctl_status dhcpctl_set_callback (dhcpctl_handle h, void *data,
    277  1.1  christos 				     void (*callback) (dhcpctl_handle,
    278  1.1  christos 						       dhcpctl_status, void *))
    279  1.1  christos 	synchronous, with asynchronous aftereffect
    280  1.1  christos 	handle is some object upon which some kind of process has been
    281  1.1  christos 	started - e.g., an open, an update or a refresh.
    282  1.1  christos 	data is an anonymous pointer containing some information that
    283  1.1  christos 	the callback will use to figure out what event completed.
    284  1.1  christos 	return value of 0 means callback was successfully set, a nonzero
    285  1.1  christos 	status code is returned otherwise.
    286  1.1  christos 	Upon completion of whatever task is in process, the callback
    287  1.1  christos 	will be passed the handle to the object, a status code
    288  1.1  christos 	indicating what happened, and the anonymous pointer passed to 
    289  1.1  christos 
    290  1.1  christos dhcpctl_status dhcpctl_wait_for_completion (dhcpctl_handle h,
    291  1.1  christos 					    dhcpctl_status *s)
    292  1.1  christos 	synchronous
    293  1.1  christos 	returns zero if the callback completes, a nonzero status if
    294  1.1  christos 	there was some problem relating to the wait operation.   The
    295  1.1  christos 	status of the queued request will be stored through s, and
    296  1.1  christos 	will also be either zero for success or nonzero for some kind
    297  1.1  christos 	of failure.    Never returns until completion or until the
    298  1.1  christos 	connection to the server is lost.   This performs the same
    299  1.1  christos 	function as dhcpctl_set_callback and the subsequent callback,
    300  1.1  christos 	for programs that want to do inline execution instead of using
    301  1.1  christos 	callbacks.
    302  1.1  christos 
    303  1.1  christos dhcpctl_status dhcpctl_get_value (data_string *result,
    304  1.1  christos 				  dhcpctl_handle h, char *value_name)
    305  1.1  christos 	synchronous
    306  1.1  christos 	returns zero if the call succeeded, a nonzero status code if
    307  1.1  christos 	it didn't. 
    308  1.1  christos 	result is the address of an empty data string (initialized
    309  1.1  christos 	with bzero or cleared with data_string_forget).   On
    310  1.1  christos 	successful completion, the addressed data string will contain
    311  1.1  christos 	the value that was fetched.
    312  1.1  christos 	dhcpctl_handle refers to some dhcpctl item
    313  1.1  christos 	value_name refers to some value related to that item - e.g.,
    314  1.1  christos 	for a handle associated with a completed host lookup, value
    315  1.1  christos 	could be one of "hardware-address", "dhcp-client-identifier",
    316  1.1  christos 	"known" or "client-hostname".
    317  1.1  christos 
    318  1.1  christos dhcpctl_status dhcpctl_get_boolean (int *result,
    319  1.1  christos 				    dhcpctl_handle h, char *value_name)
    320  1.1  christos 	like dhcpctl_get_value, but more convenient for boolean
    321  1.1  christos 	values, since no data_string needs to be dealt with.
    322  1.1  christos 
    323  1.1  christos dhcpctl_status dhcpctl_set_value (dhcpctl_handle h, data_string value,
    324  1.1  christos 				  char *value_name)
    325  1.1  christos 	Sets a value on an object referred to by a dhcpctl_handle.
    326  1.1  christos 	The opposite of dhcpctl_get_value.   Does not update the
    327  1.1  christos 	server - just sets the value on the handle.
    328  1.1  christos 
    329  1.1  christos dhcpctl_status dhcpctl_set_string_value (dhcpctl_handle h, char *value,
    330  1.1  christos 					 char *value_name)
    331  1.1  christos 	Sets a NUL-terminated ASCII value on an object referred to by
    332  1.1  christos 	a dhcpctl_handle.   like dhcpctl_set_value, but saves the
    333  1.1  christos 	trouble of creating a data_string for a NUL-terminated string.
    334  1.1  christos 	Does not update the server - just sets the value on the handle.
    335  1.1  christos 
    336  1.1  christos dhcpctl_status dhcpctl_set_boolean (dhcpctl_handle h, int value,
    337  1.1  christos 				    char *value_name)
    338  1.1  christos 	Sets a boolean value on an object - like dhcpctl_set_value,
    339  1.1  christos 	only more convenient for booleans.
    340  1.1  christos 
    341  1.1  christos dhcpctl_status dhcpctl_object_update (dhcpctl_handle h)
    342  1.1  christos 	Queues an update on the object referenced by the handle (there
    343  1.1  christos 	can't be any other work in progress on the handle).   An
    344  1.1  christos 	update means local parameters will be sent to the server.
    345  1.1  christos 
    346  1.1  christos dhcpctl_status dhcpctl_object_refresh (dhcpctl_handle h)
    347  1.1  christos 	Queues an update on the object referenced by the handle (there
    348  1.1  christos 	can't be any other work in progress on the handle).   An
    349  1.1  christos 	update means local parameters will be sent to the server.
    350  1.1  christos 
    351  1.1  christos dhcpctl_status dhcpctl_object_delete (dhcpctl_handle h)
    352  1.1  christos 	Queues a delete of the object referenced by the handle (there
    353  1.1  christos 	can't be any other work in progress on the handle).   A
    354  1.1  christos 	delete means that the object will be permanently deleted on
    355  1.1  christos 	the remote end, assuming the remote end supports object
    356  1.1  christos 	persistence.
    357  1.1  christos 
    358  1.1  christos So a sample program that would update a host declaration would look
    359  1.1  christos something like this:
    360  1.1  christos 
    361  1.1  christos 	/* Create a local object into which to store authentication
    362  1.1  christos 	   information. */
    363  1.1  christos 	if ((status = dhcpctl_new_object (&auth, dhcpctl_null_handle,
    364  1.1  christos 					  "authentication-information")))
    365  1.1  christos 		dhcpctl_error ("Can't create authentication information: %m");
    366  1.1  christos 
    367  1.1  christos 	/* Set up the authenticator with an algorithm type, user name and
    368  1.1  christos 	   password. */
    369  1.1  christos 	if ((status = dhcpctl_set_string_value (&auth, "mellon", "username")))
    370  1.1  christos 		dhcpctl_error ("Can't set username: %m", status);
    371  1.1  christos 	if ((status = dhcpctl_set_string_value (&auth, "three blind mice",
    372  1.1  christos 						"password")))
    373  1.1  christos 		dhcpctl_error ("Can't set password: %m", status);
    374  1.1  christos 	if ((status = dhcpctl_set_string_value (&auth, "md5-hash",
    375  1.1  christos 						"algorithm")))
    376  1.1  christos 		dhcpctl_error ("Can't set authentication algorithm: %m.",
    377  1.1  christos 			       status);
    378  1.1  christos 
    379  1.1  christos 	/* Connect to the server. */
    380  1.1  christos 	if ((status = dhcpctl_connect (&c, "dhcp.server.com", 612, &auth)))
    381  1.1  christos 
    382  1.1  christos 		dhcpctl_error ("Can't connect to dhcp.server.com: %m",
    383  1.1  christos 			       status);
    384  1.1  christos 
    385  1.1  christos 	/* Create a host object. */
    386  1.1  christos 	if ((status = dhcpctl_new_object (&hp, c, "host")))
    387  1.1  christos 		dhcpctl_error ("Host create failed: %m", status);
    388  1.1  christos 
    389  1.1  christos 	/* Create a data_string to contain the host's client
    390  1.1  christos 	   identifier, and set it. */
    391  1.1  christos 	if ((status =
    392  1.1  christos 	     data_string_create_from_hex (&client_id,
    393  1.1  christos 					  "1:08:00:2b:34:1a:c3")))
    394  1.1  christos 		dhcpctl_error ("Can't create client identifier: %m");
    395  1.1  christos 	if ((status = dhcpctl_set_value (hp, client_id,
    396  1.1  christos 					 "dhcp-client-identifier")))
    397  1.1  christos 		dhcpctl_error ("Host client identifier set failed.");
    398  1.1  christos 	/* Set the known flag to 1. */
    399  1.1  christos 	if ((status = dhcpctl_set_boolean (hp, 1, "known")))
    400  1.1  christos 		dhcpctl_error ("Host known set failed.");
    401  1.1  christos 
    402  1.1  christos 	/* Open an existing host object that matches the client identifier,
    403  1.1  christos 	   and update it from the local context, or if no host entry
    404  1.1  christos 	   yet exists matching the identifier, create one and
    405  1.1  christos 	   initialize it. */
    406  1.1  christos 	if ((status = dhcpctl_open_object (&hp, c,
    407  1.1  christos 					   DHCPCTL_CREATE | DHCPCTL_UPDATE)))
    408  1.1  christos 		dhcpctl_error ("Can't open host: %m", status);
    409  1.1  christos 
    410  1.1  christos 	/* Wait for the process to complete, check status. */
    411  1.1  christos 	if ((status = dhcpctl_wait_for_completion (hp, &wait_status)))
    412  1.1  christos 		dhcpctl_error ("Host create/lookup wait failed: %m", status);
    413  1.1  christos 	if (waitstatus)
    414  1.1  christos 		dhcpctl_error ("Host create/lookup failed: %m", status);
    415  1.1  christos 
    416  1.1  christos The API is a bit complicated, for a couple of reasons.   I want to
    417  1.1  christos make it general, so that there aren't a bazillion functions to call,
    418  1.1  christos one for each data type.   I want it to be thread-safe, which is why
    419  1.1  christos each function returns a status and the error printer requires a status
    420  1.1  christos code for input.   I want it to be possible to make it asynchronous, so
    421  1.1  christos that it can work in tandem with, for example, an X toolkit.   If
    422  1.1  christos you're just writing a simple update cgi program, you probably won't
    423  1.1  christos want to bother to use the asynchronous callbacks, and indeed the above
    424  1.1  christos example doesn't.
    425  1.1  christos 
    426  1.1  christos I glossed over data strings above - basically, they're objects with a
    427  1.1  christos pointer to a reference-counted buffer structure, an offset into that
    428  1.1  christos buffer, and a length.   These are used within the DHCP server, so you
    429  1.1  christos can get an idea of how they work - basically, they're a convenient and
    430  1.1  christos efficient way to store a string with a length such that substrings can
    431  1.1  christos easily be taken and such that more than one user at a time can have a
    432  1.1  christos pointer to the string.
    433  1.1  christos 
    434  1.1  christos I will also probably add locking primitives, so that you can get the
    435  1.1  christos value of something and be sure that some other updator process won't
    436  1.1  christos modify it while you have the lock.
    437