Chapter 3 Service Provider Layer API

This chapter lists and describes the API functions exported by public modules and consumed by the Framework Configuration Layer. The functions are grouped in sections according to their purpose. Within each section, functions are listed in an order in which you might use them.

The following topics are included:

• General Data Store Functions

• dhcptab Functions

• DHCP Network Container Functions

• Generic Error Codes

All implementations that match a certain Service Provider Layer API version must follow this specification for the API functions they implement. Later versions of the API must be backward-compatible with earlier versions. This means that additional API calls may be added, but existing ones cannot be changed or deleted.

See the include file /usr/include/dhcp_svc_public.h for more details about the functions.

General Data Store Functions

This section lists functions related to general data store activities.

configure()

Purpose

To pass a configuration string to the data store.

Synopsis

int configure(const char *configp);

Description

The configure() function is optional. If it is provided together with the required public module management bean (see Data Service Configuration and DHCP Management Tools), the Framework Configuration Layer calls this function when the public module loads, and passes in the public-module-specific configuration string, which is cached by the Framework Configuration Layer on the DHCP server for the data store module.

Returns

DSVC_SUCCESS, DSVC_MODULE_CFG_ERR

The configure() function returns DSVC_SUCCESS if the module wants the Framework Configuration Layer to continue to load the module, or DSVC_MODULE_CFG_ERR if the module wants the Framework Configuration Layer to fail the loading of the module. An example of such a situation is a configuration string so malformed that the required configuration of the module cannot take place.

mklocation()

Purpose

To create the directory where the data store containers are to reside.

Synopsis

int mklocation(const char *location);

Description

Creates the directory pointed to by location (if the directory does not exist) for data store containers to reside.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_EXISTS, DSVC_BUSY, DSVC_INTERNAL, DSVC_UNSUPPORTED.

status()

Purpose

To obtain the general status of the data store.

Synopsis

int status(const char *location);

Description

The status() function instructs the data store to return its general status, and if location is non-NULL, further validates the location of the data store container by determining if the container does in fact exist, is accessible, and is formed correctly for the data store type. The data store must return the appropriate error codes if the facilities it needs are unavailable or it is otherwise not ready.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.

version()

Purpose

To obtain the version number of the API implemented by the data store.

Synopsis

int version(int *versionp);

Description

Data stores that support the Service Provider Layer API described in this manual are version 1 (one). The version is returned in the int pointed to by versionp.

Returns

DSVC_SUCCESS, DSVC_INTERNAL, DSVC_MODULE_ERR.

dhcptab Functions

The API functions described in this section are used with the dhcptab container.

list_dt()

Purpose

To list the name of the dhcptab container.

Synopsis

int list_dt(const char *location, char ***listppp, uint_t *count);

Description

Produces a dynamically allocated list of dhcptab container objects (listppp) found at location and stores the number of list items in count. If no dhcptab container objects exist, then DSVC_SUCCESS is returned, listppp is set to NULL, and count is set to 0.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION.

open_dt()

Purpose

To open a dhcptab container or create a new one.

Synopsis

int open_dt(void **handpp, const char *location, uint_t flags);

Description

Opens an existing dhcptab container or creates a new container at location and initializes handp to point to the instance handle. Performs any initialization needed by the data store. When creating a new dhcptab, the caller's identity is used for owner/permissions. Valid flags include DSVC_CREATE, DSVC_READ, DSVC_WRITE, DSVC_NONBLOCK. Note that the creation of a dhcptab container as read-only (DSVC_CREATE | DSVC_READ) is invalid.

Returns

DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.

lookup_dt()

Purpose

To perform a lookup query for records in the dhcptab container.

Synopsis

int lookup_dt(void *handp, boolean_t partial, uint_t query, int count, const dt_rec_t *targetp, dt_rec_list_t **resultp, uint_t *records);

Description

Searches the dhcptab container for instances that match the query described by the combination of query and targetp. If the partial argument is B_TRUE, then partial query results are acceptable to the caller. Thus, when partial is B_TRUE, any query that returns at least one matching record is considered successful. When partial is B_FALSE, the query returns DSVC_SUCCESS only if it has been applied to the entire container.

The query argument consists of 2 fields, each 16 bits long. The lower 16 bits select which fields {key, type} of targetp are to be considered in the query. The upper 16 bits identify whether a particular field value selected in the lower 16 bits must match (bit set) or not match (bit clear). Bits 2 through 15 in both 16-bit fields are currently unused, and must be set to 0. Useful macros for constructing queries can be found in Example 3–1.

The count field specifies the maximum number of matching records to return. A count value of -1 requests the return of all records that match, regardless of the number. A count value of 0 causes lookup_dt to return immediately with no data.

resultp is set to point to the returned list of records. If resultp is NULL, then the caller is simply interested in knowing how many records match the query. Note that these records are dynamically allocated, and therefore the caller is responsible for freeing them. lookup_dt() returns the number of matching records in the records argument. A records value of 0 means that no records matched the query.

