te
Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
slp_api - Service Location Protocol Application Programming Interface

cc [ flag ... ] file ... -lslp [ library ... ]
#include <slp.h>

The slp_api is a C language binding that maps directly into the Service Location Protocol ("SLP") defined by RFC 2614. This implementation requires minimal overhead. With the exception of the SLPDereg() and SLPDelAttrs() functions, which map into different uses of the SLP deregister request, there is one C language function per protocol request. Parameters are for the most part character buffers. Memory management is kept simple because the client allocates most memory and client callback functions are required to copy incoming parameters into memory allocated by the client code. Any memory returned directly from the API functions is deallocated using the SLPFree() function.

To conform with standard C practice, all character strings passed to and returned through the API are null-terminated, even though the SLP protocol does not use null-terminated strings. Strings passed as parameters are UTF-8 but they may still be passed as a C string (a null-terminated sequence of bytes.) Escaped characters must be encoded by the API client as UTF-8. In the common case of US-ASCII, the usual one byte per character C strings work. API functions assist in escaping and unescaping strings.

Unless otherwise noted, parameters to API functions and callbacks are non-NULL. Some parameters may have other restrictions. If any parameter fails to satisfy the restrictions on its value, the operation returns a PARAMETER_BAD error.

Query strings, attribute registration lists, attribute deregistration lists, scope lists, and attribute selection lists follow the syntax described in RFC 2608. The API reflects the strings passed from clients directly into protocol requests, and reflects out strings returned from protocol replies directly to clients. As a consequence, clients are responsible for formatting request strings, including escaping and converting opaque values to escaped byte-encoded strings. Similarly, on output, clients are required to unescape strings and convert escaped string-encoded opaques to binary. The SLPEscape() and SLPUnescape() functions can be used for escaping SLP reserved characters, but they perform no opaque processing.

Opaque values consist of a character buffer that contains a UTF-8-encoded string, the first characters of which are the non UTF-8 encoding "\ff". Subsequent characters are the escaped values for the original bytes in the opaque. The escape convention is relatively simple. An escape consists of a backslash followed by the two hexadecimal digits encoding the byte. An example is "\2c" for the byte 0x2c. Clients handle opaque processing themselves, since the algorithm is relatively simple and uniform.

The system properties established in slp.conf(4), the configuration file, are accessible through the SLPGetProperty() and SLPSetProperty() functions. The SLPSetProperty() function modifies properties only in the running process, not in the configuration file. Errors are checked when the property is used and, as with parsing the configuration file, are logged at the LOG_INFO priority. Program execution continues without interruption by substituting the default for the erroneous parameter. In general, individual agents should rarely be required to override these properties, since they reflect properties of the SLP network that are not of concern to individual agents. If changes are required, system administrators should modify the configuration file.

Properties are global to the process, affecting all threads and all handles created with SLPOpen().

The only API functions that return memory specifically requiring deallocation on the part of the client are SLPParseSrvURL(), SLPFindScope(), SLPEscape(), and SLPUnescape(). Free this memory with SLPFree() when it is no longer needed. Do not free character strings returned by means of the SLPGetProperty() function.

Any memory passed to callbacks belongs to the library, and it must not be retained by the client code. Otherwise, crashes are possible. Clients must copy data out of the callback parameters. No other use of the memory in callback parameters is allowed.

If a handle parameter to an API function is opened asynchronously, the API function calls on the handle to check the other parameters, opens the appropriate operation, and returns immediately. If an error occurs in the process of starting the operation, the error code is returned. If the handle parameter is opened synchronously, the function call is blocked until all results are available, and it returns only after the results are reported through the callback function. The return code indicates whether any errors occurred during the operation.

The callback function is called whenever the API library has results to report. The callback code is required to check the error code parameter before looking at the other parameters. If the error code is not SLP_OK, the other parameters may be NULL or otherwise invalid. The API library can terminate any outstanding operation on which an error occurs. The callback code can similarly indicate that the operation should be terminated by passing back SLP_FALSE to indicate that it is not interested in receiving more results. Callback functions are not permitted to recursively call into the API on the same SLPHandle. If an attempt is made to call into the API, the API function returns SLP_HANDLE_IN_USE. Prohibiting recursive callbacks on the same handle simplifies implementation of thread safe code, since locks held on the handle will not be in place during a second outcall on the handle.

The total number of results received can be controlled by setting the net.slp.maxResults parameter.

On the last call to a callback, whether asynchronous or synchronous, the status code passed to the callback has value SLP_LAST_CALL. There are four reasons why the call can terminate:

DA reply received

Multicast terminated

Multicast null results

Maximum results

The API library reads slp.conf(4), the default configuration file, to obtain the operating parameters. You can specify the location of this file with the SLP_CONF_FILE environment variable. If you do not set this variable, or the file it refers to is invalid, the API will use the default configuration file at /etc/inet/slp.conf instead.

The data structures used by the SLP API are as follows:

typedef enum {
 SLP_LIFETIME_DEFAULT = 10800,
 SLP_LIFETIME_MAXIMUM = 65535
} SLPURLLifetime;

The enumeration SLPURLLifetime contains URL lifetime values, in seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours, while SLP_LIFETIME_MAXIMUM is 18 hours, which corresponds to the maximum size of the lifetime field in SLP messages. Note that on registration SLP_LIFETIME_MAXIMUM causes the advertisement to be continually reregistered until the process exits.

typedef enum {
 SLP_FALSE = 0,
 SLP_TRUE = 1
} SLPBoolean;

