tech-invite   World Map     

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

RFC 2614

Informational
Pages: 91
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: SVRLOC

An API for Service Location

Part 1 of 3, p. 1 to 25
None       Next RFC Part

 


Top       ToC       Page 1 
Network Working Group                                          J. Kempf
Request for Comments: 2614                                   E. Guttman
Category: Informational                                Sun Microsystems
                                                              June 1999


                      An API for Service Location

Status of This Memo

   This memo provides information for the Internet community.  It does
   not specify an Internet standard of any kind.  Distribution of this
   memo is unlimited.

Abstract

   The Service Location Protocol (SLP) provides a new way for clients to
   dynamically discovery network services.  With SLP, it is simple to
   offer highly available services that require no user configuration or
   assistance from network administrators prior to use.  This document
   describes standardized APIs for SLP in C and Java.  The APIs are
   modular and are designed to allow implementations to offer just the
   feature set needed.  In addition, standardized file formats for
   configuration and serialized registrations are defined, allowing SLP
   agents to set network and other parameters in a portable way.  The
   serialized file format allows legacy services to be registered with
   SLP directory agents in cases where modifying the legacy service
   program code is difficult or impossible, and to portably exchange a
   registration database.

Table of Contents

    1. Introduction                                                    4
        1.1. Goals  . . . . . . . . . . . . . . . . . . . . . . . .    4
        1.2. Terminology  . . . . . . . . . . . . . . . . . . . . .    4
    2. File Formats                                                    7
        2.1. Configuration File Format  . . . . . . . . . . . . . .    8
              2.1.1. DA configuration   . . . . . . . . . . . . . .    9
              2.1.2. Static Scope Configuration . . . . . . . . . .    9
              2.1.3. Tracing and Logging  . . . . . . . . . . . . .   11
              2.1.4. Serialized Proxy Registrations . . . . . . . .   11
              2.1.5. Network Configuration Properties . . . . . . .   12
              2.1.6. SA Configuration . . . . . . . . . . . . . . .   14
              2.1.7. UA Configuration . . . . . . . . . . . . . . .   14
              2.1.8. Security   . . . . . . . . . . . . . . . . . .   15
        2.2. Multihomed Machines. . . . . . . . . . . . . . . . . .   16
        2.3. Serialized Registration File . . . . . . . . . . . . .   16

