slp_api(3SLP) Service Location Protocol Library Functions slp_api(3SLP)NAMEslp_api - Service Location Protocol Application Programming Interface
SYNOPSIS
cc [ flag ... ] file ... -lslp [ library ... ]
#include <slp.h>
DESCRIPTION
The slp_api is a C language binding that maps directly into the
Service Location Protocol ("SLP") defined by RFC 2614. This imple‐
mentation 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 func‐
tion per protocol request. Parameters are for the most part charac‐
ter buffers. Memory management is kept simple because the client allo‐
cates most memory and client callback functions are required to copy
incoming parameters into memory allocated by the client code. Any mem‐
ory 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 escap‐
ing and unescaping strings.
Unless otherwise noted, parameters to API functions and callbacks are
non-NULL. Some parameters may have other restrictions. If any parame‐
ter fails to satisfy the restrictions on its value, the operation
returns a PARAMETER_BAD error.
Syntax for String Parameters
Query strings, attribute registration lists, attribute deregistra‐
tion 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 process‐
ing.
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 "". Subsequent characters are the escaped values for the orig‐
inal 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.
System Properties
The system properties established in slp.conf(4), the configuration
file, are accessible through the SLPGetProperty() and SLPSetProp‐
erty() 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 con‐
figuration 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().
Memory Management
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 possi‐
ble. Clients must copy data out of the callback parameters. No
other use of the memory in callback parameters is allowed.
Asynchronous and Incremental Return Semantics
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 ter‐
minated by passing back SLP_FALSE to indicate that it is not inter‐
ested in receiving more results. Callback functions are not per‐
mitted 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 A reply from a DA has been received and
therefore nothing more is expected.
Multicast terminated The multicast convergence time has
elapsed and the API library multicast
code is giving up.
Multicast null results Nothing new has been received during
multicast for awhile and the API
library multicast code is giving up on
that (as an optimization).
Maximum results The user has set the net.slp.maxResults
property and that number of replies
has been collected and returned.
Configuration Files
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.
Data Structures
The data structures used by the SLP API are as follows:
The URL Lifetime Type
typedef enum {
SLP_LIFETIME_DEFAULT = 10800,
SLP_LIFETIME_MAXIMUM = 65535
} SLPURLLifetime;
The enumeration SLPURLLifetime contains URL lifetime values, in sec‐
onds, 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 rereg‐
istered until the process exits.
The SLPBoolean Type
typedef enum {
SLP_FALSE = 0,
SLP_TRUE = 1
} SLPBoolean;
The enumeration SLPBoolean is used as a Boolean flag.
The Service URL Structure
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 SLPParseS‐
rvURL() 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 A pointer to a character string containing
the service type name, including naming
authority.
s_pcHost A pointer to a character string containing
the host identification information.
s_iPort The port number, or zero, if none. The port is
only available if the transport is IP.
s_pcNetFamily A pointer to a character string containing the
network address family identifier. Possible
values are "ipx" for the IPX family, "at" for
the Appletalk family, and "", the empty
string, for the IP address family.
s_pcSrvPart The remainder of the URL, after the host
identification.
The host and port should be sufficient to
open a socket to the machine hosting the
service; the remainder of the URL should allow
further differentiation of the service.
The SLPHandle
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.
Callbacks
Include a function pointer to a callback function specific to a partic‐
ular API operation in the parameter list when the API function is
invoked. The callback function is called with the results of the oper‐
ation 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) opera‐
tion. 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 SLP‐
Boolean 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.
SLPRegReport()
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 fol‐
lowing parameters:
hSLP TheSLPHandle() used to initiate the operation.
errCode An error code indicating if an error occurred during
the operation.
pvCookie Memory passed down from the client code that called the
original API function, starting the operation. It may
be NULL.
SLPSrvTypeCallback()
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 The SLPHandle used to initiate the operation.
pcSrvTypes A character buffer containing a comma-separated, null-
terminated list of service types.
errCode An error code indicating if an error occurred during
the operation. The callback should check this error
code before processing the parameters. If the error
code is other than SLP_OK, then the API library may
choose to terminate the outstanding operation.
pvCookie Memory passed down from the client code that called
the original API function, starting the opera‐
tion. It can be NULL.
SLPSrvURLCallback
typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP,
const char* pcSrvURL,
unsigned short usLifetime,
SLPError errCode,
void *pvCookie);
The SLPSrvURLCallback() type is the type of the callback func‐
tion 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 The SLPHandle used to initiate the operation.
pcSrvURL A character buffer containing the returned
service URL.
usLifetime An unsigned short giving the life time of the
service advertisement. The value must
be an unsigned integer less than or equal to
SLP_LIFETIME_MAXIMUM.
errCode An error code indicating if an error occurred
during the operation. The callback should
check this error code before processing the
parameters. If the error code is other than
SLP_OK, then the API library may choose to
terminate the outstanding operation.
pvCookie Memory passed down from the client code that
called the original API function, starting the
operation. It can be NULL.
SLPAttrCallback
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 SLPFindAt‐
trs() 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 The SLPHandle used to initiate the operation.
pcAttrList A character buffer containing a comma-separated
and null-terminated list of attribute id/value
assignments, in SLP wire format.
errCode An error code indicating if an error occurred
during the operation. The callback should
check this error code before processing the
parameters. If the error code is other than
SLP_OK, then the API library may choose to
terminate the outstanding operation.
pvCookie Memory passed down from the client code that
called the original API function, starting the
operation. It can be NULL.
ERRORS
An interface that is part of the SLP API may return one of the follow‐
ing values.
SLP_LAST_CALL The SLP_LAST_CALL code is passed to
callback functions when the API library
has no more data for them and therefore
no further calls will be made to the
callback on the currently outstanding
operation. The callback uses this to
signal the main body of the client code
that no more data will be forthcoming
on the operation, so that the main body
of the client code can break out of
data collection loops. On the last
call of a callback during both a syn‐
chronous and asynchronous call, the
error code parameter has value
SLP_LAST_CALL, and the other parameters
are all NULL. If no results are
returned by an API operation, then only
one call is made, with the error param‐
eter set to SLP_LAST_CALL.
SLP_OK The SLP_OK code indicates that the no
error occurred during the operation.
SLP_LANGUAGE_NOT_SUPPORTED No DA or SA has service advertisement
information in the language
requested, but at least one DA or
SA might have information for that
service in another language.
SLP_PARSE_ERROR The SLP message was rejected by a
remote SLP agent. The API returns
this error only when no information
was retrieved, and at least one SA or
DA indicated a protocol error. The
data supplied through the API may
be malformed or damaged in transit.
SLP_INVALID_REGISTRATION The API may return this error if
an attempt to register a service was
rejected by all DAs because of a mal‐
formed URL or attributes. SLP does
not return the error if at least
one DA accepts the reg‐
istration.
SLP_SCOPE_NOT_SUPPORTED The API returns this error if the UA
or SA has been configured with the
net.slp.useScopes list of scopes
and the SA request did not specify one
or more of these allowable scopes,
and no others. It may
also be returned by a DA if the scope
included in a request is not supported
by a DA.
SLP_AUTHENTICATION_ABSENT This error arises when the UA or SA
failed to send an authenticator for
requests or registrations when security
is enabled and thus required.
SLP_AUTHENTICATION_FAILED This error arises when a authentica‐
tion on an SLP message received from
a remote SLP agent failed.
SLP_INVALID_UPDATE An update for a nonexisting registra‐
tion was issued, or the update includes
a service type or scope different than
that in the initial registration.
SLP_REFRESH_REJECTED The SA attempted to refresh a registra‐
tion more frequently than the minimum
refresh interval. The SA should call
the appropriate API function to obtain
the minimum refresh interval to use.
SLP_NOT_IMPLEMENTED An outgoing request overflowed the max‐
imum network MTU size. The request
should be reduced in size or broken
into pieces and tried again.
SLP_BUFFER_OVERFLOW An outgoing request overflowed the max‐
imum network MTU size. The request
should be reduced in size or broken
into pieces and tried again.
SLP_NETWORK_TIMED_OUT When no reply can be obtained in the
time specified by the con‐
figured timeout interval, this error
is returned.
SLP_NETWORK_INIT_FAILED If the network cannot initialize prop‐
erly, this error is
returned.
SLP_MEMORY_ALLOC_FAILED If the API fails to allocate memory,
the operation is aborted and returns
this.
SLP_PARAMETER_BAD If a parameter passed into an inter‐
face is bad, this error is returned.
SLP_NETWORK_ERROR The failure of networking during
normal operations causes this error to
be returned.
SLP_INTERNAL_SYSTEM_ERROR A basic failure of the API causes
this error to be returned. This
occurs when a system call or library
fails. The operation could not
recover.
SLP_HANDLE_IN_USE In the C API, callback functions are
not permitted to recursively call into
the API on the same SLPHandle,
either directly or indirectly. If an
attempt is made to do so, this error
is returned from the called API func‐
tion
LIST OF ROUTINESSLPOpen() open an SLP handle
SLPClose() close an open SLP handle
SLPReg() register a service advertisement
SLPDereg() deregister a service advertisement
SLPDelAttrs() delete attributes
SLPFindSrvTypes() return service types
SLPFindSrvs() return service URLs
SLPFindAttrs() return service attributes
SLPGetRefreshInterval() return the maximum allowed refresh
interval for SAs
SLPFindScopes() return list of configured and discov‐
ered scopes
SLPParseSrvURL() parse service URL
SLPEscape() escape special characters
SLPUnescape() translate escaped characters into UTF-8
SLPGetProperty() return SLP configuration property
SLPSetProperty() set an SLP configuration property
slp_strerror() map SLP error code to message
SLPFree() free memory
ENVIRONMENT VARIABLES
When SLP_CONF_FILE is set, use this file for configuration.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWslpu │
├─────────────────────────────┼─────────────────────────────┤
│CSI │CSI-enabled │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Standard │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOslpd(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.
SunOS 5.10 16 Jan 2003 slp_api(3SLP)