The following example includes macros you might find useful for constructing and manipulating lookup queries for the DHCP network and dhcptab containers.

---

Example 3–1 Useful Macros for Lookup Queries

/*
* Query macros - used for initializing query fields (lookup_d?)
*/
/* dhcp network container */
#define DN_QCID 0x0001
#define DN_QCIP 0x0002
#define DN_QSIP 0x0004
#define DN_QLEASE 0x0008
#define DN_QMACRO 0x0010
#define DN_QFDYNAMIC 0x0020
#define DN_QFAUTOMATIC 0x0040
#define DN_QFMANUAL 0x0080
#define DN_QFUNUSABLE 0x0100
#define DN_QFBOOTP_ONLY 0x0200
#define DN_QALL (DN_QCID | DN_QCIP | DN_QSIP | DN_QLEASE | \
DN_QMACRO | DN_QFDYNAMIC DN_QFAUTOMATIC |\
DN_QFMANUAL | DN_QFUNUSABLE | \
DN_QFBOOTP_ONLY)

/* dhcptab */
#define DT_DHCPTAB "dhcptab"  /* default name of container */
#define DT_QKEY 0x01
#define DT_QTYPE 0x02
#define DT_QALL (DT_QKEY | DT_QTYPE)

/* general query macros */
#define DSVC_QINIT(q) ((q) = 0)
#define DSVC_QEQ(q, v) ((q) = ((q) | (v) | ((v) << 16)))
#define DSVC_QNEQ(q, v) ((q) = ((~(v << 16)) & (q)) | (v)))
#define DSVC_QISEQ(q, v) (((q) & (v)) && ((q) & ((v) << 16)))
#define DSVC_QISNEQ(q, v) (((q) & (v)) && (!((q) & ((v) << 16))))

/* Examples */
uint_t query;
/* search for dhcptab record with key value, but not flags value */
DSVC_QINIT(query);
DSVC_QEQ(query, DT_QKEY);
DSVC_QNEQ(query, DT_QTYPE);
/* search for dhcp network record that matches cid, client ip, server ip.
*/
DSVC_QINIT(query);
DSVC_QEQ(query, (DN_QCID | DN_QCIP | DN_QSIP));

---

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL.

add_dt()

Purpose

To add a record to the dhcptab container.

Synopsis

int add_dt(void *handp, dt_rec_t *newp);

Description

Adds the record newp to the dhcptab container referred to by handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated. The caller is responsible for freeing any dynamically allocated arguments.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS.

modify_dt()

Purpose

To modify a record in the dhcptab container.

Synopsis

int modify_dt(void *handp, const dt_rec_t *origp, dt_rec_t *newp);

Description

Atomically modifies the record origp with the record newp in the dhcptab container referred to by handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated. The caller is responsible for freeing any dynamically allocated arguments.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT.

delete_dt()

Purpose

To delete a record from the dhcptab container.

Synopsis

int delete_dt(void *handp, const dt_rec_t *dtp);

Description

Deletes the record identified by the key, type and dt_sig fields of dtp from the dhcptab container referred to by the handle handp. If an update collision occurs, the matching record is not deleted from the data store, and DSVC_COLLISION is returned. The caller is responsible for freeing any dynamically allocated arguments.

If the dtp signature (dt_sig) is 0, the matching record is simply deleted with no detection of update collisions.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION.

close_dt()

Purpose

To close the dhcptab container.

Synopsis

int close_dt(void **handpp);

Description

Frees the instance handle and cleans up per-instance state.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.

remove_dt()

Purpose

To delete the dhcptab container from the data store location.

Synopsis

int remove_dt(const char *location);

Description

Removes the dhcptab container in location from the data store.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.

DHCP Network Container Functions

The API functions described in this section are used to manipulate the DHCP network containers and the IP address records within them.

list_dn()

Purpose

To return a list of network containers.

Synopsis

int list_dn(const char *location, char ***listppp, uint_t *count);

Description

Produces a dynamically allocated list of network container objects (listppp) found at location and stores the number of list items in count. If no network container objects exist, then DSVC_SUCCESS is returned, listppp is set to NULL, and count is set to 0.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION.

open_dn()

Purpose

To open a network container or create a new one.

Synopsis

int open_dn(void **handpp, const char *location, uint_t flags, const struct in_addr *netp, const struct in_addr *maskp);

Description

Opens an existing DHCP network container or creates a new container specified by netp and maskp (both host order) in location and initializes handpp to point to the instance handle. Performs any initialization needed by the data store. When creating a new DHCP network container, the caller's identity is used for owner/permissions. Valid flags include DSVC_CREATE, DSVC_READ, DSVC_WRITE, DSVC_NONBLOCK. Note that the creation of a DHCP network container as read-only (DSVC_CREATE | DSVC_READ) is invalid.

Returns

DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL, DSVC_UNSUPPORTED.

lookup_dn()

Purpose

To perform a lookup query for records in a DHCP network container.