Top      ToC       Page 2 
        2.4. Processing Serialized Registration and Configuration
             Files  . . . . . . . . . . . . . . . . . . . . . . . .   18
    3. Binding Independent Implementation Considerations              18
        3.1. Multithreading . . . . . . . . . . . . . . . . . . . .   18
        3.2. Asynchronous and Incremental . . . . . . . . . . . . .   19
        3.3. Type Checking for Service Types. . . . . . . . . . . .   19
        3.4. Refreshing Registrations . . . . . . . . . . . . . . .   19
        3.5. Configuration File Processing  . . . . . . . . . . . .   19
        3.6. Attribute Types  . . . . . . . . . . . . . . . . . . .   20
        3.7. Removal of Duplicates  . . . . . . . . . . . . . . . .   20
        3.8. Character Set Encoding . . . . . . . . . . . . . . . .   20
        3.9. Error Semantics  . . . . . . . . . . . . . . . . . . .   20
       3.10. Modular Implementations  . . . . . . . . . . . . . . .   24
       3.11. Handling Special Service Types . . . . . . . . . . . .   24
       3.12. Scope Discovery and Handling . . . . . . . . . . . . .   24
    4. C Language Binding                                             25
        4.1. Constant Types . . . . . . . . . . . . . . . . . . . .   26
              4.1.1. URL Lifetimes. . . . . . . . . . . . . . . . .   26
              4.1.2. Error Codes. . . . . . . . . . . . . . . . . .   26
              4.1.3. SLPBoolean . . . . . . . . . . . . . . . . . .   27
        4.2. Struct Types   . . . . . . . . . . . . . . . . . . . .   28
              4.2.1. SLPSrvURL  . . . . . . . . . . . . . . . . . .   28
              4.2.2. SLPHandle  . . . . . . . . . . . . . . . . . .   29
        4.3. Callbacks  . . . . . . . . . . . . . . . . . . . . . .   29
              4.3.1. SLPRegReport   . . . . . . . . . . . . . . . .   30
              4.3.2. SLPSrvTypeCallback . . . . . . . . . . . . . .   30
              4.3.3. SLPSrvURLCallback  . . . . . . . . . . . . . .   31
              4.3.4. SLPAttrCallback  . . . . . . . . . . . . . . .   33
        4.4. Opening and Closing an SLPHandle . . . . . . . . . . .   34
              4.4.1. SLPOpen. . . . . . . . . . . . . . . . . . . .   34
              4.4.2. SLPClose . . . . . . . . . . . . . . . . . . .   35
        4.5. Protocol API   . . . . . . . . . . . . . . . . . . . .   36
              4.5.1. SLPReg . . . . . . . . . . . . . . . . . . . .   36
              4.5.2. SLPDereg . . . . . . . . . . . . . . . . . . .   37
              4.5.3. SLPDelAttrs  . . . . . . . . . . . . . . . . .   38
              4.5.4. SLPFindSrvTypes. . . . . . . . . . . . . . . .   39
              4.5.5. SLPFindSrvs  . . . . . . . . . . . . . . . . .   41
              4.5.6. SLPFindAttrs . . . . . . . . . . . . . . . . .   42
        4.6. Miscellaneous Functions  . . . . . . . . . . . . . . .   43
              4.6.1. SLPGetRefreshInterval  . . . . . . . . . . . .   44
              4.6.2. SLPFindScopes  . . . . . . . . . . . . . . . .   44
              4.6.3. SLPParseSrvURL . . . . . . . . . . . . . . . .   45
              4.6.4. SLPEscape  . . . . . . . . . . . . . . . . . .   46
              4.6.5. SLPUnescape  . . . . . . . . . . . . . . . . .   47
              4.6.6. SLPFree  . . . . . . . . . . . . . . . . . . .   48
              4.6.7. SLPGetProperty . . . . . . . . . . . . . . . .   48
              4.6.8. SLPSetProperty . . . . . . . . . . . . . . . .   49
        4.7. Implementation Notes   . . . . . . . . . . . . . . . .   49

Top      ToC       Page 3 
              4.7.1. Refreshing Registrations . . . . . . . . . . .   49
              4.7.2. Syntax for String Parameters . . . . . . . . .   49
              4.7.3. Client Side Syntax Checking  . . . . . . . . .   50
              4.7.4. System Properties  . . . . . . . . . . . . . .   50
              4.7.5. Memory Management  . . . . . . . . . . . . . .   51
              4.7.6. Asynchronous and Incremental Return Semantics.   51
        4.8. Example. . . . . . . . . . . . . . . . . . . . . . . .   52
    5. Java Language Binding                                          56
        5.1. Introduction . . . . . . . . . . . . . . . . . . . . .   56
        5.2. Exceptions and Errors  . . . . . . . . . . . . . . . .   56
              5.2.1. Class ServiceLocationException . . . . . . . .   57
        5.3. Basic Data Structures  . . . . . . . . . . . . . . . .   58
              5.3.1. Interface ServiceLocationEnumeration . . . . .   58
              5.3.2. Class ServiceLocationAttribute   . . . . . . .   58
              5.3.3. Class ServiceType  . . . . . . . . . . . . . .   61
              5.3.4. Class ServiceURL   . . . . . . . . . . . . . .   63
        5.4. SLP Access Interfaces  . . . . . . . . . . . . . . . .   67
              5.4.1. Interface Advertiser . . . . . . . . . . . . .   67
              5.4.2. Interface Locator  . . . . . . . . . . . . . .   69
        5.5. The Service Location Manager . . . . . . . . . . . . .   72
              5.5.1. Class ServiceLocationManager . . . . . . . . .   72
        5.6. Service Template Introspection . . . . . . . . . . . .   74
              5.6.1. Abstract Class TemplateRegistry  . . . . . . .   74
              5.6.2. Interface ServiceLocationAttributeVerifier . .   77
              5.6.3. Interface ServiceLocationAttributeDescriptor .   79
        5.7. Implementation Notes . . . . . . . . . . . . . . . . .   81
              5.7.1. Refreshing Registrations . . . . . . . . . . .   81
              5.7.2. Parsing Alternate Transports in ServiceURL . .   81
              5.7.3. String Attribute Values  . . . . . . . . . . .   82
              5.7.4. Client Side Syntax Checking. . . . . . . . . .   82
              5.7.5. Language Locale Handling . . . . . . . . . . .   82
              5.7.6. Setting SLP System Properties. . . . . . . . .   83
              5.7.7. Multithreading . . . . . . . . . . . . . . . .   83
              5.7.8. Modular Implementations  . . . . . . . . . . .   83
              5.7.9. Asynchronous and Incremental Return Semantics.   84
        5.8. Example. . . . . . . . . . . . . . . . . . . . . . . .   85
    6. Internationalization Considerations                            87
        6.1. service URL. . . . . . . . . . . . . . . . . . . . . .   87
        6.2. Character Set Encoding . . . . . . . . . . . . . . . .   87
        6.3. Language Tagging   . . . . . . . . . . . . . . . . . .   88
    7. Security Considerations                                        88
    8. Acknowledgements                                               88
    9. References                                                     89
   10. Authors' Addresses                                             90
   11. Full Copyright Statement                                       91