The enumeration SLPBoolean is used as a Boolean flag.

typedef struct srvurl {
 char *s_pcSrvType;
 char *s_pcHost;
 int s_iPort;
 char *s_pcNetFamily;
 char *s_pcSrvPart;
} SLPSrvURL;

The SLPSrvURL structure is filled in by the SLPParseSrvURL() function with information parsed from a character buffer containing a service URL. The fields correspond to different parts of the URL, as follows:

s_pcSrvType

s_pcHost

s_iPort

s_pcNetFamily

s_pcSrvPart

typedef void* SLPHandle;

The SLPHandle type is returned by SLPOpen() and is a parameter to all SLP functions. It serves as a handle for all resources allocated on behalf of the process by the SLP library. The type is opaque.

Include a function pointer to a callback function specific to a particular API operation in the parameter list when the API function is invoked. The callback function is called with the results of the operation in both the synchronous and asynchronous cases. When the callback function is invoked, the memory included in the callback parameters is owned by the API library, and the client code in the callback must copy out the contents if it wants to maintain the information longer than the duration of the current callback call.

Each callback parameter list contains parameters for reporting the results of the operation, as well as an error code parameter and a cookie parameter. The error code parameter reports the error status of the ongoing (for asynchronous) or completed (for synchronous) operation. The cookie parameter allows the client code that starts the operation by invoking the API function to pass information down to the callback without using global variables. The callback returns an SLPBoolean to indicate whether the API library should continue processing the operation. If the value returned from the callback is SLP_TRUE, asynchronous operations are terminated. Synchronous operations ignore the return since the operation is already complete.

typedef void SLPRegReport(SLPHandle hSLP, 
 SLPError errCode, 
 void *pvCookie);

SLPRegReport() is the callback function to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. The SLPRegReport() callback has the following parameters:

hSLP

errCode

pvCookie

typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP, 
 const char* pcSrvTypes, 
 SLPError errCode, 
 void *pvCookie);

The SLPSrvTypeCallback() type is the type of the callback function parameter to the SLPFindSrvTypes() function. The results are collated when the hSLP handle is opened either synchronously or asynchronously. The SLPSrvTypeCallback() callback has the following parameters:

hSLP

pcSrvTypes

errCode

pvCookie

typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP, 
 const char* pcSrvURL, 
 unsigned short usLifetime, 
 SLPError errCode, 
 void *pvCookie); 

The SLPSrvURLCallback() type is the type of the callback function parameter to the SLPFindSrvs() function. The results are collated, regardless of whether the hSLP was opened collated or uncollated. The SLPSrvURLCallback() callback has the following parameters:

hSLP

pcSrvURL

usLifetime

errCode

pvCookie

typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP, 
 const char* pcAttrList, 
 SLPError errCode, 
 void *pvCookie);

The SLPAttrCallback() type is the type of the callback function parameter to the SLPFindAttrs() function.

The behavior of the callback differs depending upon whether the attribute request was by URL or by service type. If the SLPFindAttrs() operation was originally called with a URL, the callback is called once, in addition to the last call, regardless of whether the handle was opened asynchronously or synchronously. The pcAttrList parameter contains the requested attributes as a comma-separated list. It is empty if no attributes match the original tag list.

If the SLPFindAttrs() operation was originally called with a service type, the value of pcAttrList and the calling behavior depend upon whether the handle was opened asynchronously or synchronously. If the handle was opened asynchronously, the callback is called every time the API library has results from a remote agent. The pcAttrList parameter is collated between calls, and contains a comma-separated list of the results from the agent that immediately returned. If the handle was opened synchronously, the results are collated from all returning agents, the callback is called once, and the pcAttrList parameter is set to the collated result.

SLPAttrCallback() callback has the following parameters:

hSLP

pcAttrList

errCode

pvCookie

An interface that is part of the SLP API may return one of the following values.

SLP_LAST_CALL

SLP_OK

SLP_LANGUAGE_NOT_SUPPORTED

SLP_PARSE_ERROR

SLP_INVALID_REGISTRATION

SLP_SCOPE_NOT_SUPPORTED

SLP_AUTHENTICATION_ABSENT

SLP_AUTHENTICATION_FAILED

SLP_INVALID_UPDATE

SLP_REFRESH_REJECTED

SLP_NOT_IMPLEMENTED

SLP_BUFFER_OVERFLOW

SLP_NETWORK_TIMED_OUT

SLP_NETWORK_INIT_FAILED

SLP_MEMORY_ALLOC_FAILED

SLP_PARAMETER_BAD

SLP_NETWORK_ERROR

SLP_INTERNAL_SYSTEM_ERROR

SLP_HANDLE_IN_USE

SLPOpen()

SLPClose()

SLPReg()

SLPDereg()

SLPDelAttrs()

SLPFindSrvTypes()

SLPFindSrvs()

SLPFindAttrs()

SLPGetRefreshInterval()

SLPFindScopes()

SLPParseSrvURL()

SLPEscape()

SLPUnescape()

SLPGetProperty()

SLPSetProperty()

slp_strerror()

SLPFree()

When SLP_CONF_FILE is set, use this file for configuration.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
CSI	CSI-enabled
MT-Level	Safe

slpd(1M), slp.conf(4), slpd.reg(4), attributes(5)

System Administration Guide: Network Services

Guttman, E., Perkins, C., Veizades, J., and Day, M. RFC 2608, Service Location Protocol, Version 2. The Internet Society. June 1999.

Kempf, J. and Guttman, E. RFC 2614, An API for Service Location. The Internet Society. June 1999.