rfc2614.txt

RFC 的详细文档！

      scope-list    =  scope-name / scope-name "," scope-list
      scope         =  ; See grammar of [7] for
                       ; scope-name syntax.
      attr-list     =  attr-def / attr-def attr-list
      attr-def      =  ( attr / keyword ) newline
      keyword       =  attr-id
      attr          =  attr-id "=" attr-val-list
      attr-id       =  ;Attribute id, see [7] for syntax.
      attr-val-list =  attr-val / attr-val "," attr-val-list
      attr-val      =  ;Attribute value, see [7] for syntax.
      allchar       =  char / WSP
      char          =  DIGIT / ALPHA / other
      other         =  %x21-%x2f / %x3a-%x40 /
                       %x5b-%x60 / %7b-%7e
                       ; All printable, nonwhitespace US-ASCII
                       ; characters.
      newline       =  CR / ( CRLF )


   The syntax for scope names, attribute tags, and attribute values
   requires escapes for special characters as specified in [7].  DAs and
   SA servers that process serialized registrations must handle them
   exactly as if they were registered by an SA. In the url-props



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


   production, the type token is optional.  If the type token is present
   for a service:  URL, a warning is signaled and the type name is
   ignored.  If the maximum lifetime is specified (65535 sec.), the
   registration is taken to be permanent, and is continually refreshed
   by the DA or SA server until it exits.  Scopes can be included in a
   registration by including an attribute definition with tag "scopes"
   followed by a comma separated list of scope names immediately after
   the url-props production.  If the optional scope list is present, the
   registrations are made in the indicated scopes; otherwise, they are
   registered in the scopes with which the DA or SA server was
   configured through the net.slp.useScopes property.

   If the scope list contains scopes that are not in the
   net.slp.useScopes property (provided that property is set) or are not
   specified by DHCP, the API library should reject the registration and
   issue a warning message.

2.4. Processing Serialized Registration and Configuration Files

   Implementations are encouraged to make processing of configuration
   and serialized files as transparent as possible to clients of the
   API. At the latest, errors must be caught when the relevant
   configuration item is used.  At the earliest, errors may be caught
   when the relevant file is loaded into the executing agent.  Errors
   should be reported by logging to the appropriate platform logging
   file, error output, or log device, and the default value substituted.
   Serialized registration file entries should be caught and reported
   when the file is loaded.

   Configuration file loading must be complete prior to the initiation
   of the first networking connection.  Serialized registration must be
   complete before the DA accepts the first network request.

3. Binding Independent Implementation Considerations

   This section discusses a number of implementation considerations
   independent of language binding, with language specific notes where
   applicable.

3.1. Multithreading

   Implementations of both the C and Java APIs are required to make API
   calls thread-safe.  Access to data structures shared between threads
   must be co-ordinated to avoid corruption or invalid access.  One way
   to achieve this goal is to allow only one thread at a time in the
   implementing library.  Performance in such an implementation suffers,
   however.  Therefore, where possible, implementations are encouraged
   to allow multiple threads within the SLP API library.



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


3.2. Asynchronous and Incremental

   The APIs are designed to encourage implementations supporting
   asynchronous and incremental client interaction.  The goal is to
   allow large numbers of returned service URLs, service types, and
   attributes without requiring the allocation of huge chunks of memory.
   The particular design features to support this goal differ in the two
   language bindings.

3.3. Type Checking for Service Types

   Service templates [8] allow SLP registrations to be type checked for
   correctness.  Implementations of the API are free to make use of
   service type information for type checking, but are not required to
   do so.  If a type error occurs, the registration should terminate
   with TYPE_ERROR.

3.4. Refreshing Registrations

   SLP advertisements carry an explicit lifetime with them.  After the
   lifetime expires, the DA flushes the registration from its cache.  In
   some cases, an application may want to have the URL continue being
   registered for the entire time during which the application is
   executing.  The API includes provision for clients to indicate
   whether they want URLs to be automatically refreshed.
   Implementations of the SA API must provide this automatic refreshing
   capability.  Note that a client which uses this facility should
   explicitly deregister the service URL before exiting, since the API
   implementation may not be able to assure that the URL is deregistered
   when the application exits, although it will time out in the DA
   eventually.