Top      ToC       Page 4 
1. Introduction

   The Service Location API is designed for standardized access to the
   Service Location Protocol (SLP). The APIs allow client and service
   programs to be be written or modified in a very simple manner to
   provide dynamic service discovery and selection.  Bindings in the C
   and Java languages are defined in this document.  In addition,
   standardized formats for configuration files and for serialized
   registration files are presented.  These files allow SLP agents to
   configure network parameters, to register legacy services that have
   not been SLP enabled, and to portably exchange registration
   databases.

1.1. Goals

   The overall goal of the API is to enable source portability of
   applications that use the API between different implementations of
   SLP. The result should facilitate the adoption of SLP, and conversion
   of clients and service programs to SLP.

   The goals of the C binding are to create a minimal but complete
   access to the functionality of the SLP protocol, allowing for simple
   memory management and limited code size.

   The Java API provides for modular implementations (where unneeded
   features can be omitted) and an object oriented interface to the
   complete set of SLP data and functionality.

   The standardized configuration file and serialized file formats
   provide a simple syntax with complete functional coverage of the
   protocol, but without system dependent properties and secure
   information.

1.2. Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119  [1].

      Service Location Protocol (SLP)

         The underlying protocol allowing dynamic and scalable service
         discovery.  This protocol is specified in the Service Location
         Protocol Version 2 [7].

Top      ToC       Page 5 
      SLP framework

         When a 'Service Location framework' is mentioned, it refers to
         both the SLP implementation and interface implementation; i.e.
         whatever provides the SLP functionality to user level programs.
         This includes remote agents.

      Directory Agent (DA)

         A service that automatically gathers service advertisements
         from SAs in order to provide them to UAs.

      User Agent (UA)

         This is the Service Location process or library that allows SLP
         requests to be made on behalf of a client process.  UAs
         automatically direct requests to DAs when they exist.  In their
         absence, UAs make requests to SAs.

      Service Agent (SA)

         This is the Service Location process or library that allows
         service software to register and deregister itself with the SLP
         framework.  SAs respond to UA service requests, detect DAs and
         register service advertisements with them.

      SA Server

         Many operating system platforms only allow a single process to
         listen on a particular port number.  Since SAs are required to
         listen on a multicast address for SLP service requests,
         implementations of the SLP framework on such platforms that
         want to support multiple SAs on one machine need to arrange for
         a single process to do the listening while the advertising SAs
         communicate with that process through another mechanism.  The
         single listening process is called an SA server.  SA servers
         share many characteristics with DAs, but they are not the same.

      Service Advertisement

         A URL possibly combined with service attributes.  These are
         made available to UAs by SAs, either directly or via a DA.

      Locale

         The language localization that applies to strings passed into
         or returned from the SLP API. The Locale is expressed using a
         Language Tag [6].  All attribute strings are associated with a

