error is signaled and agent execution is terminated. If no
configured scope information is available, then an SA client has
default scope, "DEFAULT", and a UA client employs user scoping.
User scoping is supported in the following way. Scopes discovered
from active DA discovery, and from passive DA discovery all must be
returned. If no information is available from active and passive DA
discovery, then the API library may perform SA discovery, using the
service types in the net.slp.typeHint property to limit the search to
SAs supporting particular service types. If no net.slp.typeHint
property is set, the UA may perform SA discovery without any service
type query. In the absence of any of the above sources of
information, the API must return the default scope, "DEFAULT". Note
that the API must always return some scope information.
SLP requires that SAs must perform their operations in all scopes
currently known to them. [7]. The API enforces this constraint by
not requiring the API client to supply any scopes as parameters to
API operations. The API library must obtain all currently known
scopes and use them in SA operations. UA API clients should use a
scope obtained through one of the API operations for finding scopes.
Any other scope name may result in a SCOPE_NOT_SUPPORTED error from a
remote agent. The UA API library can optionally check the scope and
return the error without contacting a remote agent.
4. C Language Binding
The C language binding presents a minimal overhead implementation
that maps directly into the protocol. There is one C language
function per protocol request, with the exception of the SLPDereg()
and SLPDelAttrs() functions, which map into different uses of the SLP
deregister request. Parameters are for the most part character
buffers. Memory management is kept simple by having the client
allocate most memory and requiring that client callback functions
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.
4.1. Constant Types
4.1.1. URL Lifetimes
4.1.1.1. Synopsis
typedef enum {
SLP_LIFETIME_DEFAULT = 10800,
SLP_LIFETIME_MAXIMUM = 65535
} SLPURLLifetime;
4.1.1.2. Description
The SLPURLLifetime enum type contains URL lifetime values, in
seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours,
while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the
maximum size of the lifetime field in SLP messages.
4.1.2. Error Codes
4.1.2.1. Synopsis
typedef enum {
SLP_LAST_CALL = 1,
SLP_OK = 0,
SLP_LANGUAGE_NOT_SUPPORTED = -1,
SLP_PARSE_ERROR = -2,
SLP_INVALID_REGISTRATION = -3,
SLP_SCOPE_NOT_SUPPORTED = -4,
SLP_AUTHENTICATION_ABSENT = -6,
SLP_AUTHENTICATION_FAILED = -7,
SLP_INVALID_UPDATE = -13,
SLP_REFRESH_REJECTED = -15,
SLP_NOT_IMPLEMENTED = -17,
SLP_BUFFER_OVERFLOW = -18,
SLP_NETWORK_TIMED_OUT = -19,
SLP_NETWORK_INIT_FAILED = -20,
SLP_MEMORY_ALLOC_FAILED = -21,
SLP_PARAMETER_BAD = -22,
SLP_NETWORK_ERROR = -23,
SLP_INTERNAL_SYSTEM_ERROR = -24,
SLP_HANDLE_IN_USE = -25,
SLP_TYPE_ERROR = -26
} SLPError ;
4.1.2.2. Description
The SLPError enum contains error codes that are returned from API
functions.
The SLP_OK code indicates that the no error occurred during the
operation.
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 can use 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.
4.1.3. SLPBoolean
4.1.3.1. Synopsis
typedef enum {
SLP_FALSE = 0,
SLP_TRUE = 1
} SLPBoolean;
4.1.3.2. Description
The SLPBoolean enum is used as a boolean flag.
4.2. Struct Types
4.2.1. SLPSrvURL
4.2.1.1. Synopsis
typedef struct srvurl {
char *s_pcSrvType;
char *s_pcHost;
int s_iPort;
char *s_pcNetFamily;
char *s_pcSrvPart;
} SLPSrvURL;
4.2.1.2. Description
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. Note that
the structure is in conformance with the standard Berkeley sockets
struct servent, with the exception that the pointer to an array of
characters for aliases (s_aliases field) is replaced by the pointer
to host name (s_pcHost field).
s_pcSrvType
A pointer to a character string containing the service
type name, including naming authority. The service type
name includes the "service:" if the URL is of the service:
scheme. [7]
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 "" (i.e. 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, and the remainder of the URL should
allow further differentiation of the service.
4.2.2. SLPHandle
4.2.2.1. Synopsis
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, since
the exact nature differs depending on the implementation.
4.3. Callbacks
A function pointer to a callback function specific to a particular
API operation is included 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. 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.
In addition to parameters for reporting the results of the operation,
each callback parameter list contains 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).
4.3.1. SLPRegReport
4.3.1.1. Synopsis
typedef void SLPRegReport(SLPHandle hSLP,
SLPError errCode,
void *pvCookie);
4.3.1.2. Description
The SLPRegReport callback type is the type of the callback function
to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions.
4.3.1.3. 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. May be NULL.
4.3.2. SLPSrvTypeCallback
4.3.2.1. Synopsis
typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,
const char* pcSrvTypes,
SLPError errCode,
void *pvCookie);
4.3.2.2. Description
The SLPSrvTypeCallback type is the type of the callback function
parameter to SLPFindSrvTypes() function. If the hSLP handle
parameter was opened asynchronously, the results returned through the
callback MAY be uncollated. If the hSLP handle parameter was opened
synchronously, then the returned results must be collated and
duplicates eliminated.
4.3.2.3. 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. May be NULL.
4.3.2.4. Returns
The client code should return SLP_TRUE if more data is desired,
otherwise SLP_FALSE.
4.3.3. SLPSrvURLCallback
4.3.3.1. Synopsis
typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP,
const char* pcSrvURL,
unsigned short sLifetime,
SLPError errCode,
void *pvCookie);
4.3.3.2. Description
The SLPSrvURLCallback type is the type of the callback function
parameter to SLPFindSrvs() function. If the hSLP handle parameter
was opened asynchronously, the results returned through the callback
MAY be uncollated. If the hSLP handle parameter was opened
synchronously, then the returned results must be collated and
duplicates eliminated.
4.3.3.3. Parameters
hSLP
The SLPHandle used to initiate the operation.
pcSrvURL
A character buffer containing the returned service URL.
sLifetime
An unsigned short giving the life time of the service
advertisement, in seconds. 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. May be NULL.
4.3.3.4. Returns
The client code should return SLP_TRUE if more data is desired,
otherwise SLP_FALSE.
4.3.4. SLPAttrCallback
4.3.4.1. Synopsis
typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP,
const char* pcAttrList,
SLPError errCode,
void *pvCookie);
4.3.4.2. Description
The SLPAttrCallback type is the type of the callback function
parameter to SLPFindAttrs() function.
The behavior of the callback differs depending on 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 regardless of whether the handle was opened
asynchronously or synchronously. The pcAttrList parameter contains
the requested attributes as a comma separated list (or is empty if no
attributes matched the original tag list).
If the SLPFindAttrs() operation was originally called with a service
type, the value of pcAttrList and calling behavior depend on 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
MAY be uncollated between calls. It contains a comma separated list
with the results from the agent that immediately returned results.
If the handle was opened synchronously, the results must be collated
from all returning agents and the callback is called once, with the
pcAttrList parameter set to the collated result.
4.3.4.3. Parameters
hSLP
The SLPHandle used to initiate the operation.
pcAttrList
A character buffer containing a comma separated, null
terminated list of attribute id/value assignments, in SLP wire
format; i.e. "(attr-id=attr-value-list)" [7].
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. May be NULL.
4.3.4.4. Returns
The client code should return SLP_TRUE if more data is desired,
otherwise SLP_FALSE.
4.4. Opening and Closing an SLPHandle
4.4.1. SLPOpen
4.4.1.1. Synopsis
SLPError SLPOpen(const char *pcLang, SLPBoolean isAsync, SLPHandle
*phSLP);
4.4.1.2. Description
Returns a SLPHandle handle in the phSLP parameter for the language
locale passed in as the pcLang parameter. The client indicates if
operations on the handle are to be synchronous or asynchronous
through the isAsync parameter. The handle encapsulates the language
locale for SLP requests issued through the handle, and any other
resources required by the implementation. However, SLP properties
are not encapsulated by the handle; they are global. The return
value of the function is an SLPError code indicating the status of
the operation. Upon failure, the phSLP parameter is NULL.
An SLPHandle can only be used for one SLP API operation at a time.
If the original operation was started asynchronously, any attempt to
start an additional operation on the handle while the original
operation is pending results in the return of an SLP_HANDLE_IN_USE
error from the API function. The SLPClose() API function terminates
any outstanding calls on the handle. If an implementation is unable
to support a asynchronous( resp. synchronous) operation, due to
memory constraints or lack of threading support, the
SLP_NOT_IMPLEMENTED flag may be returned when the isAsync flag is
SLP_TRUE (resp. SLP_FALSE).
4.4.1.3. Parameters
pcLang
A pointer to an array of characters containing the RFC1766
Language Tag [6] for the natural language locale of requests
and registrations issued on the handle.
isAsync
An SLPBoolean indicating whether the SLPHandle should be opened
for asynchronous operation or not.
phSLP
A pointer to an SLPHandle, in which the open SLPHandle is
returned. If an error occurs, the value upon return is NULL.
4.4.2. SLPClose
4.4.2.1. Synopsis
void SLPClose(SLPHandle hSLP);
4.4.2.2. Description
Frees all resources associated with the handle. If the handle was
invalid, the function returns silently. Any outstanding synchronous
or asynchronous operations are cancelled so their callback functions
will not be called any further.
4.4.2.3. Parameters
SLPHandle
A SLPHandle handle returned from a call to SLPOpen().
4.5. Protocol API
4.5.1. SLPReg
4.5.1.1. Synopsis
SLPError SLPReg(SLPHandle hSLP,
const char *pcSrvURL,
const unsigned short usLifetime,
const char *pcSrvType,
const char *pcAttrs
SLPBoolean fresh,
SLPRegReport callback,
void *pvCookie);
4.5.1.2. Description
Registers the URL in pcSrvURL having the lifetime usLifetime with the
attribute list in pcAttrs. The pcAttrs list is a comma separated
list of attribute assignments in the wire format (including escaping
of reserved characters). The usLifetime parameter must be nonzero
and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is
SLP_TRUE, then the registration is new (the SLP protocol FRESH flag
is set) and the registration replaces any existing registrations.
The pcSrvType parameter is a service type name and can be included
for service URLs that are not in the service: scheme. If the URL is
in the service: scheme, the pcSrvType parameter is ignored. If the
fresh flag is SLP_FALSE, then an existing registration is updated.
Rules for new and updated registrations, and the format for pcAttrs
and pcScopeList can be found in [7]. Registrations and updates take
place in the language locale of the hSLP handle.
The API library is required to perform the operation in all scopes
obtained through configuration.
4.5.1.3. Parameters
hSLP
The language specific SLPHandle on which to register the
advertisement.
pcSrvURL
The URL to register. May not be the empty string.
usLifetime
An unsigned short giving the life time of the service
advertisement, in seconds. The value must be an unsigned
integer less than or equal to SLP_LIFETIME_MAXIMUM and greater
than zero.
pcSrvType
The service type. If pURL is a service: URL, then this
parameter is ignored.
pcAttrs
A comma separated list of attribute assignment expressions for
the attributes of the advertisement. Use empty string, "" for
no attributes.
fresh
An SLPBoolean that is SLP_TRUE if the registration is new or
SLP_FALSE if a reregistration.
callback
A callback to report the operation completion status.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.1.4. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.5.2. SLPDereg
4.5.2.1. Synopsis
SLPError SLPDereg(SLPHandle hSLP,
const char *pcURL,
SLPRegReport callback,
void *pvCookie);
4.5.2.2. Description
Deregisters the advertisement for URL pcURL in all scopes where the
service is registered and all language locales. The deregistration
is not just confined to the locale of the SLPHandle, it is in all
locales. The API library is required to perform the operation in all
scopes obtained through configuration.
4.5.2.3. Parameters
hSLP
The language specific SLPHandle to use for deregistering.
pcURL
The URL to deregister. May not be the empty string.
callback
A callback to report the operation completion status.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.2.4. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.5.3. SLPDelAttrs
4.5.3.1. Synopsis
SLPError SLPDelAttrs(SLPHandle hSLP,
const char *pcURL,
const char *pcAttrs,
SLPRegReport callback,
void *pvCookie);
4.5.3.2. Description
Delete the selected attributes in the locale of the SLPHandle. The
API library is required to perform the operation in all scopes
obtained through configuration.
4.5.3.3. Parameters
hSLP
The language specific SLPHandle to use for deleting attributes.
pcURL
The URL of the advertisement from which the attributes should
be deleted. May not be the empty string.
pcAttrs
A comma separated list of attribute ids for the attributes to
deregister. See Section 9.8 in [7] for a description of the
list format. May not be the empty string.
callback
A callback to report the operation completion status.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.3.4. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.5.4. SLPFindSrvTypes
4.5.4.1. Synopsis
SLPError SLPFindSrvTypes(SLPHandle hSLP,
const char *pcNamingAuthority,
const char *pcScopeList,
SLPSrvTypeCallback callback,
void *pvCookie);
The SLPFindSrvType() function issues an SLP service type request for
service types in the scopes indicated by the pcScopeList. The
results are returned through the callback parameter. The service
types are independent of language locale, but only for services
registered in one of scopes and for the indicated naming authority.
If the naming authority is "*", then results are returned for all
naming authorities. If the naming authority is the empty string,
i.e. "", then the default naming authority, "IANA", is used. "IANA"
is not a valid naming authority name, and it is a PARAMETER_BAD error
to include it explicitly.
The service type names are returned with the naming authority intact.
If the naming authority is the default (i.e. empty string) then it
is omitted, as is the separating ".". Service type names from URLs
of the service: scheme are returned with the "service:" prefix
intact. [7] See [8] for more information on the syntax of service
type names.
4.5.4.2. Parameters
hSLP
The SLPHandle on which to search for types.
pcNamingAuthority
The naming authority to search. Use "*" for all naming
authorities and the empty string, "", for the default naming
authority.
pcScopeList
A pointer to a char containing comma separated list of scope
names to search for service types. May not be the empty
string, "".
callback
A callback function through which the results of the operation
are reported.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.4.3. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.5.5. SLPFindSrvs
4.5.5.1. Synopsis
SLPError SLPFindSrvs(SLPHandle hSLP,
const char *pcServiceType,
const char *pcScopeList,
const char *pcSearchFilter,
SLPSrvURLCallback callback,
void *pvCookie);
4.5.5.2. Description
Issue the query for services on the language specific SLPHandle and
return the results through the callback. The parameters determine
the results
4.5.5.3. Parameters
hSLP
The language specific SLPHandle on which to search for
services.
pcServiceType
The Service Type String, including authority string if any, for
the request, such as can be discovered using SLPSrvTypes().
This could be, for example "service:printer:lpr" or
"service:nfs". May not be the empty string.
pcScopeList
A pointer to a char containing comma separated list of scope
names. May not be the empty string, "".
pcSearchFilter
A query formulated of attribute pattern matching expressions in
the form of a LDAPv3 Search Filter, see [4]. If this filter
is empty, i.e. "", all services of the requested type in the
specified scopes are returned.
callback
A callback function through which the results of the operation
are reported.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.5.4. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.5.6. SLPFindAttrs
4.5.6.1. Synopsis
SLPError SLPFindAttrs(SLPHandle hSLP,
const char *pcURLOrServiceType,
const char *pcScopeList,
const char *pcAttrIds,
SLPAttrCallback callback,
void *pvCookie);
4.5.6.2. Description
This function returns service attributes matching the attribute ids
for the indicated service URL or service type. If pcURLOrServiceType
is a service URL, the attribute information returned is for that
particular advertisement in the language locale of the SLPHandle.
If pcURLOrServiceType is a service type name (including naming
authority if any), then the attributes for all advertisements of that
service type are returned regardless of the language of registration.
Results are returned through the callback.
The result is filtered with an SLP attribute request filter string
parameter, the syntax of which is described in [7]. If the filter
string is the empty string, i.e. "", all attributes are returned.
4.5.6.3. Parameters
hSLP
The language specific SLPHandle on which to search for
attributes.
pcURLOrServiceType
The service URL or service type. See [7] for URL and service
type syntax. May not be the empty string.
pcScopeList
A pointer to a char containing a comma separated list of scope
names. May not be the empty string, "".
pcAttrIds
The filter string indicating which attribute values to return.
Use empty string, "", to indicate all values. Wildcards
matching all attribute ids having a particular prefix or suffix
are also possible. See [7] for the exact format of the filter
string.
callback
A callback function through which the results of the operation
are reported.
pvCookie
Memory passed to the callback code from the client. May be
NULL.
4.5.6.4. Returns
If an error occurs in starting the operation, one of the SLPError
codes is returned.
4.6. Miscellaneous Functions
4.6.1. SLPGetRefreshInterval
4.6.1.1. Synopsis
unsigned short SLPGetRefreshInterval();
4.6.1.2. Description
Returns the maximum across all DAs of the min-refresh-interval
attribute. This value satisfies the advertised refresh interval
bounds for all DAs, and, if used by the SA, assures that no refresh
registration will be rejected. If no DA advertises a min-refresh-
interval attribute, a value of 0 is returned.
4.6.1.3. Returns
If no error, the maximum refresh interval value allowed by all DAs (a
positive integer). If no DA advertises a min-refresh-interval
attribute, returns 0. If an error occurs, returns an SLP error code.
4.6.2. SLPFindScopes
4.6.2.1. Synopsis
SLPError SLPFindScopes(SLPHandle hSLP,
char** ppcScopeList);
4.6.2.2. Description
Sets ppcScopeList parameter to a pointer to a comma separated list
including all available scope values. The list of scopes comes from
a variety of sources: the configuration file's net.slp.useScopes
property, unicast to DAs on the net.slp.DAAddresses property, DHCP,
or through the DA discovery process. If there is any order to the
scopes, preferred scopes are listed before less desirable scopes.
There is always at least one name in the list, the default scope,
"DEFAULT".
4.6.2.3. Parameters
hSLP
The SLPHandle on which to search for scopes.
ppcScopeList
A pointer to char pointer into which the buffer pointer is
placed upon return. The buffer is null terminated. The memory
should be freed by calling SLPFree().
4.6.2.4. Returns
If no error occurs, returns SLP_OK, otherwise, the appropriate error
code.
4.6.3. SLPParseSrvURL
4.6.3.1. Synopsis
SLPError SLPParseSrvURL(char *pcSrvURL
SLPSrvURL** ppSrvURL);
4.6.3.2. Description
Parses the URL passed in as the argument into a service URL structure
and returns it in the ppSrvURL pointer. If a parse error occurs,
returns SLP_PARSE_ERROR. The input buffer pcSrvURL is destructively
modified during the parse and used to fill in the fields of the
return structure. The structure returned in ppSrvURL should be freed
with SLPFreeURL(). If the URL has no service part, the s_pcSrvPart
string is the empty string, "", i.e. not NULL. If pcSrvURL is not a
service: URL, then the s_pcSrvType field in the returned data
structure is the URL's scheme, which might not be the same as the
service type under which the URL was registered. If the transport is
IP, the s_pcTransport field is the empty string. If the transport is
not IP or there is no port number, the s_iPort field is zero.
4.6.3.3. Parameters
pcSrvURL
A pointer to a character buffer containing the null terminated
URL string to parse. It is destructively modified to produce
the output structure.
ppSrvURL
A pointer to a pointer for the SLPSrvURL structure to receive
the parsed URL. The memory should be freed by a call to
SLPFree() when no longer needed.
4.6.3.4. Returns
If no error occurs, the return value is SLP_OK. Otherwise, the
appropriate error code is returned.
4.6.4. SLPEscape
4.6.4.1. Synopsis
SLPError SLPEscape(const char* pcInbuf,
char** ppcOutBuf,
SLPBoolean isTag);
4.6.4.2. Description
Process the input string in pcInbuf and escape any SLP reserved
characters. If the isTag parameter is SLPTrue, then look for bad tag
characters and signal an error if any are found by returning the
SLP_PARSE_ERROR code. The results are put into a buffer allocated by
the API library and returned in the ppcOutBuf parameter. This buffer
should be deallocated using SLPFree() when the memory is no longer
needed.
4.6.4.3. Parameters
pcInbuf
Pointer to he input buffer to process for escape characters.
ppcOutBuf
Pointer to a pointer for the output buffer with the SLP
reserved characters escaped. Must be freed using SLPFree()
when the memory is no longer needed.
isTag
When true, the input buffer is checked for bad tag characters.
4.6.4.4. Returns
Return SLP_PARSE_ERROR if any characters are bad tag characters and
the isTag flag is true, otherwise SLP_OK, or the appropriate error
code if another error occurs.
4.6.5. SLPUnescape
4.6.5.1. Synopsis
SLPError SLPUnescape(const char* pcInbuf,
char** ppcOutBuf,
SLPBoolean isTag);
4.6.5.2. Description
Process the input string in pcInbuf and unescape any SLP reserved
characters. If the isTag parameter is SLPTrue, then look for bad tag
characters and signal an error if any are found with the
SLP_PARSE_ERROR code. No transformation is performed if the input
string is an opaque. The results are put into a buffer allocated by
the API library and returned in the ppcOutBuf parameter. This buffer
should be deallocated using SLPFree() when the memory is no longer
needed.
4.6.5.3. Parameters
pcInbuf
Pointer to he input buffer to process for escape characters.
ppcOutBuf
Pointer to a pointer for the output buffer with the SLP
reserved characters escaped. Must be freed using SLPFree()
when the memory is no longer needed.
isTag
When true, the input buffer is checked for bad tag characters.
4.6.5.4. Returns
Return SLP_PARSE_ERROR if any characters are bad tag characters and
the isTag flag is true, otherwise SLP_OK, or the appropriate error
code if another error occurs.
4.6.6. SLPFree
4.6.6.1. Synopsis
void SLPFree(void* pvMem);
4.6.6.2. Description
Frees memory returned from SLPParseSrvURL(), SLPFindScopes(),
SLPEscape(), and SLPUnescape().
4.6.6.3. Parameters
pvMem
A pointer to the storage allocated by the SLPParseSrvURL(),
SLPEscape(), SLPUnescape(), or SLPFindScopes() function.
Ignored if NULL.
4.6.7. SLPGetProperty
4.6.7.1. Synopsis
const char* SLPGetProperty(const char* pcName);
4.6.7.2. Description
Returns the value of the corresponding SLP property name. The
returned string is owned by the library and MUST NOT be freed.
4.6.7.3. Parameters
pcName
Null terminated string with the property name, from
Section 2.1.
4.6.7.4. Returns
If no error, returns a pointer to a character buffer containing the
property value. If the property was not set, returns the default
value. If an error occurs, returns NULL. The returned string MUST
NOT be freed.
4.6.8. SLPSetProperty
4.6.8.1. Synopsis
void SLPSetProperty(const char *pcName,
const char *pcValue);
4.6.8.2. Description
Sets the value of the SLP property to the new value. The pcValue
parameter should be the property value as a string.
4.6.8.3. Parameters
pcName
Null terminated string with the property name, from
Section 2.1.
pcValue
Null terminated string with the property value, in UTF-8
character encoding.
4.7. Implementation Notes
4.7.1. Refreshing Registrations
Clients indicate that they want URLs to be automatically refreshed by
setting the usLifetime parameter in the SLPReg() function call to
SLP_LIFETIME_MAXIMUM. This will cause the API implementation to
refresh the URL before it times out. Although using
SLP_LIFETIME_MAXIMUM to designate automatic reregistration means that
a transient URL can't be registered for the maximum lifetime, little
hardship is likely to occur, since service URL lifetimes are measured
in seconds and the client can simply use a lifetime of
SLP_LIFETIME_MAXIMUM - 1 if a transient URL near the maximum lifetime
is desired. API implementations MUST provide this facility.
4.7.2. Syntax for String Parameters
Query strings, attribute registration lists, attribute deregistration
lists, scope lists, and attribute selection lists follow the syntax
described in [7] for the appropriate requests. The API directly
reflects the strings passed in from clients into protocol requests,
and directly reflects out strings returned from protocol replies 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 functions SLPEscape() and SLPUnescape() can
be used for escaping SLP reserved characters, but perform no opaque
processing.
Opaque values consist of a character buffer containing a UTF-8-
encoded string, the first characters of which are the nonUTF-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.
4.7.3. Client Side Syntax Checking
Client side API implementations may do syntax checking of scope
names, naming authority names, and service type names, but are not
required to do so. Since the C API is designed to be a thin layer
over the protocol, some low memory SA implementations may find
extensive syntax checking on the client side to be burdensome. If
syntax checking uncovers an error in a parameter, the
SLP_PARAMETER_BAD error must be returned. If any parameter is NULL
and is required to be nonNULL, SLP_PARAMETER_BAD is returned.
4.7.4. System Properties
The system properties established in the configuration file are
accessible through the SLPGetProperty() and SLPSetProperty()
functions. The SLPSetProperty() function only modifies properties in
the running process, not in the configuration file. Properties are
global to the process, affecting all threads and all handles created
with SLPOpen. Errors are checked when the property is used and, as
with parsing the configuration file, are logged. Program execution
continues without interruption by substituting the default for the
erroneous parameter. With the exception of net.slp.locale,
net.slp.typeHint, and net.slp.maxResults, clients of the API 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.
4.7.5. Memory Management
The only API functions returning memory specifically requiring
deallocation on the part of the client are SLPParseSrvURL(),
SLPFindScopes(), SLPEscape(), and SLPUnescape(). This memory should
be freed using SLPFree() when no longer needed. Character strings
returned via the SLPGetProperty() function should NOT be freed, they
are owned by the SLP library.
Memory passed to callbacks belongs to the library and MUST NOT be
retained by the client code. Otherwise, crashes are possible.
Clients are required to copy data out of the callback parameters. No
other use of the parameter memory in callback parameters is allowed.
4.7.6. Asynchronous and Incremental Return Semantics
If a handle parameter to an API function was opened asynchronously,
API function calls on the handle check the other parameters, open the
appropriate operation and return immediately. In an error occurs in
the process of starting the operation, an error code is returned. If
the handle parameter was opened synchronously, the API function call
blocks until all results are available, and returns only after the
results are reported through the callback function. The return code
indicates whether any errors occurred both starting and 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 invalid. The API library
has the option of terminating 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. Callback
functions are not permitted to recursively call into the API on the
same SLPHandle. If an attempt is made to recursively 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. On the other hand, it means
that handle creation should be fairly lightweight so a client program
can easily support multiple outstanding calls.
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 a while 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
4.8. Example
This example illustrates how to discover a mailbox.
A POP3 server registers itself with the SLP framework. The
attributes it registers are "USER", a list of all users whose mail is
available through the POP3 server.
The POP3 server code is the following:
SLPHandle slph;
SLPRegReport errCallback = POPRegErrCallback;
/* Create an English SLPHandle, asynchronous processing. */
SLPError err = SLPOpen("en", SLP_TRUE, &slph);
if( err != SLP_OK ) {
/* Deal with error. */
}
/* Create the service: URL and attribute parameters. */
const char* surl = "service:pop3://mail.netsurf.de"; /* the URL */
const char *pcAttrs = "(user=zaphod,trillian,roger,marvin)"
/* Perform the registration. */
err = SLPReg(slph,
surl,
SLP_LIFETIME_DEFAULT,
ppcAttrs,
errCallback,
NULL);
if (err != SLP_OK ) {
/*Deal with error.*/
}
The errCallback reports any errors:
void
POPRegErrCallback(SLPHandle hSLP,
SLPError errCode,
unsigned short usLifetime,
void* pvCookie) {
if( errCode != SLP_OK ) {
/* Report error through a dialog, message, etc. */
}
/*Use lifetime interval to update periodically. */
}
The POP3 client locates the server for the user with the following
code:
/*
* The client calls SLPOpen(), exactly as above.
*/
const char *pcSrvType = "service:pop3"; /* the service type */
const char *pcScopeList = "default"; /* the scope */
const char *pcFilter = "(user=roger)"; /* the search filter */
SLPSrvURLCallback srvCallback = /* the callback */
POPSrvURLCallback;
err = SLPFindSrvs(slph,
pcSrvType, pcScopeList, pcFilter,
srvCallback, NULL);
if( err != SLP_OK ) {
/* Deal with error. */
}
Within the callback, the client code can use the returned POP
service:
SLPBoolean
POPSrvURLCallback(SLPHandle hSLP,
const char* pcSrvURL,
unsigned short sLifetime,
SLPError errCode,
void* pvCookie) {
if( errCode != SLP_OK ) {
/* Deal with error. */
}
SLPSrvURL* pSrvURL;
errCode = SLPParseSrvURL(pcSrvURL, &pSrvURL);
if (err != SLP_OK ) {
/* Deal with error. */
} else {
/* get the server's address */
struct hostent *phe = gethostbyname(pSrvURL.s_pcHost);
/* use hostname in pSrvURL to connect to the POP3 server
* . . .
*/
SLPFreeSrvURL((void*)pSrvURL); /* Free the pSrvURL storage */
}
return SLP_FALSE; /* Done! */
}
A client that wanted to discover all the users receiving mail at the
server uses with the following query:
/*
* The client calls SLPOpen(), exactly as above. We assume the
* service: URL was retrieved into surl.
*/
const char *pcScopeList = "default"; /* the scope */
const char *pcAttrFilter = "use"; /* the attribute filter */
SLPAttrCallback attrCallBack = /* the callback */
POPUsersCallback
err =
SLPFindAttrs(slph,
surl,
pcScopeList, pcAttrFilter,
attrCallBack, NULL);
if( err != SLP_OK ) {
/* Deal with error. */
}
The callback processes the attributes:
SLPBoolean
POPUsersCallback(const char* pcAttrList,
SLPError errCode,
void* pvCookie) {
if( errCode != SLP_OK ) {
/* Deal with error. */
} else {
/* Parse attributes. */
}
return SLP_FALSE; /* Done! */
}
5. Java Language Binding
5.1. Introduction
The Java API is designed to model the various SLP entities in classes
and objects. APIs are provided for SA, UA, and service type template
access capabilities. The ServiceLocationManager class contains
methods that return instances of objects implementing SA and UA
capability. Each of these is modeled in an interface. The Locator
interface provides UA capability and the Advertiser interface
provides SA capability. The TemplateRegistry abstract class contains
methods that return objects for template introspection and attribute
type checking. The ServiceURL, ServiceType, and
ServiceLocationAttribute classes model the basic SLP concepts. A
concrete subclass instance of TemplateRegistry is returned by a class
method.
All SLP classes and interfaces are located within a single package.
The package name should begin with the name of the implementation and
conclude with the suffix "slp". Thus, the name for a hypothetical
implementation from the University of Michigan would look like:
edu.umich.slp
This follows the Java convention of prepending the top level DNS
domain name for the organization implementing the package onto the
organization's name and using that as the package prefix.
5.2. Exceptions and Errors
Most parameters to API methods are required to be non-null. The API
description indicates if a null parameter is acceptable, or if other
restrictions constrain a parameter. When parameters are checked for
validity (such as not being null) or their syntax is checked, an
error results in the RuntimeException subclass
IllegalArgumentException being thrown. Clients of the API are
reminded that IllegalArgumentException, derived from
RuntimeException, is unchecked by the compiler. Clients should thus
be careful to include try/catch blocks for it if the relevant
parameters could be erroneous.
Standard Java practice is to encode every exceptional condition as a
separate subclass of Exception. Because of the relatively high cost
in code size of Exception subclasses, the API contains only a single
Exception subclass with different conditions being determined by an
integer error code property. A subset, appropriate to Java, of the
error codes described in Section 3 are available as constants on the
ServiceLocationException class. The subset excludes error codes such
as MEMORY_ALLOC_FAILED.
5.2.1. Class ServiceLocationException
5.2.1.1. Synopsis
public class ServiceLocationException
extends Exception
5.2.1.2. Description
The ServiceLocationException class is thrown by all methods when
exceptional conditions occur in the SLP framework. The error code
property determines the exact nature of the condition, and an
optional message may provide more information.
5.2.1.3. Fields
public static final short LANGUAGE_NOT_SUPPORTED = 1
public static final short PARSE_ERROR = 2
public static final short INVALID_REGISTRATION = 3
public static final short SCOPE_NOT_SUPPORTED = 4
public static final short AUTHENTICATION_ABSENT = 6
public static final short AUTHENTICATION_FAILED = 7
public static final short INVALID_UPDATE = 13
public static final short REFRESH_REJECTED = 15
public static final short NOT_IMPLEMENTED = 16
public static final short NETWORK_INIT_FAILED 17
public static final short NETWORK_TIMED_OUT = 18
public static final short NETWORK_ERROR = 19
public static final short INTERNAL_SYSTEM_ERROR = 20
public static final short TYPE_ERROR = 21
public static final short BUFFER_OVERFLOW = 22
5.2.1.4. Instance Methods
public short getErrorCode()
Return the error code. The error code takes on one of the static
field values.
5.3. Basic Data Structures
5.3.1. Interface ServiceLocationEnumeration
public interface ServiceLocationEnumeration
extends Enumeration
5.3.1.1. Description
The ServiceLocationEnumeration class is the return type for all
Locator SLP operations. The Java API library may implement this
class to block until results are available from the SLP operation, so
that the client can achieve asynchronous operation by retrieving
results from the enumeration in a separate thread. Clients use the
superclass nextElement() method if they are unconcerned with SLP
exceptions.
5.3.1.2. Instance Methods
public abstract Object next() throws ServiceLocationException
Return the next value or block until it becomes available.
Throws:
ServiceLocationException
Thrown if the SLP operation encounters an error.
NoSuchElementException
If there are no more elements to return.
5.3.2. Class ServiceLocationAttribute
5.3.2.1. Synopsis
public class ServiceLocationAttribute
extends Object implements Serializable
5.3.2.2. Description
The ServiceLocationAttribute class models SLP attributes. Instances
of this class are returned by Locator.findAttributes() and are
communicated along with register/deregister requests.
5.3.2.3. Constructors
public ServiceLocationAttribute(String id,Vector values)
Construct a service location attribute. Errors in the id or values
vector result in an IllegalArgumentException.
Parameters:
id
The attribute name. The String can consist of any Unicode