Service Location Protocol Library Functions slpapi(3SLP)
NAME
slpapi - Service Location Protocol Application Programming
Interface
SYNOPSIS
cc [ flag ... ] file ... -lslp [ library ... ]
#include
DESCRIPTION
The slpapi 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() func-
tions, which map into different uses of the SLP dere-
gister request, there is one C language function per
protocol request. Parameters are for the most part char-
acter buffers. Memory management is kept simple because the
client allocates most memory and client callback functions
are required to copy incoming parameters into memory allo-
cated by the client code. Any memory returned directly from
the API functions is deallocated using the SLPFree() func-
tion.
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-ASCI,
the usual one byte per character C strings work. API func-
tions assist in escaping and unescaping strings.
Unless otherwise noted, parameters to API functions and
callbacks are non-NUL. Some parameters may have other res-
trictions. If any parameter fails to satisfy the restric-
tions on its value, the operation returns a PARAMETERBAD
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 pro-
tocol requests, and reflects out strings returned from pro-
tocol 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
SunOS 5.11 Last change: 16 Jan 2003 1
Service Location Protocol Library Functions slpapi(3SLP)
to unescape strings and convert escaped string-encoded
opaques to binary. The SLPEscape() and SLPUnescape() func-
tions 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 "". 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 han-
dle opaque processing themselves, since the algorithm is
relatively simple and uniform.
System Properties
The system properties established in slp.conf(4), the confi-
guration file, are accessible through the SLPGetProperty()
and SLPSetProperty() functions. The SLPSetProperty() func-
tion 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 LOGINFO 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 con-
cern 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 SLPar-
seSrvURL(), 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
SunOS 5.11 Last change: 16 Jan 2003 2
Service Location Protocol Library Functions slpapi(3SLP)
If a handle parameter to an API function is opened asynchro-
nously, 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 parame-
ters. If the error code is not SLPOK, the other parameters
may be NUL or otherwise invalid. The API library can ter-
minate any outstanding operation on which an error occurs.
The callback code can similarly indicate that the operation
should be terminated by passing back SLPFALSE to indicate
that it is not interested in receiving more results. Call-
back 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 SLPHANDLEINUSE.
Prohibiting recursive callbacks on the same handle simpli-
fies 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 syn-
chronous, the status code passed to the callback has value
SLPLASTCAL. There are four reasons why the call can ter-
minate:
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 multi-
cast code is giving up.
Multicast null results Nothing new has been received dur-
ing multicast for awhile and the
API library multicast code is
SunOS 5.11 Last change: 16 Jan 2003 3
Service Location Protocol Library Functions slpapi(3SLP)
giving up on that (as an optimiza-
tion).
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 SLPCONFILE environment
variable. If you do not set this variable, or the file it
refers to is invalid, the API will use the default confi-
guration 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 {
SLPLIFETIMEDEFAULT = 10800,
SLPLIFETIMEMAXIMUM = 65535
} SLPURLifetime;
The enumeration SLPURLifetime contains URL lifetime
values, in seconds, that are frequently used.
SLPLIFETIMEDEFAULT is 3 hours, while SLPLIFETIMEMAXIMUM
is 18 hours, which corresponds to the maximum size of the
lifetime field in SLP messages. Note that on registration
SLPLIFETIMEMAXIMUM causes the advertisement to be continu-
ally reregistered until the process exits.
The SLPBoolean Type
typedef enum {
SLPFALSE = 0,
SLPTRUE = 1
} SLPBoolean;
The enumeration SLPBoolean is used as a Boolean flag.
The Service URL Structure
typedef struct srvurl {
char *spcSrvType;
char *spcHost;
int siPort;
SunOS 5.11 Last change: 16 Jan 2003 4
Service Location Protocol Library Functions slpapi(3SLP)
char *spcNetFamily;
char *spcSrvPart;
} SLPSrvURL;
The SLPSrvURL structure is filled in by the SLParseSrvURL()
function with information parsed from a character buffer
containing a service URL. The fields correspond to different
parts of the URL, as follows:
spcSrvType A pointer to a character string containing
the service type name, including naming
authority.
spcHost A pointer to a character string containing
the host identification information.
siPort The port number, or zero, if none. The port
is only available if the transport is IP.
spcNetFamily A pointer to a character string containing
the network address family identifier. Pos-
sible values are "ipx" for the IPX family,
"at" for the Appletalk family, and "", the
empty string, for the IP address family.
spcSrvPart 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 ser-
vice.
The SLPHandle
typedef void* SLPHandle;
The SLPHandle type is returned by SLPOpen() and is a parame-
ter 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.
SunOS 5.11 Last change: 16 Jan 2003 5
Service Location Protocol Library Functions slpapi(3SLP)
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 call-
back 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 report-
ing 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 parame-
ter 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 SLPTRUE, asynchronous opera-
tions 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 NUL.
SLPSrvTypeCallback()
typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,
SunOS 5.11 Last change: 16 Jan 2003 6
Service Location Protocol Library Functions slpapi(3SLP)
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
SLPOK, then the API library may choose to
terminate the outstanding operation.
pvCookie emory passed down from the client code that
called the original API function, starting the
operation. It can be NUL.
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() call-
back has the following parameters:
hSLP The SLPHandle used to initiate the operation.
SunOS 5.11 Last change: 16 Jan 2003 7
Service Location Protocol Library Functions slpapi(3SLP)
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
SLPLIFETIMEMAXIMUM.
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
SLPOK, 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 NUL.
SLPAttrCallback
typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP,
const char* pcAttrList,
SLPError errCode,
void *pvCookie);
The SLPAttrCallback() type is the type of the callback func-
tion 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 asynchro-
nously or synchronously. If the handle was opened asynchro-
nously, 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
SunOS 5.11 Last change: 16 Jan 2003 8
Service Location Protocol Library Functions slpapi(3SLP)
of the results from the agent that immediately returned. If
the handle was opened synchronously, the results are col-
lated 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 attri-
bute 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
SLPOK, 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 NUL.
ERORS
An interface that is part of the SLP API may return one of
the following values.
SLPLASTCAL The SLPLASTCAL code is
passed to callback functions
when the API library has no
more data for them and there-
fore no further calls will be
made to the callback on the
currently outstanding opera-
tion. 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
SunOS 5.11 Last change: 16 Jan 2003 9
Service Location Protocol Library Functions slpapi(3SLP)
has value SLPLASTCAL, and
the other parameters are all
NUL. If no results are
returned by an API operation,
then only one call is made,
with the error parameter set
to SLPLASTCAL.
SLPOK The SLPOK code indicates that
the no error occurred during
the operation.
SLPLANGUAGENOTSUPORTED No DA or SA has service adver-
tisement information in the
language requested, but at
least one DA or SA might have
information for that service
in another language.
SLPARSEROR 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 dam-
aged in transit.
SLPINVALIDREGISTRATION 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 registra-
tion.
SLPSCOPENOTSUPORTED The API returns this error if
the UA or SA has been config-
ured 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
SunOS 5.11 Last change: 16 Jan 2003 10
Service Location Protocol Library Functions slpapi(3SLP)
included in a request is not
supported by a DA.
SLPAUTHENTICATIONABSENT This error arises when the UA
or SA failed to send an
authenticator for requests or
registrations when security is
enabled and thus required.
SLPAUTHENTICATIONFAILED This error arises when a
authentication on an SLP mes-
sage received from a remote
SLP agent failed.
SLPINVALIDUPDATE An update for a nonexisting
registration was issued, or
the update includes a service
type or scope different than
that in the initial registra-
tion.
SLPREFRESHREJECTED 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.
SLPNOTIMPLEMENTED An outgoing request overflowed
the maximum network MTU size.
The request should be reduced
in size or broken into pieces
and tried again.
SLPBUFEROVERFLOW An outgoing request overflowed
the maximum network MTU size.
The request should be reduced
in size or broken into pieces
and tried again.
SLPNETWORKTIMEDOUT When no reply can be obtained
in the time specified by the
configured timeout interval,
this error is returned.
SunOS 5.11 Last change: 16 Jan 2003 11
Service Location Protocol Library Functions slpapi(3SLP)
SLPNETWORKINITFAILED If the network cannot initial-
ize properly, this error is
returned.
SLPMEMORYALOCFAILED If the API fails to allocate
memory, the operationis
aborted and returns this.
SLPARAMETERBAD If a parameter passed into an
interface is bad, this error
is returned.
SLPNETWORKEROR The failure of networking dur-
ing normal operations causes
this error to be returned.
SLPINTERNALSYSTEMEROR 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.
SLPHANDLEINUSE In the C API, callback func-
tions 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 advertise-
ment
SunOS 5.11 Last change: 16 Jan 2003 12
Service Location Protocol Library Functions slpapi(3SLP)
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
SLParseSrvURL() 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
slpstrerror() map SLP error code to message
SLPFree() free memory
ENVIRONMENT VARIABLES
When SLPCONFILE is set, use this file for configuration.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 16 Jan 2003 13
Service Location Protocol Library Functions slpapi(3SLP)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWslpu
CSI CSI-enabled
MT-Level Safe
SEE ALSO
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 Loca-
tion. The Internet Society. June 1999.
SunOS 5.11 Last change: 16 Jan 2003 14
|