Top      ToC       Page 6 
         particular locale.  The locale is completely orthogonal to the
         ANSI C locale.  The SLP locale is mapped into the Java locale
         in the Java API.

      Service Template

         A document that describes the syntax of the URL for a given
         service type and a definition of all service attributes
         including the meaning, defaults, and constraints on values the
         attributes may take.  See [8] for more information on service
         templates.

      The service:  URL

         A service of a particular type announces its availability with
         a service:  URL that includes its service access point (domain
         name or IP address, and possibly its port number) and
         optionally basic configuration parameters.  The syntax of the
         service:  URL is defined in the service template.  Other URL's
         can be used in service advertisements if desired.

      Service Attributes

         The attributes associated with a given service.  The values
         that can be assigned to service attributes are defined by the
         service template.

      Scope

         A string used to control the availability of service
         advertisements.  Every SLP Agent is configured with one or more
         scope strings.  Scopes are assigned by site administrators to
         group services for many purposes, but chiefly as a means of
         scalability.  DAs store only services advertised having a scope
         string matching the scopes with which they are configured.

      Naming Authority (NA)

         This is a 'suffix' to the service type string.  It completely
         changes the meaning of the service type.  NAs are used for
         private definitions of well known Service Types and
         experimental Service Type extensions.  The default NA is
         "IANA", which must not be explicitly included.  Service types
         with the IANA naming authority are registered with the Internet
         Assigned Numbers Authority (see [8] for more information on the
         registration procedure).

Top      ToC       Page 7 
2. File Formats

   This section describes the configuration and serialized registration
   file formats.  Both files are defined in the UTF-8 character set [3].

   Attribute tags and values in the serialized registration file require
   SLP reserved characters to be escaped.  The SLP reserved characters
   are `(', `)', `,', `\', `!', `<', `=', `>', `~' and control
   characters (characters with UTF codes less than 0x0020 and the
   character 0x007f, which is US-ASCII DEL). The escapes are formed
   exactly as for the wire protocol, i.e.  a backslash followed by two
   hex digits representing the character.  For example, the escape for '
   ,' is '\2c'.  In addition, the characters `\n', `\r', `\t', and `_'
   are prohibited from attribute tags by the SLP wire syntax grammar.
   [7]

   In serialized registration files, escaped strings beginning with
   `\ff`, an encoding for a nonUTF-8 character, are treated as opaques.
   Exactly as in the wire protocol, syntactically correct opaque
   encodings consist of a string beginning with `\ff` and containing
   *only* escaped characters that are transformed to bytes.  Such
   strings are only syntactically correct in the serialized registration
   file as attribute values.  In other cases, whenever an escape is
   encountered and the character is not an SLP reserved character, an
   error is signaled.

   Escaped characters in URLs in serialized registration files use the
   URL escape convention. [2].

   Property names and values in the configuration file have a few
   reserved characters that are involved in file's lexical definition.
   The characters '.'  and '=' are reserved in property names and must
   be escape.  The characters ',', '(', and ')' are reserved in property
   values and must be escaped.  In addition, scope names in the
   net.slp.useScopes property use the SLP wire format escape convention
   for SLP reserved characters.  This simplifies implementation, since
   the same code can be used to unescape scope names as is used in
   processing the serialized registration file or for formatting wire
   messages.

   On platforms that only support US-ASCII and not UTF-8, the upper bit
   of bytes incoming from the configuration and registration files
   determines whether the character is US-ASCII or not US-ASCII.
   According to the standard UTF-8 encoding, the upper bit is zero if
   the character is US-ASCII and one if the character is multibyte and
   thus not US-ASCII. Platforms without intrinsic UTF-8 support are
   required to parse the multibyte character and store it in an
   appropriate internal format.  Support for UTF-8 is required to

