Chapter 4
Code Samples and Testing
This chapter includes some segments of code that illustrate
proper use of the API functions.
The following topics are included:
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);
}
|