tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 2614

 
 
 

An API for Service Location

Part 2 of 3, p. 25 to 55
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 25 
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.

Top      Up      ToC       Page 26 
   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,

Top      Up      ToC       Page 27 
     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;

Top      Up      ToC       Page 28 
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.

Top      Up      ToC       Page 29 
      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

Top      Up      ToC       Page 30 
   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);

Top      Up      ToC       Page 31 
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);

Top      Up      ToC       Page 32 
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.

Top      Up      ToC       Page 33 
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].

Top      Up      ToC       Page 34 
      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

Top      Up      ToC       Page 35 
   SLP_TRUE (resp.  SLP_FALSE).

4.4.1.3. Parameters

      pcLang

         A pointer to an array of characters containing the RFC 1766
         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().

Top      Up      ToC       Page 36 
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.

Top      Up      ToC       Page 37 
      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);

Top      Up      ToC       Page 38 
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);

Top      Up      ToC       Page 39 
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);

Top      Up      ToC       Page 40 
   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.

Top      Up      ToC       Page 41 
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

Top      Up      ToC       Page 42 
         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.

Top      Up      ToC       Page 43 
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();

Top      Up      ToC       Page 44 
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().

Top      Up      ToC       Page 45 
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.

Top      Up      ToC       Page 46 
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.

Top      Up      ToC       Page 47 
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.

Top      Up      ToC       Page 48 
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.

Top      Up      ToC       Page 49 
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

Top      Up      ToC       Page 50 
   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.

Top      Up      ToC       Page 51 
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:

Top      Up      ToC       Page 52 
      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 */

Top      Up      ToC       Page 53 
   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;

Top      Up      ToC       Page 54 
   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! */

Top      Up      ToC       Page 55 
   }

   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! */

   }


Next RFC Part