Top      ToC       Page 8 
   implement the SLP protocol (see [7]), and can therefore be used in
   file processing as well.

   The location and name of the configuration file is system-dependent,
   but implementations of the API are encouraged to locate it together
   with other configuration files and name it consistently.

2.1. Configuration File Format

   The configuration file format consists of a newline delimited list of
   zero or more property definitions.  Each property definition
   corresponds to a particular configurable SLP, network, or other
   parameter in one or more of the three SLP agents.  The file format
   grammar in ABNF [5] syntax is:

      config-file   =  line-list
      line-list     =  line / line line-list
      line          =  property-line / comment-line
      comment-line  =  ( "#" / ";" ) 1*allchar newline
      property-line =  property newline
      property      =  tag "=" value-list
      tag           =  prop / prop "." tag
      prop          =  1*tagchar
      value-list    =  value / value "," value-list
      value         =  int / bool /
                       "(" value-list ")" / string
      int           =  1*DIGIT
      bool          =  "true" / "false" / "TRUE" / "FALSE"
      newline       =  CR / ( CRLF )
      string        =  1*stringchar
      tagchar       =  DIGIT / ALPHA / tother / escape
      tother        =  %x21-%x2d / %x2f /
                       %x3a / %x3c-%x40 /
                       %x5b-%x60 / %7b-%7e
                       ; i.e., all characters except `.',
                       ; and `='.
      stringchar    =  DIGIT / ALPHA / sother / escape
      sother        =  %x21-%x29 / %x2a-%x2b /
                       %x2d-%x2f / %x3a-%x40 /
                       %x5b-%x60 / %7b-%7e
                       ; i.e., all characters except `,'
      allchar       =  DIGIT / ALPHA / HTAB / SP
      escape        =  "\" HEXDIG HEXDIG
                       ; Used for reserved characters

   With the exception of net.slp.useScopes, net.slp.DAAddresses, and
   net.slp.isBroadcastOnly, all other properties can be changed through
   property accessors in the C and Java APIs.  The property accessors

Top      ToC       Page 9 
   only change the property values in the running agent program and do
   not affect the values in the configuration file.  The
   net.slp.useScopes and net.slp.DAAddresses properties are read-only
   because they control the agent's view of the scopes and DAs and are
   therefore critical to the function of the API scope discovery
   algorithm.  Attempts to modify them are unlikely to yield productive
   results, and could harm the ability of the agent to find scopes and
   use DAs.  The net.slp.isBroadcastOnly property is read-only because
   the API library needs to configure networking upon start up and
   changing this property might invalidate the configuration.  Whether
   the local network uses broadcast or multicast is not likely to change
   during the course of the program's execution.

   The properties break down into the following subsections describes an
   area and its properties.

2.1.1. DA configuration

   Important configuration properties for DAs are included in this
   section.  These are:

      net.slp.isDA

         A boolean indicating if the SLP server is to act as a DA. If
         false, not run as a DA. Default is false.

      net.slp.DAHeartBeat

         A 32 bit integer giving the number of seconds for the
         DA heartbeat.  Default is 3 hours (10800 seconds).  This
         property corresponds to the protocol specification parameter
         CONFIG_DA_BEAT [7].  Ignored if isDA is false.

      net.slp.DAAttributes

         A comma-separated list of parenthesized attribute/value list
         pairs that the DA must advertise in DAAdverts.  The property
         must be in the SLP attribute list wire format, including
         escapes for reserved characters. [7]

2.1.2. Static Scope Configuration

   These properties allow various aspects of scope handling to be
   configured.

Top      ToC       Page 10 
      net.slp.useScopes

         A value-list of strings indicating the only scopes a UA or SA
         is allowed to use when making requests or registering, or the
         scopes a DA must support.  If not present for the DA and SA,
         then in the absence of scope information from DHCP, the default
         scope "DEFAULT" is used.  If not present for the UA, and there
         is no scope information available from DHCP, then the user
         scoping model is in force.  Active and passive DA discovery
         or SA discovery are used for scope discovery, and the scope
         "DEFAULT" is used if no other information is available.  If a
         DA or SA gets another scope in a request, a SCOPE_NOT_SUPPORTED
         error should be returned, unless the request was multicast, in
         which case it should be dropped.  If a DA gets another scope in
         a registration, a SCOPE_NOT_SUPPORTED error must be returned.
         Unlike other properties, this property is "read-only", so
         attempts to change it after the configuration file has been
         read are ignored.  See Section 3.12 for the algorithm the API
         uses in determining what scope information to present.

      net.slp.DAAddresses

         A value-list of IP addresses or DNS resolvable host names
         giving the SLPv2 DAs to use for statically configured UAs and
         SAs.  Ignored by DAs (unless the DA is also an SA server).
         Default is none.  Unlike other properties, this property is
         "read-only", so attempts to change it after the configuration
         file has been read are ignored.

         The following grammar describes the property:


               addr-list     =  addr / addr "," addr-list
               addr          =  fqdn / hostnumber
               fqdn          =  ALPHA / ALPHA *[ anum / "-" ] anum
               anum          =  ALPHA / DIGIT
               hostnumber    =  1*3DIGIT 3("." 1*3DIGIT)


         An example is:


                sawah,mandi,sambal


         IP addresses can be used instead of host names in networks
         where DNS is not deployed, but network administrators are
         reminded that using IP addresses will complicate machine

Top      ToC       Page 11 
         renumbering, since the SLP configuration property files
         in statically configured networks will have to be changed.
         Similarly, if host names are used, implementors must be careful
         that a name service is available before SLP starts, in other
         words, SLP cannot be used to find the name service.

2.1.3. Tracing and Logging

   This section allows tracing and logging information to be printed by
   the various agents.

      net.slp.traceDATraffic

         A boolean controlling printing of messages about traffic with
         DAs.  Default is false.

      net.slp.traceMsg

         A boolean controlling printing of details on SLP messages.
         The fields in all incoming messages and outgoing replies are
         printed.  Default is false.

      net.slp.traceDrop

         A boolean controlling printing details when a SLP message is
         dropped for any reason.  Default is false.

      net.slp.traceReg

         A boolean controlling dumps of all registered services upon
         registration and deregistration.  If true, the contents
         of the DA or SA server are dumped after a registration or
         deregistration occurs.  Default is false.

2.1.4. Serialized Proxy Registrations

   These properties control the reading and writing of serialized
   registrations.

      net.slp.serializedRegURL

         A string containing a URL pointing to a document containing
         serialized registrations that should be processed when the DA
         or SA server starts up.  Default is none.

Top      ToC       Page 12 
2.1.5. Network Configuration Properties

   The properties in this section allow various network configuration
   properties to be set.

      net.slp.isBroadcastOnly

         A boolean indicating if broadcast should be used instead of
         multicast.  Like the net.slp.useScopes and net.slp.DAAddresses
         properties, this property is "read-only", so attempts to change
         it after the configuration file has been read are ignored.
         Default is false.

      net.slp.passiveDADetection

         A boolean indicating whether passive DA detection should be
         used.  Default is true.

      net.slp.multicastTTL

         A positive integer less than or equal to 255, giving the
         multicast TTL. Default is 255.

      net.slp.DAActiveDiscoveryInterval

         A 16 bit positive integer giving the number of seconds
         between DA active discovery queries.  Default is 900 seconds
         (15 minutes).  This property corresponds to the protocol
         specification parameter CONFIG_DA_FIND [7].  If the property is
         set to zero, active discovery is turned off.  This is useful
         when the DAs available are explicitly restricted to those
         obtained from DHCP or the net.slp.DAAddresses property.

      net.slp.multicastMaximumWait

         A 32 bit integer giving the maximum amount of time to perform
         multicast, in milliseconds.  Default is 15000 ms (15 sec.).
         This property corresponds to the CONFIG_MC_MAX parameter in the
         protocol specification [7].

      net.slp.multicastTimeouts

         A value-list of 32 bit integers used as timeouts, in
         milliseconds, to implement the multicast convergence
         algorithm.  Each value specifies the time to wait before
         sending the next request, or until nothing new has
         been learned from two successive requests.  Default
         is:  3000,3000,3000,3000,3000.  In a fast network the

Top      ToC       Page 13 
         aggressive values of 1000,1250,1500,2000,4000 allow better
         performance.  This property corresponds to the CONFIG_MC_RETRY
         parameter in the protocol specification [7].  Note that the
         net.slp.DADiscoveryTimeouts property must be used for active DA
         discovery.

      net.slp.DADiscoveryTimeouts

         A value-list of 32 bit integers used as timeouts, in
         milliseconds, to implement the multicast convergence algorithm
         during active DA discovery.  Each value specifies the time
         to wait before sending the next request, or until nothing
         new has been learned from two successive requests.  This
         property corresponds to the protocol specification parameter
         CONFIG_RETRY [7].  Default is:  2000,2000,2000,2000,3000,4000.

      net.slp.datagramTimeouts

         A value-list of 32 bit integers used as timeouts, in
         milliseconds, to implement unicast datagram transmission to
         DAs.  The nth value gives the time to block waiting for a reply
         on the nth try to contact the DA. The sum of these values is
         the protocol specification property CONFIG_RETRY_MAX [7].

      net.slp.randomWaitBound

         A 32 bit integer giving the maximum value for all random
         wait parameters, in milliseconds.  Default is 1000 (1
         sec.).  This value corresponds to the protocol specification
         parameters CONFIG_START_WAIT, CONFIG_REG_PASSIVE, and
         CONFIG_REG_ACTIVE [7].

      net.slp.MTU

         A 16 bit integer giving the network packet MTU, in bytes.
         This is the maximum size of any datagram to send, but the
         implementation might receive a larger datagram.  The maximum
         size includes IP, and UDP or TCP headers.  Default is 1400.

      net.slp.interfaces

         Value-list of strings giving the IP addresses of network
         interfaces on which the DA or SA should listen on port 427 for
         multicast, unicast UDP, and TCP messages.  Default is empty,
         i.e.  use the default network interface.  The grammar for this
         property is:

Top      ToC       Page 14 
               addr-list     =  hostnumber / hostnumber "," addr-list
               hostnumber    =  1*3DIGIT 3("." 1*3DIGIT)


         An example is:


                  195.42.42.42,195.42.142.1,195.42.120.1


         The example machine has three interfaces on which the DA should
         listen.

         Note that since this property only takes IP addresses, it will
         need to be changed if the network is renumbered.

2.1.6. SA Configuration

   This section contains configuration properties for the SA. These
   properties are typically set programmatically by the SA, since they
   are specific to each SA.

      net.slp.SAAttributes

         A comma-separated list of parenthesized attribute/value list
         pairs that the SA must advertise in SAAdverts.  The property
         must be in the SLP attribute list wire format, including
         escapes for reserved characters. [7]

2.1.7. UA Configuration

   This section contains configuration properties for the UA. These
   properties can be set either programmatically by the UA or in the
   configuration file.

      net.slp.locale

         A RFC 1766 Language Tag [6] for the language locale.  Setting
         this property causes the property value to become the default
         locale for SLP messages.  Default is "en".  This property is
         also used for SA and DA configuration.

      net.slp.maxResults

         A 32 bit integer giving the maximum number of results to
         accumulate and return for a synchronous request before the
         timeout, or the maximum number of results to return through a
         callback if the request results are reported asynchronously.

Top      ToC       Page 15 
         Positive integers and -1 are legal values.  If -1, indicates
         that all results should be returned.  Default value is -1.

         DAs and SAs always return all results that match the
         request.  This configuration value applies only to UAs, that
         filter incoming results and only return as many values as
         net.slp.maxResults indicates.

      net.slp.typeHint

         A value-list of service type names.  In the absence of any
         DAs, UAs perform SA discovery for finding scopes.  These SA
         discovery requests may contain a request for service types as
         an attribute.

         The API implementation will use the service type names supplied
         by this property to discover only those SAs (and their scopes)
         which support the desired service type or types.  For example,
         if net.slp.typeHint is set to "service:imap,service:pop3" then
         SA discovery requests will include the search filter:


         (|(service-type=service:imap)(service-type=service:pop3))


         The API library can also use unicast to contact the discovered
         SAs for subsequent requests for these service types, to
         optimize network access.

2.1.8. Security

   The property in this section allows security for all agents to be set
   on or off.  When the property is true, then the agent must include
   security information on all SLP messages transacted by that agent.
   Since security policy must be set network wide to be effective, a
   single property controls security for all agents.  Key management and
   management of SLP SPI strings [7] are implementation and policy
   dependent.

      net.slp.securityEnabled

         A boolean indicating whether the agent should enable
         security for URLs, attribute lists, DAAdverts, and SAAdverts.
         Each agent is responsible for interpreting the property
         appropriately.  Default is false.

Top      ToC       Page 16 
2.2. Multihomed Machines

   On multihomed machines, the bandwidth and latency characteristics on
   different network interfaces may differ considerably, to the point
   where different configuration properties are necessary to achieve
   optimal performance.  The net.slp.interfaces property indicates which
   network interfaces are SLP enabled.  An API library implementation
   may support configuration customization on a per network interface
   basis by allowing the interface IP address to be appended to the
   property name.  In that case, the values of the property are only
   used for that particular interface, the generic property (or defaults
   if no generic property is set) applies to all others.

   For example, if a configuration has the following properties:


      net.slp.interfaces=125.196.42.41,125.196.42.42,125.196.42.43
      net.slp.multicastTTL.125.196.42.42=1


   then the network interface on subnet 42 is restricted to a TTL of 1,
   while the interfaces on the other subnets have the default multicast
   radius, 255.

   The net.slp.interfaces property must only be set if there is no
   routing between the interfaces.  If the property is set, the DA (if
   any) and SAs should advertise with the IP address or host name
   appropriate to the interface on the interfaces in the list.  If
   packets are routed between the interfaces, then the DA and SAs should
   only advertise on the default interface.  The property should also be
   set if broadcast is used rather than multicast on the subnets
   connected to the interfaces.  Note that even if unicast packets are
   not routed between the interfaces, multicast may be routed through
   another router.  The danger in listening for multicast on multiple
   interfaces when multicast packets are routed is that the DA or SA may
   receive the same multicast request via more than one interface.
   Since the IP address is different on each interface, the DA or SA
   cannot identify the request as having already being answered via the
   previous responder's list.  The requesting agent will end up getting
   URLs that refer to the same DA or service but have different
   addresses or host names.

2.3. Serialized Registration File

   The serialized registration file contains a group of registrations
   that a DA or SA server (if one exists) registers when it starts up.
   These registrations are primarily for older service programs that do
   not internally support SLP and cannot be converted, and for portably

Top      ToC       Page 17 
   exchanging registrations between SLP implementations.  The character
   encoding of the registrations is required to be UTF-8.

   The syntax of the serialized registration file, in ABNF format [5],
   is as follows:


      ser-file      =  reg-list
      reg-list      =  reg / reg reg-list
      reg           =  creg / ser-reg
      creg          =  comment-line ser-reg
      comment-line  =  ( "#" / ";" ) 1*allchar newline
      ser-reg       =  url-props [slist] [attr-list] newline
      url-props     =  surl "," lang "," ltime [ "," type ] newline
      surl          =  ;The registration's URL. See
                       ; [8] for syntax.
      lang          =  1*8ALPHA [ "-" 1*8ALPHA ]
                       ;RFC 1766 Language Tag see [6].
      ltime         =  1*5DIGIT
                       ; A positive 16-bit integer
                       ; giving the lifetime
                       ; of the registration.
      type          =  ; The service type name, see [7]
                       ; and [8] for syntax.
      slist         =  "scopes" "=" scope-list newline
      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

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

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

Top      ToC       Page 20 
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

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

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

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

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

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



(page 25 continued on part 2)

Next RFC Part