Synopsis

int lookup_dn(void *handp, boolean_t partial, uint_t query, int count, const dn_rec_t *targetp, dn_rec_list_t **resultp, uint_t *records);

Description

Searches a DHCP network container for instances that match the query described by the combination of query and targetp. If the partial argument is B_TRUE, then partial query results are acceptable to the caller. Thus, when partial is B_TRUE, any query that returns at least one matching record is considered successful. When partial is B_FALSE, the query returns DSVC_SUCCESS only if it has been applied to the entire container.

The query argument consists of 2 fields, each 16 bits long. The lower 16 bits select 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 identify whether a particular field value selected in the lower 16 bits must match (bit set) or not match (bit clear). Bits 7 through 15 in both 16-bit fields are currently unused, and must be set to 0. Useful macros for constructing queries can be found in Example 3–1.

The count field specifies the maximum number of matching records to return. A count value of -1 requests the return of all records that match, regardless of the number. A count value of 0 causes lookup_dn to return immediately with no data.

resultp is set to point to the returned list of records. If resultp is NULL, then the caller is simply interested in knowing how many records match the query. Note that these records are dynamically allocated, and therefore the caller is responsible for freeing them. lookup_dn() returns the number of matching records in the records argument. A records value of 0 means that no records matched the query.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL.

add_dn()

Purpose

To add a record to the DHCP network container.

Synopsis

int add_dn(void *handp, dn_rec_t *newp);

Description

Adds the record newp to the DHCP network container referred to by the handle handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS.

modify_dn()

Purpose

To modify a record in a DHCP network container.

Synopsis

int modify_dn(void *handp, const dn_rec_t *origp, dn_rec_t *newp);

Description

Atomically modifies the record origp with the record newp in the DHCP network container referred to by the handle handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT.

delete_dn()

Purpose

To delete a record from a DHCP network container.

Synopsis

int delete_dn(void *handp, const dn_rec_t *pnp);

Description

Deletes the record identified by the dn_cip and dn_sig elements of pnp from the DHCP network container referred to by the handle handp. If an update collision occurs, the matching record is not deleted from the data store and DSVC_COLLISION is returned.

If the dn_sig signature of pnp is 0, the matching record is simply deleted with no detection of update collisions.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION.

close_dn()

Purpose

To close the network container.

Synopsis

int close_dn(void **handpp);

Description

Frees the instance handle and cleans up per-instance state.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.

remove_dn()

Purpose

To delete the DHCP network container from the data store location.

Synopsis

int remove_dn(const char *location, const struct in_addr *netp);

Description

Removes DHCP network container netp (host order) in location.

Returns

DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.

Generic Error Codes

The Framework Configuration Layer and Service Provider Layer API functions will return the following integer error values. Note that the file /usr/include/dhcp_svc_public.h is the definitive source for these codes.

 * Standard interface errors 
*/ 
#define DSVC_SUCCESS           0   /* success */ 
#define DSVC_EXISTS            1   /* object already exists */ 
#define DSVC_ACCESS            2   /* access denied */ 
#define DSVC_NO_CRED           3   /* No underlying credential */ 
#define DSVC_NOENT             4   /* object doesn't exist */ 
#define DSVC_BUSY              5   /* object temporarily busy (again) */ 
#define DSVC_INVAL             6   /* invalid argument(s) */ 
#define DSVC_INTERNAL          7   /* internal data store error */ 
#define DSVC_UNAVAILABLE       8   /* underlying service required by */ 
                                   /* public module unavailable */ 
#define DSVC_COLLISION         9   /* update collision */ 
#define DSVC_UNSUPPORTED       10  /* operation not supported */ 
#define DSVC_NO_MEMORY         11  /* operation ran out of memory */ 
#define DSVC_NO_RESOURCES      12  /* non-memory resources unavailable */ 
#define DSVC_BAD_RESOURCE      13  /* malformed/missing RESOURCE setting */ 
#define DSVC_BAD_PATH          14  /* malformed/missing PATH setting */ 
#define DSVC_MODULE_VERSION    15  /* public module version mismatch */ 
#define DSVC_MODULE_ERR        16  /* internal public module error */ 
#define DSVC_MODULE_LOAD_ERR   17  /* error loading public module */ 
#define DSVC_MODULE_UNLOAD_ERR 18  /* error unloading public module */ 
#define DSVC_MODULE_CFG_ERR    19  /* module configuration failure */
#define DSVC_SYNCH_ERR         20  /* error in synchronization protocol */ 
#define DSVC_NO_LOCKMGR        21  /* cannot contact lock manager */ 
#define DSVC_NO_LOCATION       22  /* location nonexistent */ 
#define DSVC_BAD_CONVER        23  /* malformed/missing CONVER setting */ 
#define DSVC_NO_TABLE          24  /* table does not exist */
#define DSVC_TABLE_EXISTS      25  /* table already exists */
#define DSVC_NERR                  (DSVC_TABLE_EXISTS + 1)