libslp(3N)

NAME

libslp: SLPOpen(), SLPClose(), SLPReg(), SLPDereg(), SLPDelAttrs(), SLPFindSrvs(), SLPFindSrvTypes(), SLPFindAttrs(), SLPParseSrvURL(), SLPEscape(), SLPUnescape(), SLPFree(), SLPGetRefreshInterval(), SLPFindScopes(), SLPGetProperty(), SLPSetProperty() — SLP (Service Location Protocol) library routines

SYNOPSIS

#include <slp.h>
cc [ flag... ] file... -lslp [ library... ]

SLPError SLPOpen(
     cnst char *lang,
     SLPBoolean isasync,
     SLPHandle *hslp,
);

void SLPClose(
     SLPHandle *hslp
);

SLPError SLPReg(
     SLPHandle hslp,
     const char* srvurl,
     unsigned short lifetime,
     const char* srvtype,
     const char* attrs,
     SLPBoolean fresh,
     SLPRegReport callback,
     void* cookie
);

SLPError SLPDereg(
     SLPHandle hslp,
     const char* srvurl,
     SLPRegReport callback,
     void* cookie
);

SLPError SLPDelAttrs(
     SLPHandle hslp,
     const char* srvurl,
     const char* attrs,
     SLPRegReport callback,
     void* cookie
);

SLPError SLPFindSrvs(
     SLPHandle hslp,
     const char* srvtype,
     const char* scopelist,
     const char* filter,
     SLPSrvURLCallback callback,
     void* cookie
);

SLPError SLPFindSrvTypes(
     SLPHandle hslp,
     const char* namingauthority,
     const char* scopelist,
     SLPSrvURLCallback callback,
     void* cookie
);

SLPError SLPFindAttrs(:
     SLPHandle hslp,
     const char* srvurlorsrvtype,
     const char* scopelist,
     const char* attrids,
     SLPSrvURLCallback callback,
     void* cookie
);

DESCRIPTION

The SLP (Service Location Protocol) library routines provide a standard interface for writing application programs that are SLP enabled. The SLP API is an interface that allows programmers to write client and server applications to provide dynamic service discovery and selection.

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 are provided that 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.

Arguments

lang

points to the language tag to be used.

isasync

denotes whether the required operation is to be done asynchronously or synchronously. Currently only synchronous operation is supported.

srvurl

is the URL to be registered/deregistered.

lifetime

is the lifetime of the Service URL to be registered in seconds less than or equal to SLP_LIFETIME_MAXIMUM and greater than zero.

srvtype

is the service type name in the service:scheme format.

attrs

is the list of attributes of the service type.

fresh

is used with SLP service registration and denotes whether the registration request is a new one or if it is a request for update of existing registration. Currently updating an existing registration is not supported.

Note: Currently asynchronous operations and incremental registrations are not supported. Hence isasync has be set to SLP_FALSE always, and fresh has to be set to SLP_TRUE. Otherwise an SLP_NOT_IMPLEMENTED error is returned.

callback

is a pointer to a callback function of appropriate type that will be called for processing the reply.

cookie

is the pointer to memory passed from the application to the SLP library for the callback to fill the return values.

scopelist

is the comma-separated list of scopes.

filter

is a pattern matching expression formed of attributes in LDAPv3 search filter syntax, which will be used by the server to filter the results.

namingauthority

is the naming authority to search for.

Callbacks

The callback function allows the application developer to control the processing of the results of the library calls. With asynchronous programming calls, it allows the program code, which passes the callback function as one of the paramaters to the library function, to continue to perform its job, while the result of that operation is being evaluated by the callback function.

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 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 the value, SLP_LAST_CALL.

Primary Routines

SLPOpen()

Returns an SLPHandle handle in the hslp parameter for the language locale passed in as the lang parameter. The handle encapsulates the language locale for SLP requests issued through the handle, and any other resources required by the implementation. The return value of the function is an SLPError code indicating the status of the operation. Upon failure, the hslp parameter is set to 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.

