Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

slpdelattrs(3n) [hpux man page]

libslp(3N)																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
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 selec- tion. 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 and 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 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 param- eter fails to satisfy the restrictions on its value, the operation returns a 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 and greater than zero. srvtype is the service type name in the 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 always, and fresh has to be set to Otherwise an 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 fil- ter 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 con- tinue 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 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 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 If an attempt is made to call the API, the API function returns Prohibiting recursive callbacks on the same handle simplifies implementa- tion 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, Primary Routines Returns an 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 func- tion is an code indicating the status of the operation. Upon failure, the hslp parameter is set to NULL. An 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 error from the API func- tion. Currently asynchronous operation is not supported. If the isasync parameter is set to 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 to be returned. Return values are: Frees all resources associated with the handle hslp. If the handle was invalid, the functions returns silently. Any outstanding synchronous or asynchronous operations are can- celled so their callback functions will not be called any longer. 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 If the fresh argument is then the registration is new (the SLP protocol 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 If the URL is in the the srvtype parameter is ignored. If the fresh argument is 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. will be returned if srvurl is not a SLP Service URL. If lifetime is set to 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. 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 it is in all locales. The API library is required to perform the operation in all scopes obtained through configuration. Issue a query for services. The 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 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 are returned with the prefix intact. 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 registra- tions 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 The functions are: The SLPRegReport callback type is used as the type for the callback function that is passed in to the and functions. This callback function does not return any value. The SLPSrvURLCallback type is the type of the callback function parameter to function. If the hslp handle parameter was opened asynchronously, the results returned through the callback MAY be uncollated. The callback should return if more data is desired. The callback may continue to return until it is called with an errcode of If no more data is requested the callback should return The SLPAttrCallback type is the type of callback function passed as a parameter to the function. The behavior of the library dif- fers depending on whether the attribute request was by Service URL or by service type. If the function was called with a Service URL, then the callback is called once regardless of whether the handle was opened asyn- chronously or synchronously. The attrlist parameter will contain a comma separated list of attributes. If the 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 was called synchronously. But when called asynchronously the attrlist may return duplicates. The callback should return if more data is desired. The callback may continue to return until it is called with an errcode of If no more data is requested the callback should return Miscellaneous routines The following are the routines for parsing the service URL. Parses a Service URL passed in as a null terminated character string and returns the results in a pointer to a dynamically allocated structure. The pointer returned in parsedurl should be freed by structure is defined in as follows: Processes the input string to escape any SLP reserved characters and returns the escaped string in dynamically allocated memory. If the istag parameter is then will look for bad tag characters. Process the input string to unescape any SLP reserved characters. The unescaped string is returned in dynamically allocated memory the pointer to which is returned in The memory should be freed by calling SLPFree() when no longer needed. If the istag parameter is then will look for bad tag characters. Frees memory that was returned from and The following routines may be used to determine the configuration of SLP on the local machine and on the network. 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 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 when no longer needed. 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. This function is supposed to allow the caller to set SLP properties, but it is impossible to implement this function along with in a way that is even remotely thread safe. Therefore, SLP implementation completely ignores all calls made to so that can be used in threaded applications. Note: 1. If is returned, then probably is not running. For flexibility, does not require 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 function is not implemented. Instead of calling developers writing SLP enabled code should use simply to de-register the entire service then call to re-register the service without the undesired attributes. RETURN VALUE
If successful, returns else it returns one of the codes. See SLPError(3N) for error return values. AUTHOR
SLP was developed by Caldera Systems, Inc. SEE ALSO
slpd(1M), SLPError(3N), slp.conf(4), slp.reg(4), slp_syntax(7). STANDARDS CONFORMANCE
RFC 2614, RFC2608 libslp(3N)
Man Page