3.5. Configuration File Processing

   DAs, SAs and UAs processing the configuration file, and DAs and SA
   servers processing the serialized registration file are required to
   log any errors using whatever underlying error mechanism is
   appropriate for the platform.  Examples include writing error
   messages to the standard output, writing to a system logging device,
   or displaying the errors to a logging window.  After the error is
   reported, the offending property must be set to the default and
   program execution continued.  An agent MUST NOT fail if a file format
   error occurs.








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


3.6. Attribute Types

   String encoded attribute values do not include explicit type
   information.  All UA implementations and those SA and DA
   implementations that choose to support type checking should use the
   type rules described in [8] in order to convert from the string
   representation on the wire to an object typed appropriately.

3.7. Removal of Duplicates

   The UA implementation SHOULD always collate results to remove
   duplicates during synchronous operations and for the Java API. During
   asynchronous operation in C, the UA implementation SHOULD forgo
   duplicate elimination to reduce memory requirements in the library.
   This allows the API library to simply take the returned attribute
   value list strings, URL strings, or service type list strings and
   call the callback function with it, without any additional
   processing.  Naturally, the burden of duplicate elimination is thrown
   onto the client in this case.

3.8. Character Set Encoding

   Character string parameters in the Java API are all represented in
   Unicode internally because that is the Java-supported character set.
   Characters buffer parameters in the C API are represented in UTF-8 to
   maintain maximum compatibility on platforms that only support US-
   ASCII and not UTF-8.  API functions are still required to handle the
   full range of UTF-8 characters because the SLP protocol requires it,
   but the API implementation can represent the characters internally in
   any convenient way.  On the wire, all characters are converted to
   UTF-8.  Inside URLs, characters that are not allowed by URL syntax
   [2] must be escaped according to the URL escape character convention.
   Strings that are included in SLP messages may include SLP reserved
   characters and can be escaped by clients through convenience
   functions provided by the API. The character encoding used in escapes
   is UTF-8.

   Due to constraints in SLP, no string parameter passed to the C or
   Java API may exceed 64K bytes in length.

3.9. Error Semantics

   All errors encountered processing SLP messages should be logged.  For
   synchronous calls, an error is only reported on a call if no
   successful replies were received from any SLP framework entity.  If
   an error occurred among one of several successful replies, then the
   error should be logged and the successful replies returned.  For
   asynchronous calls, an error occurring during correspondence with a



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


   particular remote SLP agent is reported through the first callback
   (in the C API) or enumeration method invocation (in the Java API)
   after the error occurs, which would normally report the results of
   the correspondence.  This allows the callback or client code to
   determine whether the operation should be terminated or continue.  In
   some cases, the error returned from the SLP framework may be fatal
   (SLP_PARSE_ERROR, etc.).  In these cases, the API library terminates
   the operation.

   Both the Java and C APIs contain language specific error code
   mechanisms for returning error information.  The names of the error
   codes are consistent between the two implementations, however.

   The following error codes are returned from a remote agent (DA or SA
   server):

      LANGUAGE_NOT_SUPPORTED

         No DA or SA has service advertisement or attribute information
         in the language requested, but at least one DA or SA indicated,
         via the LANGUAGE_NOT_SUPPORTED error code, that it might have
         information for that service in another language.

      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 the API may be malformed or a may have been
         damaged in transit.

      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 least one DA
         accepted the registration.

      AUTHENTICATION_ABSENT

         If the SLP framework supports authentication, this error arises
         when the UA or SA failed to send an authenticator for requests
         or registrations in a protected scope.








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


      INVALID_UPDATE

         An update for a non-existing registration was issued, or the
         update includes a service type or scope different than that in
         the initial registration, etc.

   The following errors result from interactions with remote agents or
   can occur locally:

      AUTHENTICATION_FAILED

         If the SLP framework supports authentication, this error arises
         when a authentication on an SLP message failed.

      SCOPE_NOT_SUPPORTED

         The API returns this error if the SA has been configured with
         net.slp.useScopes value-list of scopes and the SA request did
         not specify one or more of these allowable scopes, and no
         others.  It may be returned by a DA or SA if the scope included
         in a request is not supported by the DA or SA.

      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.

   The following errors are generated through a program interacting with
   the API implementation.  They do not involve a remote SLP agent.

      NOT_IMPLEMENTED

         If an unimplemented feature is used, this error is returned.

      NETWORK_INIT_FAILED

         If the network cannot initialize properly, this error is
         returned.

      NETWORK_TIMED_OUT

         When no reply can be obtained in the time specified by the
         configured timeout interval for a unicast request, this error
         is returned.





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