Solaris DHCP Service Developer's Guide

Code Templates

This section provides templates that show in general how you might use the API functions.


Note –

Download the source code for Sun's ASCII files data store (ds_SUNWfiles) in the developer pages on Sun's web site (http://www.sun.com/developer). The source code for the module may prove invaluable in writing your own module.


General API Functions

This template uses the general API functions status(), version(), and mklocation().


Example 4–1 general.c

* Copyright (c) 2000 by Sun Microsystems, Inc. /*
 * Copyright (c) 2000 by Sun Microsystems, Inc.
 * All rights reserved.
 */

#pragma	ident	"@(#)general.c	1.15	00/08/16 SMI"

/*
 * This module contains the public APIs for status, version, and mklocation.
 */

#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <dhcp_svc_public.h>

/*
 * This API function instructs the underlying datastore to return its 
 * general status. If the "location" argument is non-NULL, the function 
 * validates the location for the data store containers (is it formed 
 * correctly for the data store, and does it exist).
 */
int
status(const char *location)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Return the data store API version supported by this module.  This version
 * was implemented to support version 1 of the API.
 */
int
version(int *vp)
{
	*vp = DSVC_PUBLIC_VERSION;
	return (DSVC_SUCCESS);
}

/*
 * Create the datastore-specific "location" if it doesn't already exist.
 * Containers will ultimately be created there.
 */
int
mklocation(const char *location)
{
	return (DSVC_UNSUPPORTED);
}

dhcptab API Functions

This template illustrates functions that are used with the dhcptab container.


Example 4–2 dhcptab.c

/*
 * Copyright (c) 1998-2000 by Sun Microsystems, Inc.
 * All rights reserved.
 */

#pragma	ident	"@(#)dhcptab.c	1.12	00/08/16 SMI"

/*
 * This module contains the public API functions for managing the dhcptab
 * container.
 */

#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <dhcp_svc_public.h>

/*
 * List the current number of dhcptab container objects located at
 * "location" in "listppp". Return number of list elements in "count".
 * If no objects exist, then "count" is set to 0 and DSVC_SUCCESS is 
 * returned.
 *
 * This function will block waiting for a result, if the underlying 
 * data store is busy.
 */
int
list_dt(const char *location, char ***listppp, uint32_t *count)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Creates or opens the dhcptab container in "location" and initializes
 * "handlep" to point to the instance handle. When creating a new dhcptab, 
 * the caller's identity is used for owner/permissions. Performs any 
 * initialization needed by data store.
 */
int
open_dt(void **handlep, const char *location, uint32_t flags)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Frees instance handle, cleans up per instance state.
 */
int
close_dt(void **handlep)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Remove dhcptab container in "location" from data store. If the underlying
 * data store is busy, this function will block.
 */
int
remove_dt(const char *location)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Searches the dhcptab container for instances that match the query
 * described by the combination of query and targetp.  If the partial
 * argument is true, then lookup operations that are unable to
 * complete entirely are allowed (and considered successful).  The
 * query argument consists of 2 fields, each 16 bits long.  The lower
 * 16 bits selects which fields {key, flags} of targetp are to be
 * considered in the query.  The upper 16 bits identifies whether a
 * particular field value must match (bit set) or not match (bit
 * clear).  Bits 2-15 in both 16 bit fields are currently unused, and
 * must be set to 0.  The count field specifies the maximum number of
 * matching records to return, or -1 if any number of records may be
 * returned.  The recordsp argument is set to point to the resulting
 * list of records; if recordsp is passed in as NULL then no records
 * are actually returned. Note that these records are dynamically
 * allocated, thus the caller is responsible for freeing them.  The
 * number of records found is returned in nrecordsp; a value of 0
 * means that no records matched the query.
 */
int
lookup_dt(void *handle, boolean_t partial, uint32_t query, int32_t count,
    const dt_rec_t *targetp, dt_rec_list_t **recordsp, uint32_t *nrecordsp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Add the record pointed to by "addp" to from the dhcptab container 
 * referred to by the handle. The underlying public module will set 
 * "addp's" signature as part of the data store operation.
 */
int
add_dt(void *handle, dt_rec_t *addp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Atomically modify the record "origp" with the record "newp" in the
 * dhcptab container referred to by the handle.  "newp's" signature will
 * be set by the underlying public module.  If an update collision
 * occurs, either because "origp's" signature in the data store has changed
 * or "newp" would overwrite an existing record, DSVC_COLLISION is
 * returned and no update of the data store occurs.
 */
int
modify_dt(void *handle, const dt_rec_t *origp, dt_rec_t *newp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Delete the record referred to by dtp from the dhcptab container
 * referred to by the handle. If "dtp's" signature is zero, the
 * caller is not interested in checking for collisions, and the record
 * should simply be deleted if it exists. If the signature is non-zero,
 * and the signature of the data store version of this record do not match,
 * an update collision occurs, no deletion of matching record in data store
 * is done, and DSVC_COLLISION is returned.
 */
int
delete_dt(void *handle, const dt_rec_t *dtp)
{
	return (DSVC_UNSUPPORTED);
}

DHCP Network Container API Functions

This template illustrates functions used with the the DHCP network containers.


Example 4–3 dhcp_network.c

/*
 * Copyright (c) 1998-2000 by Sun Microsystems, Inc.
 * All rights reserved.
 */

#pragma	ident	"@(#)dhcp_network.c	1.12	00/08/16 SMI"

/*
 * This module contains public API functions for managing dhcp network
 * containers.
 */

#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <dhcp_svc_public.h>

/*
 * List the current number of dhcp network container objects located at
 * "location" in "listppp". Return number of list elements in "count".
 * If no objects exist, then "count" is set to 0 and DSVC_SUCCESS is 
 * returned.
 *
 * This function will block if the underlying data service is busy or is
 * otherwise unvailable.
 */
int
list_dn(const char *location, char ***listppp, uint32_t *count)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Creates or opens the dhcp network container "netp" (host order) in
 * "location" and initializes "handlep" to point to the instance handle.
 * Performs any initialization needed by data store. New containers are
 * created with the identity of the caller.
 */
int
open_dn(void **handlep, const char *location, uint32_t flags,
    const struct in_addr *netp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Frees instance handle, cleans up per instance state.
 */
int
close_dn(void **handlep)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Remove DHCP network container "netp" (host order) in location.
 * This function will block if the underlying data service is busy or
 * otherwise unavailable.
 */
int
remove_dn(const char *location, const struct in_addr *netp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Searches DHCP network container for instances that match the query
 * described by the combination of query and targetp.  If the partial
 * argument is true, then lookup operations that are unable to
 * complete entirely are allowed (and considered successful).  The
 * query argument consists of 2 fields, each 16 bits long.  The lower
 * 16 bits selects which fields {client_id, flags, client_ip,
 * server_ip, expiration, macro, or comment} of targetp are to be
 * considered in the query.  The upper 16 bits identifies whether a
 * particular field value must match (bit set) or not match (bit
 * clear).  Bits 7-15 in both 16 bit fields are currently unused, and
 * must be set to 0.  The count field specifies the maximum number of
 * matching records to return, or -1 if any number of records may be
 * returned.  The recordsp argument is set to point to the resulting
 * list of records; if recordsp is passed in as NULL then no records
 * are actually returned. Note that these records are dynamically
 * allocated, thus the caller is responsible for freeing them.  The
 * number of records found is returned in nrecordsp; a value of 0 means
 * that no records matched the query.
 */
int
lookup_dn(void *handle, boolean_t partial, uint32_t query, int32_t count,
    const dn_rec_t *targetp, dn_rec_list_t **recordsp, uint32_t *nrecordsp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Add the record pointed to by "addp" to from the dhcp network container
 * referred to by the handle.  The underlying public module will set 
 * "addp's" signature as part of the data store operation.
 */
int
add_dn(void *handle, dn_rec_t *addp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Atomically modify the record "origp" with the record "newp" in the dhcp
 * network container referred to by the handle.  "newp's" signature will
 * be set by the underlying public module.  If an update collision
 * occurs, either because "origp's" signature in the data store has changed
 * or "newp" would overwrite an preexisting record, DSVC_COLLISION is
 * returned and no update of the data store occurs.
 */
int
modify_dn(void *handle, const dn_rec_t *origp, dn_rec_t *newp)
{
	return (DSVC_UNSUPPORTED);
}

/*
 * Delete the record pointed to by "pnp" from the dhcp network container
 * referred to by the handle. If "pnp's" signature is zero, the caller
 * is not interested in checking for collisions, and the record should 
 * simply be deleted if it exists. If the signature is non-zero, and the 
 * signature of the data store version of this record do not match, an 
 * update collision occurs, no deletion of any record is done, and 
 * DSVC_COLLISION is returned.
 */
int
delete_dn(void *handle, const dn_rec_t *pnp)
{
	return (DSVC_UNSUPPORTED);
}