Currently asynchronous operation is not supported. If the isasync parameter is set to SLP_TRUE, SLP_NOT_IMPLEMENTED is returned.

lang is a pointer to a null terminated array of characters containing the RFC 1766 Language Tag. Pass in NULL or the empty string, "" , to use the locale the machine is configured to use.

Currently English is the only supported language tag. Any other value passed to langtag will cause SLP_NOT_IMPLEMENTED to be returned.

Return values are:

SLP_OK
SLP_PARAMETER_BAD
SLP_NOT_IMPLEMENTED
SLP_MEMORY_ALLOC_FAILED

SLPClose()

Frees all resources associated with the handle hslp. If the handle was invalid, the functions returns silently. Any outstanding synchronous or asynchronous operations are cancelled so their callback functions will not be called any longer.

SLPReg()

Registers the URL in srvurl having the lifetime, lifetime, and the attribute list in attrs. The attrs list is a comma separated list of attribute assignments in the wire format (including escaping of reserved characters). The lifetime parameter must be nonzero and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh argument is SLP_TRUE, then the registration is new (the SLP protocol FRESH flag is set), and the registration replaces any existing registrations. The srvtype 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 srvtype parameter is ignored. If the fresh argument is SLP_FALSE, then an existing registration is updated.

The service URL to be registered must conform to the SLP Service URL syntax, and it may not be the empty string or NULL. SLP_INVALID_REGISTRATION will be returned if srvurl is not a SLP Service URL.

If lifetime is set to SLP_LIFETIME_MAXIMUM, it will remain registered for the lifetime of the calling process.

The srvtype parameter is always ignored because the Service URL syntax required for the srvurl parameter encapsulates the service-type.

Attributes list consists of comma separated attribute assignment expressions for the registered service. If no attributes are to be provided, use an empty string "" when registering services.

Example: (attr1=val1),(attr2=val2),(attr3=val3)

SLPDereg()

Deregisters the advertisement for URL srvurl in all scopes where the service is registered in 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.

SLPFindSrvs()

Issue a query for services.

SLPFindSrvTypes()

The SLPFindSrvTypes() function issues an SLP service type request for service types in the scopes indicated by the scopelist. 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. It is not valid to specify "IANA" explicitly as a naming authority, and it will be taken by default. It will return SLP_PARAMETER_BAD error if it is included 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.

SLPFindAttrs()

This function returns service attributes matching the attrids for the indicated Service URL or service type. If srvurlorsrvtype is a service type name, then the attributes for all the registrations of that service type are returned.

Callback Functions

Callback functions are required for all of the major SLP APIs that have been mentioned above. The callback functions and their semantics are listed below.

The parameters include:

hslp: is the SLP handle.
errcode: is a variable that is used to pass the status of the operation to the callback function by the library function.
cookie: is a pointer to memory passed on by the application code to the SLP library call.
srvurl: contains the SLP service URL of the requested service.
lifetime: is the lifetime of the service in seconds.
attrlist: is a pointer to a buffer containing a comma separated null terminated list of attribute id/value assignments in SLP wire format (attr-id=attr-value-list) .

The functions are:

typedef void SLPRegReport(SLPHandle hslp, SLPError errcode,
                          void* cookie)

The SLPRegReport callback type is used as the type for the callback function that is passed in to the SLPReg(), SLPDeReg() and SLPDelAttrs() functions. This callback function does not return any value.

typedef SLPBoolean SLPSrvURLCallback(SLPHandle hslp,
                                     const char* srvurl,
                                     unsigned short lifetime,
                                     SLPError errcode,
                                     void* cookie)

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. The callback should return SLP_TRUE if more data is desired. The callback may continue to return SLP_TRUE until it is called with an errcode of SLP_LAST_CALL. If no more data is requested the callback should return SLP_FALSE.

typedef SLPBoolean SLPAttrCallback(SLPHandle hslp,
                                    const char* attrlist,
                                    SLPError errcode,
                                    void* cookie)

