rfc2614.txt

RFC 的详细文档！

      NETWORK_ERROR

         The failure of networking during normal operations causes this
         error to be returned.

      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.

      MEMORY_ALLOC_FAILED

         If the API fails to allocate memory, the operation is aborted
         and returns this.

      PARAMETER_BAD

         If a parameter passed into an interface is bad, this error is
         returned.

      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.

      HANDLE_IN_USE

         In the C API, callback functions 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.

      TYPE_ERROR

         If the API supports type checking of registrations against
         service type templates, this error can arise if the attributes
         in a registration do not match the service type template for
         the service.

   Some error codes are handled differently in the Java API. These
   differences are discussed in Section 5.

   The SLP protocol errors OPTION_NOT_UNDERSTOOD, VERSION_NOT_SUPPORTED,
   INTERNAL_ERROR, MSG_NOT_SUPPORTED, AUTHENTICATON_UNKNOWN, and
   DA_BUSY_NOW should be handled internally and not surfaced to clients
   through the API.



Kempf & Guttman              Informational                     [Page 23]

RFC 2614                  Service Location API                 June 1999


3.10. Modular Implementations

   Subset implementations that do not support the full range of
   functionality are required to nevertheless support every interface in
   order to maintain link compatibility between compliant API
   implementations and applications.  If a particular operation is not
   supported, a NOT_IMPLEMENTED error should be returned.  The Java API
   has some additional conventions for handling subsets.  Applications
   that are expected to run on a wide variety of platforms should be
   prepared for subset API implementations by checking returned error
   codes.

3.11. Handling Special Service Types

   The service types service:directory-agent and service:service-agent
   are used internally in the SLP framework to discover DAs and SAs.
   The mechanism of DA and SA discovery is not normally exposed to the
   API client; however, the client may have interest in discovering DAs
   and SAs independently of their role in discovering other services.
   For example, a network management application may want to determine
   which machines are running SLP DAs.  To facilitate that, API
   implementations must handle requests to find services and attributes
   for these two service types so that API clients obtain the
   information they expect.

   In particular, if the UA is using a DA, SrvRqst and AttrRqst for
   these service types must be multicast and not unicast to the DA, as
   is the case for other service types.  If the requests are not
   multicast, the DA will respond with an empty reply to a request for
   services of type service:service-agent and with its URL only to a
   request for services of type service:directory-agent.  The UA would
   therefore not obtain a complete picture of the available DAs and SAs.

3.12. Scope Discovery and Handling

   Both APIs contain an operation to obtain a list of currently known
   scope names.  This scope information comes from a variety of places:
   DHCP, the net.slp.useScopes property, unicast to DAs configured via
   DHCP or the net.slp.DAAddresses property, and active and passive
   discovery.

   The API is required to be implemented in a way that re-enforces the
   administrative and user scoping models described in [7].  SA clients
   only support the administrative scoping model.  SAs must know a
   priori what DAs they need to register with since there is typically
   no human intervention in scope selection for SAs.  UAs must support
   both administrative and user scoping because an application may
   require human intervention in scope selection.



Kempf & Guttman              Informational                     [Page 24]

RFC 2614                  Service Location API                 June 1999


   API implementations are required to support administrative scoping in
   the following way.  Scopes configured by DHCP and scopes of DAs
   configured by DHCP have first priority (in that order) and must be
   returned if they are available.  The net.slp.useScopes property has
   second priority, and scopes discovered through the net.slp.useScopes
   property must be returned if this property is set and there are no
   scopes available from DHCP. If scopes are not available from either
   of these sources and the net.slp.DAAddresses property is set, then
   the scopes available from the configured DAs must be returned.  Note
   that if both DAs and scopes are configured, the scopes of the
   configured DAs must match the configured scope list; otherwise and
   error is signaled and agent execution is terminated.  If no
   configured scope information is available, then an SA client has
   default scope, "DEFAULT", and a UA client employs user scoping.

   User scoping is supported in the following way.  Scopes discovered
   from active DA discovery, and from passive DA discovery all must be
   returned.  If no information is available from active and passive DA
   discovery, then the API library may perform SA discovery, using the
   service types in the net.slp.typeHint property to limit the search to
   SAs supporting particular service types.  If no net.slp.typeHint
   property is set, the UA may perform SA discovery without any service
   type query.  In the absence of any of the above sources of
   information, the API must return the default scope, "DEFAULT".  Note
   that the API must always return some scope information.

   SLP requires that SAs must perform their operations in all scopes
   currently known to them. [7].  The API enforces this constraint by
   not requiring the API client to supply any scopes as parameters to
   API operations.  The API library must obtain all currently known
   scopes and use them in SA operations.  UA API clients should use a
   scope obtained through one of the API operations for finding scopes.
   Any other scope name may result in a SCOPE_NOT_SUPPORTED error from a
   remote agent.  The UA API library can optionally check the scope and
   return the error without contacting a remote agent.

4. C Language Binding

   The C language binding presents a minimal overhead implementation
   that maps directly into the protocol.  There is one C language
   function per protocol request, with the exception of the SLPDereg()
   and SLPDelAttrs() functions, which map into different uses of the SLP
   deregister request.  Parameters are for the most part character
   buffers.  Memory management is kept simple by having the client
   allocate most memory and requiring that client callback functions
   copy incoming parameters into memory allocated by the client code.
   Any memory returned directly from the API functions is deallocated
   using the SLPFree() function.



Kempf & Guttman              Informational                     [Page 25]

RFC 2614                  Service Location API                 June 1999


   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,



Kempf & Guttman              Informational                     [Page 26]

RFC 2614                  Service Location API                 June 1999


     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;






Kempf & Guttman              Informational                     [Page 27]

RFC 2614                  Service Location API                 June 1999


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() functio