|
Service Location Protocol Library Functions | slp_api(3SLP) |
| slp_api - Service Location
Protocol Application Programming Interface |
SYNOPSIS
|
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.
Syntax for String Parameters
|
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.
|
System Properties
|
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().
|
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 possible.
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 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
- 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 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. 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 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
- 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
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 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. 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 following 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 operation. 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 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
- 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 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
- 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.
|
|
|
An interface that is part of the SLP API may return one of the following 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 synchronous 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 parameter 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 malformed URL or attributes. SLP does not return the error if at least one DA accepts the registration.
-
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 authentication on an SLP message received from a remote SLP agent
failed.
-
SLP_INVALID_UPDATE
- An update for a nonexisting registration 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 registration 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 maximum 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 maximum 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 configured timeout interval, this error is returned.
-
SLP_NETWORK_INIT_FAILED
- If the network cannot initialize properly, 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 interface 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
function
|
|
- SLPOpen()
- 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 discovered 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
|
|
When SLP_CONF_FILE is set, use this file for configuration.
|
|
See attributes(5)
for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
Availability | SUNWslpu |
CSI | CSI-enabled |
Interface Stability | Standard |
MT-Level | Safe |
|
|
slpd(1M), slp.conf(4), slpd.reg(4), attributes(5)
System Administration Guide: Resource Management and 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.
|
| |