Service Location Protocol Library Functions slp_api(3SLP)
NAME
slp_api - Service Location Protocol Application Programming
InterfaceSYNOPSIS
cc [ flag ... ] file ... -lslp [ library ... ]
#include
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. Withthe 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 perprotocol request. Parameters are for the most part char-
acter buffers. Memory management is kept simple because the client allocates most memory and client callback functionsare required to copy incoming parameters into memory allo-
cated by the client code. Any memory returned directly fromthe API functions is deallocated using the SLPFree() func-
tion. To conform with standard C practice, all character stringspassed 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 bythe API client as UTF-8. In the common case of US-ASCII,
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 andcallbacks are non-NULL. Some parameters may have other res-
trictions. If any parameter fails to satisfy the restric-
tions 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 APIreflects 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, includingescaping and converting opaque values to escaped byte-
encoded strings. Similarly, on output, clients are requiredSunOS 5.11 Last change: 16 Jan 2003 1
Service Location Protocol Library Functions slp_api(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 aUTF-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 encodingthe byte. An example is "2c" for the byte 0x2c. Clients han-
dle opaque processing themselves, since the algorithm is relatively simple and uniform. System PropertiesThe 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, arelogged 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 theyreflect 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 specificallyrequiring deallocation on the part of the client are SLPPar-
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 SemanticsSunOS 5.11 Last change: 16 Jan 2003 2
Service Location Protocol Library Functions slp_api(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 checkthe error code parameter before looking at the other parame-
ters. If the error code is not SLP_OK, the other parameters
may be NULL 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 operationshould be terminated by passing back SLP_FALSE 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 callinto the API, the API function returns SLP_HANDLE_IN_USE.
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 valueSLP_LAST_CALL. 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 haselapsed 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 isSunOS 5.11 Last change: 16 Jan 2003 3
Service Location Protocol Library Functions slp_api(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 specifythe location of this file with the SLP_CONF_FILE environment
variable. If you do not set this variable, or the file itrefers 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 {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 registrationSLP_LIFETIME_MAXIMUM causes the advertisement to be continu-
ally 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;
SunOS 5.11 Last change: 16 Jan 2003 4
Service Location Protocol Library Functions slp_api(3SLP)
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. Pos-
sible 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 shouldallow 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 slp_api(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 isowned 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 valuereturned from the callback is SLP_TRUE, 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 NULL. SLPSrvTypeCallback() typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,SunOS 5.11 Last change: 16 Jan 2003 6
Service Location Protocol Library Functions slp_api(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 thanSLP_OK, 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 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 wasopened 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 slp_api(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 toSLP_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 thanSLP_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 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 therequested 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 callingbehavior 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 iscollated between calls, and contains a comma-separated list
SunOS 5.11 Last change: 16 Jan 2003 8
Service Location Protocol Library Functions slp_api(3SLP)
of the results from the agent that immediately returned. Ifthe 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 thanSLP_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 nomore data for them and there-
fore no further calls will be made to the callback on thecurrently 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 acallback during both a syn-
chronous and asynchronous call, the error code parameterSunOS 5.11 Last change: 16 Jan 2003 9
Service Location Protocol Library Functions slp_api(3SLP)
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 setto 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 adver-
tisement 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 theAPI may be malformed or dam-
aged 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 leastone DA accepts the registra-
tion.SLP_SCOPE_NOT_SUPPORTED 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 scopeSunOS 5.11 Last change: 16 Jan 2003 10
Service Location Protocol Library Functions slp_api(3SLP)
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 mes-
sage 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 thanthat in the initial registra-
tion.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.SunOS 5.11 Last change: 16 Jan 2003 11
Service Location Protocol Library Functions slp_api(3SLP)
SLP_NETWORK_INIT_FAILED If the network cannot initial-
ize properly, this error is returned.SLP_MEMORY_ALLOC_FAILED If the API fails to allocate
memory, the operationis 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 dur-
ing 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 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 advertisementSLPDereg() deregister a service advertise-
mentSunOS 5.11 Last change: 16 Jan 2003 12
Service Location Protocol Library Functions slp_api(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 SLPParseSrvURL() parse service URL SLPEscape() escape special characters SLPUnescape() translate escaped characters intoUTF-8
SLPGetProperty() return SLP configuration property SLPSetProperty() set an SLP configuration propertyslp_strerror() map SLP error code to message
SLPFree() free memory ENVIRONMENT VARIABLESWhen SLP_CONF_FILE is set, use this file for configuration.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 16 Jan 2003 13
Service Location Protocol Library Functions slp_api(3SLP)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | service/network/slp ||_____________________________|_____________________________|
| 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