Tribblix: manual page: slp

SLP_API(3SLP) Service Location Protocol Library Functions SLP_API(3SLP)

NAME

slp_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
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(5), 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(5), 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

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
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
The SLPHandle() 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.

ERRORS

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

LIST OF ROUTINES

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

ENVIRONMENT VARIABLES

When SLP_CONF_FILE is set, use this file for configuration.

ATTRIBUTES