The SLPAttrCallback type is the type of callback function passed as a parameter to the SLPFindAttrs() function. The behavior of the library differs depending on whether the attribute request was by Service URL or by service type.
If the SLPFindAttrs() function was called with a Service URL, then the callback is called once regardless of whether the handle was opened asynchronously or synchronously. The attrlist parameter will contain a comma separated list of attributes.
If the SLPFindAttrs() function was called with a service type, then the callback is called until no more results are available. The attrlist parameter will contain a comma separated list of attributes. Replies from SA's and DA's will be collated to remove duplicates if SLPFindAttrs() was called synchronously. But when called asynchronously the attrlist may return duplicates.
The callback should return SLP_TRUE if more data is desired. The callback may continue to return SLP_TRUE until it is called with an errcode of SLP_LAST_CALL. If no more data is requested the callback should return SLP_FALSE.

Miscellaneous routines

The following are the routines for parsing the service URL.

SLPParseSrvURL(const char* srvurl, SLPSrvURL** parsedurl)

Parses a Service URL passed in as a null terminated character string and returns the results in a pointer to a dynamically allocated SLPSrvURL structure. The pointer returned in parsedurl should be freed by SLPFree().
SLPSrvURL structure is defined in <slp.h> as follows:
typedef struct srvurl { char *s_pcSrvType; char *s_pcHost; int s_iPort; char *s_pcNetFamily; char *s_pcSrvPart; } SLPSrvURL;

SLPError SLPEscape(const char* unescaped,
                   char** escaped, SLPBoolean istag)

Processes the input string to escape any SLP reserved characters and returns the escaped string in dynamically allocated memory. If the istag parameter is SLP_TRUE, then SLPEscape() will look for bad tag characters.

SLPError SLPUnescape(const char* escaped, char** unescaped,
                     SLPBoolean istag)

Process the input escaped string to unescape any SLP reserved characters. The unescaped string is returned in dynamically allocated memory the pointer to which is returned in unescaped. The memory should be freed by calling SLPFree() when no longer needed. If the istag parameter is SLP_TRUE, then SLPUnEscape() will look for bad tag characters.

void SLPFree (void* mem)

Frees memory that was returned from SLPParseSrvURL(), SLPFindScopes(), SLPEscape(), and SLPUnescape().

The following routines may be used to determine the configuration of SLP on the local machine and on the network.

unsigned short SLPGetRefreshInterval(void)

Returns the minimum refresh interval that will be accepted by all SLP SA and DA agents on the network.
This call is not implemented and always returns SLP_NOT_IMPLEMENTED.

SLPError SLPFindScopes(SLPHandle hslp,
                       char** scopelist)

Sets the scopelist parameter to a pointer to a comma separated list of all available scope values. The most desirable values are always placed first in the list. There is always one value, "DEFAULT", in the list.
The memory for the scopelist is dynamically allocated. The memory should be freed by a call to SLPFree() when no longer needed.

const char* SLPGetProperty(const char* name)

Returns the value of the corresponding SLP property name. The returned string is owned by the library and MUST NOT be freed. The returned pointer to string is a pointer to static memory.

void SLPSetProperty(const char* name, const char* value):

This function is supposed to allow the caller to set SLP properties, but it is impossible to implement this function along with SLPGetProperty() in a way that is even remotely thread safe. Therefore, SLP implementation completely ignores all calls made to SLPSetProperty() so that SLPGetProperty() can be used in threaded applications. Note:
1.
If SLP_NETWORK_INIT_FAILED is returned, then probably slpd is not running. For flexibility, OpenSLP() does not require slpd to be running on all hosts, but it does require it to be running on those hosts that will be registering and deregistering services.
2.
Currently SLPDelAttrs() function is not implemented. Instead of calling SLPDelAttrs(), developers writing SLP enabled code should use simply SLPDeReg() to de-register the entire service then call SLPReg() to re-register the service without the undesired attributes.

RETURN VALUE

If successful, returns SLP_OK, else it returns one of the SLPError codes. See SLPError(3N) for error return values.

AUTHOR

SLP was developed by Caldera Systems, Inc.

STANDARDS CONFORMANCE

RFC 2614, RFC2608