[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: (RFC 2614) 00 01

                                                            James Kempf
Internet Draft                                             Erik Guttman
Document: draft-kempf-svrloc-rfc2614bis-00.txt
Expires: August 2002                                      Feburary 2002


                        An API for Service Location



Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups. Note that
   other groups may also distribute working documents as Internet-
   Drafts.
   Internet-Drafts are draft documents valid for a maximum of six
   months and may be updated, replaced, or obsoleted by other documents
   at any time. It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."
   The list of current Internet-Drafts can be accessed at
        http://www.ietf.org/ietf/1id-abstracts.txt
   The list of Internet-Draft Shadow Directories can be accessed at
        http://www.ietf.org/shadow.html.

Abstract
   The Service Location Protocol (SLP) provides a way for clients to
   dynamically discovery network services. This document describes a
   standardized API for SLP in the C language. In addition,
   standardized file formats for configuration and serialized
   registrations are defined. This document defines a new API for SLP
   that supercedes the definition in RFC 2614.

Table of Contents

   1.0  Introduction.................................................3
   1.1  Terminology..................................................3
   2.0  File Formats.................................................3
   2.1  Configuration File Format....................................4
   2.1.1 DA configuration............................................6
   2.1.2 Preconfiguration............................................6
   2.1.3 Tracing and Logging.........................................7
   2.1.4 Serialized Proxy Registrations..............................7
   2.1.5 Network Configuration Properties............................7
   2.1.6 SA Configuration............................................9
   2.1.7 UA Configuration............................................9
   2.2 Serialized Registration File.................................10
   2.3  Processing Serialized Registration and Configuration Files..11
   3.0  The API.....................................................11
   3.1 Constant Types...............................................11
   3.1.1 URL Lifetimes..............................................11

   Kempf and Guttman             Informational              [Page 1]

   Internet Draft              SLP API Revised        Feburary, 2002
   3.2 Error Codes..................................................12
   3.3 SLPBoolean...................................................13
   3.4 Structure Types..............................................14
   3.4.1 SLPSrvURL..................................................14
   3.4.2 SLPHandle..................................................15
   3.5  Callback Types..............................................15
   3.5.1 SLPRegReport...............................................15
   3.5.2 SLPSrvTypeCallback.........................................16
   3.5.3 SLPSrvURLCallback..........................................16
   3.5.4 SLPAttrCallback............................................17
   3.6  Opening and Closing an SLPHandle............................18
   3.6.1 SLPOpen....................................................18
   3.6.2 SLPClose...................................................18
   3.7 SA API.......................................................19
   3.7.1 SLPReg.....................................................19
   3.7.2 SLPDereg...................................................20
   3.7.3 SLPFindSrvTypes............................................21
   3.7.4 SLPFindSrvs................................................22
   3.7.5 SLPFindAttrs...............................................23
   3.8 Miscellaneous Functions......................................24
   3.8.1 SLPGetRefreshInterval......................................24
   3.8.2 SLPFindScopes..............................................24
   3.8.3 SLPParseSrvURL.............................................25
   3.8.4 SLPParseAttrs..............................................25
   3.8.5 SLPEscape..................................................26
   3.8.6 SLPUnescape................................................27
   3.8.7 SLPFree....................................................27
   3.8.8 SLPGetProperty.............................................28
   3.8.9 SLPSetProperty.............................................28
   3.8.10 SLPGetExtensionInterface..................................29
   3.8.11 SLPFreeExtensionInterface.................................29
   4.0  Implementation Considerations...............................30
   4.1 Callback Semantics...........................................30
   4.2 Asynchronous Semantics.......................................31
   4.3 Scope and DA Configuration and Discovery.....................32
   4.4 Multithreading...............................................32
   4.5 Type Checking for Registrations..............................32
   4.6 Refreshing Registrations.....................................33
   4.7 Character Set Encoding.......................................33
   4.8 Error Handling...............................................33
   4.9 Modular Implementations......................................34
   4.10 Handling Special Service Types..............................34
   4.11 Syntax for String Parameters................................34
   4.12 Client Side Syntax Checking.................................35
   4.13 SLP Configuration Properties................................35
   4.14 Memory Management...........................................35
   4.15 Multi-homed Hosts...........................................35
   4.16 Unicast UA Requests.........................................36
   4.17 UA Caching..................................................36
   5.0  Deprecated Features.........................................37
   6.0  Example.....................................................37
   7.0  Security Considerations.....................................39
   Kempf and Guttman           Informational                [Page 2]

   Internet Draft              SLP API Revised        Feburary, 2002
   8.0  Acknowledgements............................................39
   9.0  References..................................................40
   10.0  Editors' Addresses.........................................40
   11.0  Full Copyright Statement...................................40


1.0     Introduction

   The Service Location API is designed for standardized access to the
   Service Location Protocol (SLP) through a C language interface. The
   API facilitates writing portable client and service programs. In
   addition, standardized formats for configuration files and for
   serialized registration files are presented. These files allow
   system administrators to configure network parameters, to register
   legacy services that have not been SLP-enabled, and to portably
   exchange configuration and registration files. This document
   supercedes the SLP API definition in RFC 2614 [1] and corresponds to
   the protocol definition described in [8].

1.1 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 [2].

   Please see [8] for specific SLP protocol-related terms.

      SA Server

         Many operating system platforms only allow a single process to
         listen on a particular port number for TCP. Since general
         purpose SAs are required to listen on TCP for SLP requests,
         implementations of the SLP supporting multiple SAs on such
         platforms need to arrange for a single process to do the
         listening. The advertising SAs communicate with that process
         through another mechanism, described here in Section XXX. The
         single listening process is called an SA server. SA servers
         share many characteristics with DAs, but they are not the
         same.

2.0     File Formats

   This section describes the configuration and serialized registration
   file formats. Both files are defined in the UTF-8 character set [4],
   and they must not include a Byte Order Mark (BOM) at the beginning,
   to maximize compatibility with US-ASCII. The rules governing
   attribute tags and values in serialized registration files and
   configuration files are exactly the same as those for the wire
   format described in [8]. Attribute tags and string values 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
   Kempf and Guttman           Informational                [Page 3]

   Internet Draft              SLP API Revised        Feburary, 2002
   ',' is '\2c'. In addition, the characters "\n", "\r", "\t", and '_'
   are prohibited from attribute tags by the SLP wire syntax grammar
   [8]. Other characters may be escaped, and are processed into the
   corresponding characters upon input, exactly as for reserved
   characters.

   In file encodings for attribute values, 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 as attribute values. In a
   string beginning with "\ff", if any characters are not escaped, it
   is a syntax error.

   Escaped characters in URLs use the URL escape convention [3].

   Property names and values in the configuration file have a few
   reserved characters that are involved in file's lexical definition,
   in addition to those involving attributes described above, for those
   property values that contain attribute list definitions. The
   characters '.' and '=' are reserved in property names and must be
   escaped. The characters ',', '(', and ')' are reserved in all
   property values, not just attribute list definitions, and must be
   escaped. In addition, scope names in the net.slp.configuredScopes
   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 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. 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 implement the SLP
   protocol (see [8]), 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 [6] syntax is:

            config-file   =  line-list
            line-list     =  line / line line-list
            line          =  property-line / comment-line
   Kempf and Guttman           Informational                [Page 4]

   Internet Draft              SLP API Revised        Feburary, 2002
            comment-line  =  ( "#" / ";" ) 1*allchar newline
            property-line =  property newline
            property      =  tag "=" value-list
            tag           =  prop / prop "." tag
            prop          =  1*tagchar
            list          =  value / value "," list
            value         =  int / bool / attribute /
                             string / addr
            int           =  1*DIGIT
            bool          =  "true" / "false" / "TRUE" / "FALSE"
            newline       =  CR / ( CRLF )
            string        =  1*stringchar
            attribute     =  ; see the definition of attribute
                             ; list in Section 4.3.6 of [8].
            addr          =  fqdn / hostnumber
            fqdn          =  ALPHA / ALPHA *[ anum / "-" ] anum
            anum          =  ALPHA / DIGIT
            hostnumber    =  1*3DIGIT 3("." 1*3DIGIT)
            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

   All properties can be changed through the SLPSetProperty() API
   function. However, changing certain properties has no effect on
   further execution in the API library, since these properties are
   only involved in conveying preconfigured information to the API
   library on startup and are not used afterwards. These properties are
   net.slp.configuredScopes, net.slp.configuredDAAddresses, and
   net.slp.enableBroadcast.

   On multi-homed hosts, it may be necessary to have different network
   configuration properties for different interfaces. 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 or host name 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 file 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

   Kempf and Guttman           Informational                [Page 5]

   Internet Draft              SLP API Revised        Feburary, 2002
   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
   TTL, 255.


   The following subsections describe an area and its properties.

2.1.1   DA configuration

   The following properties are used for DA configuration. They are
   ignored if the host is not configured as a DA:

      net.slp.isDA
         Type:    Boolean
         Default: FALSE
         Use:     A Boolean configuring the SLP server to act as a DA.
                  If TRUE, run as a DA.

       net.slp.DAHeartBeat
         Type:    Unsigned 32 bit integer
         Default: 10800 seconds (3 hours)
         Use:     The number of seconds between transmission of
                  unsolicited DAAdverts by the DA. This property
                  corresponds to the protocol specification parameter
                  CONFIG_DA_BEAT [8].

       net.slp.DAAttributes
         Type:    List of Attribute
         Default: Null
         Use:     A list of parenthesized attribute/value list pairs
                  that the DA must advertise in DAAdverts.

2.1.2   Preconfiguration

   The following properties convey statically configured or DHCP-
   configured information to all agents. Changing these properties
   using SLPSetProperty() has no effect on execution.

       net.slp.configuredScopes
         Type:    List of String
         Default: Null
         Use:     A list of statically configured or DHCP-configured
                  scopes.

      net.slp.configuredDAAddresses
         Type:    List of Address
         Default: Null
         Use:     A list of statically configured or DHCP-configured DA
                  IP addresses or DNS-resolvable host names.

      net.slp.enableBroadcast
         Type:    Boolean
         Default: FALSE
         Use:     If TRUE, enable all SLP agents to use broadcast
                  instead of multicast, and disable multicast.

   Kempf and Guttman           Informational                [Page 6]

   Internet Draft              SLP API Revised        Feburary, 2002
2.1.3   Tracing and Logging

   The following properties are used to control tracing and logging of
   error and warning messages.

      net.slp.traceDATraffic
         Type:    Boolean
         Default: FALSE
         Use:     If TRUE, print log messages about traffic to DAs.

      net.slp.traceMsg
         Type:    Boolean
         Default: FALSE
         Use:     If TRUE, print log messages of all incoming and
                  outgoing SLP messages.

      net.slp.traceDrop
         Type:    Boolean
         Default: FALSE
         Use:     If TRUE, print log messages when a SLP message is
                  dropped for any reason.

      net.slp.traceReg
         Type:   Boolean
         Default FALSE
         Use:    If TRUE, dump all registred services when a
                  registration or deregistration occurs.

2.1.4   Serialized Proxy Registrations

   The following property controls processing of serialized
   registrations.

      net.slp.serializedRegURL
         Type:    String
         Default: Null
         Use:     A URL pointing to a document containing serialized
                  registrations that should be processed when the DA or
                  SA server starts up.

2.1.5   Network Configuration Properties

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

      net.slp.multicastTTL
         Type:    Positive integer less than or equal to 255
         Default: 255
         Use:     Multicast TTL.

      net.slp.DAActiveDiscoveryInterval
         Type:    Unsigned 16 bit integer
         Default: 900
         Use:     The number of seconds between DA active discovery
                  queries. The queries may be done periodically or in
                  response to a particular SLP operation. This property
   Kempf and Guttman           Informational                [Page 7]

   Internet Draft              SLP API Revised        Feburary, 2002
                  corresponds to the protocol specification parameter
                  CONFIG_DA_FIND [8]. If the property is set to zero,
                  active discovery is turned off.

      net.slp.passiveDADetection
         Type:    Boolean
         Default: TRUE
         Use:     If FALSE, ignore any unsolicited DAAdverts that are
                  received.

      net.slp.multicastMaximumWait
         Type:   Positive 32 bit integer.
         Default 15000 ms (15 sec.)
         Use:    Maximum number of milliseconds to multicast a request
                  before giving up. This property corresponds to the
                  CONFIG_MC_MAX parameter in the protocol specification
                  [8].

      net.slp.multicastTimeouts
         Type:    List of positive 32 bit integer
         Default: 3000,3000,3000,3000,3000
         Use:     The timeouts, in milliseconds, to use for multiple
                  attempts at multicast for UA requests. Each value
                  specifies the time to wait before sending the next
                  request, or until nothing new has been learned from
                  two successive requests. The sum should equal
                  net.slp.multicastMaximumWait.

      net.slp.DADiscoveryTimeouts
         Type:    List of positive 32 bit integer
         Default: 2000,2000,2000,2000,3000,4000
         Use:     The timeouts, in milliseconds, to use for multiple
                  attempts at multicast for 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. The sum should equal
                  net.slp.multicastMaximumWait.

      net.slp.datagramTimeouts
         Type:    List of positive 32 bit integer
         Default: 3000,3000,3000,3000,3000
         Use:     The timeouts, in milliseconds, to use for
                  retransmitting unicast UDP requests. 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
                  should equal the protocol specification property
                  CONFIG_RETRY_MAX [8].

      net.slp.randomWaitBound
         Type:    Positive 32 bit integer
         Default: 1000 ms (1 sec.)
         Use:     The maximum value in milliseconds for all random wait
                  parameters. This value corresponds to the protocol
                  specification parameters CONFIG_START_WAIT,
                  CONFIG_REG_PASSIVE, and CONFIG_REG_ACTIVE [8].

   Kempf and Guttman           Informational                [Page 8]

   Internet Draft              SLP API Revised        Feburary, 2002
      net.slp.MTU
         Type:    Positive 16 bit integer
         Default: 1500
         Use:     Maximum datagram size for an SLP agent to send, and
                  includes IP and UDP or TCP headers.

      net.slp.interfaces
         Type:    List of Address
         Default: System Default
         Use:     List of IP addresses for interfaces on the host on
                  which the DA or SA server should listen on port 427
                  for multicast, unicast UDP, and TCP messages.

2.1.6   SA Configuration

   The following properties are used for SA or SA server configuration.

      net.slp.SAAttributes
         Type:    List of Attribute
         Default: "(service-type=" <list of service types> ")"
         Use:     A list of attribute definitions advertised by the SA
                  in an SAAdvert. The list must contain the "service-
                  type" attribute with value equal to all service types
                  advertised by the SA.

2.1.7   UA Configuration

   The following properties are used by the UA for configuration. They
   can be set dynamically through SLPSetProperty() to alter API library
   execution.

      net.slp.locale
         Type:    RFC 1766 Language Tag [7]
         Default: "en"
         Use:     The default locale used for language tags in SLP
                  messages. This property is also used for SA and DA
                  configuration.

      net.slp.maxResults
         Type:    Nonnegative 32 bit integer, and -1
         Default: -1
         Use:     The maximum number of results to report. A value of
                  -1 indicates that all requests should be reported.

      net.slp.typeHint
         Type:    List of string
         Default: Null
         Use:     A list of service type names that are used when
                  performing SA discovery

      net.slp.enableUnicastSARequest
         Type:    Boolean
         Default: FALSE
         Use:     If TRUE, the UA uses unicast to contact SAs directly
                  rather than multicast, and does not use DAs even if
                  DAs are available
   Kempf and Guttman           Informational                [Page 9]

   Internet Draft              SLP API Revised        Feburary, 2002
2.2 Serialized Registration File

   The serialized registration file contains a group of proxy
   registrations that a DA or SA server performs 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
   exchanging registrations between SLP implementations. The character
   encoding of the registrations is UTF-8.

   The syntax of the serialized registration file, in ABNF format [6],
   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 [attr-list] newline
      url-props     =  surl "," lang "," ltime [ "," type ] newline
      surl          =  ;The registration's URL. See
                       ; [9] for syntax.
      lang          =  1*8ALPHA [ "-" 1*8ALPHA ]
                       ;RFC 1766 Language Tag see [7].
      ltime         =  1*5DIGIT
                       ; A positive 16-bit integer
                       ; giving the lifetime
                       ; of the registration.
      type          =  ; The service type name, see [8]
                       ; and [9] for 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 [8] for syntax.
      attr-val-list =  attr-val / attr-val "," attr-val-list
      attr-val      =  ;Attribute value, see [8] 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 attribute tags and attribute value lists is specified
   in [8]. DAs and SA servers that process serialized registrations
   must handle them exactly as if they were registered by an SA. In the
   url-props production, the type token is optional. If the type token
   is absent, the URL's scheme is used as the type. If the maximum
   lifetime is specified (65535 sec.), the advertisement is taken to be
   permanent, and is continually refreshed by the DA or SA server until
   it exits. The API library should respect any advertised DA minimum
   refresh interval values, and otherwise, should only register after
   half or more of the lifetime has expired. If the lifetime is other
   than the maximum, the advertisement times out after the lifetime

   Kempf and Guttman           Informational                [Page 10]

   Internet Draft              SLP API Revised        Feburary, 2002
   expires. Advertisements are registered in the scopes with which the
   DA or SA server is configured.

2.3 Processing Serialized Registration and Configuration Files

   Implementations are encouraged to make processing of configuration
   and serialized registration files as transparent as possible to
   clients of the API. Agents processing the configuration file and the
   serialized registration file must log any errors using the platform
   specific error reporting mechanism. An agent must not fail if a file
   format error occurs.

   For configuration files, errors must be caught at the latest when
   the relevant configuration item is used. Errors may be caught at the
   earliest when the configuration file is loaded into the executing
   agent. The default value must be substituted when an error is
   caught. Configuration file loading must complete prior to the
   initiation of the first networking connection.

   For serialized registration files, errors must be caught and
   reported when the file is loaded, and the offending registration
   must be rejected. Serialized registration must be complete before
   the DA or SA server accepts the first network request.

3.0     The API

   The C language binding presents a minimal overhead implementation
   mapping directly into the protocol. 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 in the
   multi-byte UTF-8 encoding but they must be passed as a type char*, a
   null terminated array of bytes.  In the common case of US-ASCII, the
   usual one byte per character C strings work because the US-ASCII
   encoding is a subset of the UTF-8 encoding.

   Unless otherwise noted, a NULL parameter value can be used to denote
   "no value." Some parameters may have restrictions. If any parameter
   fails to satisfy the restrictions on its value, the operation
   returns a PARAMETER_BAD error.

   An exception is scope lists in the UA API. A NULL or empty string
   for a scope list parameter indicates "default the list". Section 4.3
   describes how to construct the default list.

3.1 Constant Types

3.1.1   URL Lifetimes

Synopsis

      typedef enum {
        SLP_LIFETIME_DEFAULT = 10800,
        SLP_LIFETIME_MAXIMUM = 65535
      } SLPURLLifetime;

   Kempf and Guttman           Informational                [Page 11]

   Internet Draft              SLP API Revised        Feburary, 2002
Description

   The SLPURLLifetime enum type contains frequently used URL lifetime
   values, in seconds. 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. A registration
   made with SLP_LIFETIME_MAXIMUM causes the service advertisement to
   be automatically re-registered.

3.2 Error Codes

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_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 ;

Description

   The SLPError enum contains error codes that are returned from API
   functions or passed as error parameters to callback functions.

   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.

   The error codes SLP_OK, SLP_LANGAUGE_NOT_UNDERSTOOD,
   SLP_PARSE_ERROR, SLP_SCOPE_NOT_SUPPORTED, and SLP_REFRESH_REJECTED
   correspond directly to the protocol error codes as described in [8].
   In addition, SLP_PARSE_ERROR may be returned by the API library if
   the library itself detects any syntactic errors.

   The remaining error codes indicate the following conditions:

      SLP_LAST_CALL

         The SLP_LAST_CALL code is passed to callback functions for
         both synchronous and asynchronous calls when the API library
         has no more data for them and therefore no further calls will
   Kempf and Guttman           Informational                [Page 12]

   Internet Draft              SLP API Revised        Feburary, 2002
         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. The other callback
         parameters are all NULL. If an SLP request results in no
         return values, then only one call is made, with the error
         parameter set to SLP_LAST_CALL.

      SLP_NETWORK_INIT_FAILED

         The network failed to initialize properly.

      SLP_NETWORK_TIMED_OUT

         No reply can be obtained in the time specified by the
         configured timeout interval for a unicast request.

      SLP_NETWORK_ERROR

         Networking failed during normal operation.

      SLP_BUFFER_OVERFLOW

         An outgoing request overflowed the maximum network MTU size.

      SLP_MEMORY_ALLOC_FAILED

         The API failed to allocate memory.

      SLP_PARAMETER_BAD

         A bad parameter was passed into the API.

      SLP_INTERNAL_SYSTEM_ERROR

         A basic failure of the API, such as the failure of a system
         call, occurred.

      SLP_HANDLE_IN_USE

         An attempt was made to make an API call on an SLPHandle that
         already has an outstanding call on it.

      SLP_TYPE_ERROR

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

   More information on the causes of these errors may be available
   through the platform specific system error reporting API.

3.3 SLPBoolean

   Kempf and Guttman           Informational                [Page 13]

   Internet Draft              SLP API Revised        Feburary, 2002
Synopsis

      typedef enum {
        SLP_FALSE = 0,
        SLP_TRUE = 1
      } SLPBoolean;

Description

   The SLPBoolean enum is used as a Boolean flag.

3.4 Structure Types

3.4.1   SLPSrvURL

Synopsis

      typedef struct srvurl {
        char *s_pcSrvType;
        char *s_pcHost;
        int   s_iPort;
        char *s_pcNetFamily;
        char *s_pcSrvPart;
      } SLPSrvURL;

Description

   The SLPSrvURL structure is filled in by the SLPParseSrvURL()
   function when a service URL string is parsed. 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
         [8].

      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.

      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
   Kempf and Guttman           Informational                [Page 14]

   Internet Draft              SLP API Revised        Feburary, 2002
         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.

3.4.2   SLPHandle

Synopsis

      typedef void* SLPHandle;

Description

   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.

3.5 Callback Types

   The callback functions report the results of an SLP protocol
   operation. 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
   starting the operation to pass information down to the callback
   through the API function without using global variables. If the
   cookie is not set when the API function is called, the parameter is
   NULL.

   The callback returns an SLPBoolean to indicate whether the API
   library should continue processing the operation. If the value
   returned from the callback is SLP_TRUE, asynchronous operations are
   terminated, synchronous operations ignore the return, since the
   operation is already complete.

   Section 4.1 contains more detail on callback processing.

3.5.1   SLPRegReport

Synopsis

   typedef void SLPRegReport(SLPHandle hSLP,
                             SLPError  errCode,
                             void      *pvCookie);

Description

   The SLPRegReport callback type is the type of the callback function
   to the SLPReg() and SLPDereg() functions.

Parameters

      hSLP
   Kempf and Guttman           Informational                [Page 15]

   Internet Draft              SLP API Revised        Feburary, 2002
         The SLPHandle used to initiate the operation.

      errCode
         The error code.

      pvCookie
         The cookie.

3.5.2   SLPSrvTypeCallback

Synopsis

   typedef SLPBoolean SLPSrvTypeCallback(SLPHandle   hSLP,
                                         const char* pcSrvTypes,
                                         SLPError    errCode,
                                         void        *pvCookie);

Description

   The SLPSrvTypeCallback callback type is the type of the callback
   function parameter to the SLPFindSrvTypes() function.

Parameters

      hSLP
         The SLPHandle used to initiate the operation.

      pcSrvTypes
         A character buffer containing a comma separated, null
         terminated list of service types.

      errCode
         The error code.

      pvCookie
         The cookie.
Returns

   The client code should return SLP_TRUE if more data is desired,
   otherwise SLP_FALSE.

3.5.3   SLPSrvURLCallback

Synopsis

   typedef SLPBoolean SLPSrvURLCallback(SLPHandle      hSLP,
                                        const char*    pcSrvURL,
                                        unsigned short sLifetime,
                                        SLPError       errCode,
                                        void           *pvCookie);

Description

   The SLPSrvURLCallback callback type is the type of the callback
   function parameter to the SLPFindSrvs() function.

   Kempf and Guttman           Informational                [Page 16]

   Internet Draft              SLP API Revised        Feburary, 2002
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
         The error code.

      pvCookie
         The cookie.

Returns

   The client code should return SLP_TRUE if more data is desired,
   otherwise SLP_FALSE.

3.5.4   SLPAttrCallback

Synopsis

   typedef SLPBoolean SLPAttrCallback(SLPHandle   hSLP,
                                      const char* pcAttrList,
                                      SLPError    errCode,
                                      void        *pvCookie);


Description

   The SLPAttrCallback type is the callback type of the callback
   function parameter to SLPFindAttrs() function.

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, see [8] for details.

      errCode
         The error code.

      pvCookie
         The cookie.

Returns
   Kempf and Guttman           Informational                [Page 17]

   Internet Draft              SLP API Revised        Feburary, 2002

   The client code should return SLP_TRUE if more data is desired,
   otherwise SLP_FALSE.

3.6 Opening and Closing an SLPHandle

3.6.1   SLPOpen

Synopsis

   SLPError SLPOpen(const char *pcLang,
                    SLPBoolean isAsync,
                    SLPHandle  *phSLP);

Description

   Returns a SLPHandle handle in the phSLP parameter for the language
   locale passed in as the pcLang parameter. If the isAsync parameter
   is TRUE, operations are performed asynchronously. 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.

   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. If an implementation is unable to
   support an asynchronous (resp. synchronous) operation, due to memory
   constraints or lack of threading support, the SLP_NOT_IMPLEMENTED
   flag must be returned when the isAsync flag is SLP_TRUE (resp.
   SLP_FALSE).

Parameters

      pcLang
         The RFC 1766 Language Tag [7] for the natural language locale
         of requests and registrations issued on the handle.

      isAsync
         A 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.

3.6.2   SLPClose

Synopsis

   void SLPClose(SLPHandle hSLP);

Description
   Kempf and Guttman           Informational                [Page 18]

   Internet Draft              SLP API Revised        Feburary, 2002

   Frees all resources associated with the handle. If the handle was
   invalid, the function returns silently. Any outstanding synchronous
   or asynchronous operations are cancelled immediately, so their
   callback functions will not be called any further.

Parameters

      SLPHandle
         A SLPHandle handle returned from a call to SLPOpen().

3.7 SA API

3.7.1   SLPReg

Synopsis

   SLPError SLPReg(SLPHandle            hSLP,
                   const char           *pcSrvURL,
                   const unsigned short usLifetime,
                   const char           *pcSrvType,
                   const char           *pcAttrs
                   SLPBoolean           fresh,
                   SLPRegReport         callback,
                   void                 *pvCookie);

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. The pcSrvType
   parameter is a service type name and may be NULL or the empty string
   if the URL is a service: URL. The fresh parameter is ignored. The
   format for pcAttrs and pcScopeList can be found in [8].
   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.

Parameters

      hSLP
         The language specific SLPHandle on which to register the
         advertisement.

      pcSrvURL
         The URL to register. May not be NULL or the empty string. This
         parameter must be a properly formatted URL [3]; otherwise, the
         SLP SrvReg returns a parse error and the callback is called
         with the SLP_PARSE_ERROR error code.

      usLifetime

   Kempf and Guttman           Informational                [Page 19]

   Internet Draft              SLP API Revised        Feburary, 2002
         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 a service: URL is present in pcSrvURL and
         this parameter is NULL or an empty string, then the value of
         the the service type field in the SrvReg message is obtained
         from the service: URL's scheme [8].

      pcAttrs
         A comma separated list of attribute assignment expressions for
         the attributes of the advertisement. See [8] for the format.
         Use NULL or the empty string for no attributes.

      fresh
         Ignored.

      callback
         A callback to report the operation completion status.

      pvCookie
         Memory passed to the callback code from the client. May be
         NULL.

Returns

   One of the SLPError codes is returned indicating the status of
   starting the operation.

3.7.2   SLPDereg

Synopsis

   SLPError SLPDereg(SLPHandle    hSLP,
                     const char   *pcURL,
                     SLPRegReport callback,
                     void         *pvCookie);

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.

Parameters

      hSLP
         The language specific SLPHandle to use for deregistering.

      pcURL
         The URL to deregister. May not be the empty string. This
         parameter must be a properly formatted URL [3]; otherwise, the
   Kempf and Guttman           Informational                [Page 20]

   Internet Draft              SLP API Revised        Feburary, 2002
         SLP SrvDeReg returns a parse error and the callback is called
         with the SLP_PARSE_ERROR error code.

      callback
         A callback to report the operation completion status.

      pvCookie
         Memory passed to the callback code from the client. May be
         NULL.
Returns

   One of the SLPError codes is returned indicating the status of
   starting the operation.

3.7.3   SLPFindSrvTypes

Synopsis

   SLPError SLPFindSrvTypes(SLPHandle           hSLP,
                            const char         *pcNamingAuthority,
                            const char         *pcScopeList,
                            SLPSrvTypeCallback callback,
                            void               *pvCookie);

Description

   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 NULL or the empty
   string, 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 [8]. See [9] for more information on the syntax of
   service type names.

Parameters

      hSLP
         The SLPHandle on which to search for types.

      pcNamingAuthority
         The naming authority to search. Use "*" for all naming
         authorities and NULL or the empty string for the default
         naming authority.

      pcScopeList

   Kempf and Guttman           Informational                [Page 21]

   Internet Draft              SLP API Revised        Feburary, 2002
         The comma separated list of scope names to search for service
         types. Use NULL or the empty string for the default scope
         list.

      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.

Returns

   One of the SLPError codes is returned indicating the status of
   starting the operation.

3.7.4   SLPFindSrvs

Synopsis

      SLPError SLPFindSrvs(SLPHandle         hSLP,
                           const char        *pcServiceType,
                           const char        *pcScopeList,
                           const char        *pcSearchFilter,
                           SLPSrvURLCallback callback,
                           void              *pvCookie);

Description

   Issue the query for services on the locale-specific SLPHandle and
   return the results through the callback. The parameters determine
   the results.

Parameters

      hSLP
         The locale-specific SLPHandle on which to search for services.

      pcServiceType
         The service type name, including naming authority if any, for
         the request, such as can be discovered using SLPSrvTypes().
         May not be NULL or the empty string.

      pcScopeList
         The comma separated list of scope names. Use NULL or the empty
         string for the default scope list.

      pcSearchFilter
         A query formulated of attribute pattern matching expressions
         in the form of an LDAPv3 Search Filter, see [5]. If this
         filter is NULL or the empty string, all services of the
         requested type in the specified scopes are returned. The
         search filter should be a simple search filter as defined in
         [8].

   Kempf and Guttman           Informational                [Page 22]

   Internet Draft              SLP API Revised        Feburary, 2002
      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.

Returns

   One of the SLPError codes is returned indicating the status of
   starting the operation.

3.7.5   SLPFindAttrs

Synopsis

   SLPError SLPFindAttrs(SLPHandle        hSLP,
                         const char      *pcURL,
                         const char      *pcScopeList,
                         const char      *pcAttrIds,
                         SLPAttrCallback callback,
                         void            *pvCookie);
Description

   This function returns service attributes matching the attribute ids
   for the indicated URL. The attribute information returned is for the
   matching advertisement in the locale of the SLPHandle.
   The result is filtered with an SLP attribute request filter string
   parameter, pcAttrIds, the syntax of which is described in [8]. If
   the filter string is NULL or the empty string, all attributes are
   returned.

Parameters

      hSLP
         The language specific SLPHandle on which to search for
         attributes.

      pcURL
         The URL. May not be NULL or the empty string. This parameter
         must be a properly formatted URL [3]; otherwise, the SLP
         AttrRqst returns a parse error and the callback is called with
         the SLP_PARSE_ERROR error code.

      pcScopeList
         The comma separated list of scope names. Use NULL or the empty
         string for the default scope list.

      pcAttrIds
         The filter string indicating which attribute values to return.
         Use NULL or the empty string to indicate all values. See [8]
         for the exact format of the filter string.

      callback

   Kempf and Guttman           Informational                [Page 23]

   Internet Draft              SLP API Revised        Feburary, 2002
         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.

Returns

   One of the SLPError codes is returned indicating the status of
   starting the operation.

3.8 Miscellaneous Functions

3.8.1   SLPGetRefreshInterval

Synopsis

   unsigned short SLPGetRefreshInterval();

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 as the minimum service
   advertisement lifetime, assures that no refresh registration will be
   rejected. If no DA advertises a min-refresh-interval attribute, a
   value of 0 is returned.

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.

3.8.2   SLPFindScopes

Synopsis

   SLPError SLPFindScopes(SLPHandle hSLP,
                          char      **ppcScopeList);

Description

   Sets ppcScopeList parameter to a pointer to a comma separated list
   including all available scope values. See Section 4.3 for a
   description of how the list is determined. 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".

Parameters

      hSLP
         The SLPHandle on which to search for scopes.

   Kempf and Guttman           Informational                [Page 24]

   Internet Draft              SLP API Revised        Feburary, 2002
      ppcScopeList
         On return, contains a pointer to a null terminated string with
         the comma-separated list of scopes. The memory should be freed
         by calling SLPFree().

Returns

   If no error occurs, returns SLP_OK, otherwise, the appropriate error
   code.

3.8.3   SLPParseSrvURL

Synopsis

   SLPError SLPParseSrvURL(char        *pcSrvURL
                           SLPSrvURL** ppSrvURL);

Description

   The URL passed in as the argument is parsed into a SLPSrvURL
   structure and is return in the ppSrvURL pointer. If a parse error
   occurs, returns SLP_PARSE_ERROR as the value of the function. The
   input buffer pcSrvURL may be 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 SLPFree().

   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.

Parameters

      pcSrvURL
         The null terminated URL string to parse. It may be
         destructively modified to produce the output structure. This
         parameter must be a properly formatted URL; otherwise,
         function returns the SLP_PARSE_ERROR error code.

      ppSrvURL
         On return, contains a pointer to the SLPSrvURL structure with
         the parsed URL, or NULL if the parse failed. The memory should
         be freed by a call to SLPFree() when no longer needed.

Returns

   If no error occurs, the return value is SLP_OK. Otherwise, the
   appropriate error code is returned.

3.8.4    SLPParseAttrs

Synopsis

   SLPError SLPParseAttrs(const char *pcAttrList,
                          const char *pcAttrId,
   Kempf and Guttman           Informational                [Page 25]

   Internet Draft              SLP API Revised        Feburary, 2002
                          char       **ppcAttrVal);
Description

   Parses an attribute list to obtain the attribute value of a specified
   attribute ID. SLP_PARSE_ERROR is returned if a value for pcAttrId can
   not be found. The attribute value string returned in ppcAttrVal must
   be freed with SLPFree().

Parameters

      pcAttrList
         A comma separated list of attribute assignment expressions. See
         [8] for the format.
      pcAttrId
         The string indicating which attribute value to return. May not
         be NULL or the empty string.
      ppcAttrVal
         Upon return, a pointer to the buffer containing the attribute
         value.  The returned memory should be freed by a call to
         SLPFree() when no longer needed.

Returns

   If no error occurs, the return value is SLP_OK. Otherwise, the
   appropriate error code is returned. If this function is not
   implemented, the library should return SLP_NOT_IMPLEMENTED.  If a
   parse error occurs, the library should return SLP_PARSE_ERROR.

3.8.5   SLPEscape

Synopsis

   SLPError SLPEscape(const char *pcInbuf,
                      char        **ppcOutBuf,
                      SLPBoolean isTag);

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.

Parameters

      pcInbuf
         Pointer to he input buffer to process for escape characters.

      ppcOutBuf
         On output, contains a pointer to a copy of the input 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.

Returns

   Kempf and Guttman           Informational                [Page 26]

   Internet Draft              SLP API Revised        Feburary, 2002
   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.

3.8.6   SLPUnescape

Synopsis

   SLPError SLPUnescape(const char *pcInbuf,
                        char        **ppcOutBuf,
                        SLPBoolean isTag);

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 SLP 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.

Parameters

      pcInbuf
         Pointer to he input buffer to process for escape characters.

      ppcOutBuf
         On output, contains a pointer to a copy of the input buffer
         with the SLP reserved characters unescaped. Must be freed
         using SLPFree()when the memory is no longer needed.

      isTag
         When true, the input buffer is checked for bad tag characters.

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.

3.8.7   SLPFree

Synopsis

   void SLPFree(void* pvMem);

Description

   Frees memory returned from SLPParseSrvURL(),
   SLPFindScopes(),SLPEscape(), SLPUnescape(), and SLPGetProperty().

Parameters

      pvMem
   Kempf and Guttman           Informational                [Page 27]

   Internet Draft              SLP API Revised        Feburary, 2002
         A pointer to the storage allocated by the
         SLPParseSrvURL(),SLPEscape(), SLPUnescape(), or
         SLPFindScopes() function. Ignored if NULL.

3.8.8   SLPGetProperty

Synopsis

   SLPError SLPGetProperty(const char *pcPropertyName,
                           char       **ppcPropertyValue);

Description

   Upon return, the ppcPropertyValue parameter is set to a pointer to
   the property value string corresponding to pcPropertyName, or NULL
   if the pcPropertyName string does not name a valid SLP property. The
   ppcPropertyValue buffer should be deallocated using SLPFree() when
   the memory is no longer needed.

Parameters

      pcPropertyName
         Null terminated string with the property name, from Section
         2.1.

      ppcPropertyValue
         On return, contains a pointer to a string with the property
         value, or NULL if the pcPropertyName parameter does not name a
         property.
Returns

   Returns one of the following status codes: SLP_OK,
   SLP_MEMORY_ALLOC_FAILED, SLP_NOT_IMPLEMENTED, or SLP_PARAMETER_BAD.
   The latter is returned if the pcPropertyName parameter does not name
   a valid SLP property.

3.8.9   SLPSetProperty

Synopsis

   SLPError SLPSetProperty(const char *pcPropertyName,
                           const char *pcPropertyValue);

Description

   Sets the value of the SLP property to the new value. The pcValue
   parameter should be the property value as a string.

Parameters

      pcPropertyName
         Null terminated string with the property name, from Section
         2.1.

      pcPropertyValue

   Kempf and Guttman           Informational                [Page 28]

   Internet Draft              SLP API Revised        Feburary, 2002
         Null terminated string with the property value. Use NULL or
         the empty string to indicate that the property should be
         unset, and thus return to default.

Returns

         Returns one of the following status codes: SLP_OK,
         SLP_MEMORY_ALLOC_FAILED, SLP_NOT_IMPLEMENTED, or
         SLP_PARAMETER_BAD. The latter is returned if the
         pcPropertyName parameter does not name a valid SLP property.

3.8.10  SLPGetExtensionInterface

Synopsis

   SLPError SLPGetExtensionInterface(SLPHandle  hSLP,
                                     const char *pcExtName,
                                     void       **ppExtInterface);

Description

   Called with an initialized SLPHandle and the name of an SLP
   extension. On return, a pointer to the extension interface is in the
   ppExtInterface parameter, or NULL if there is no such extension.
   Exactly how the code for the extension is located, the exact format
   of the interface structure implementing access to the extension, how
   the interface code is made available (i.e.dynamically linked v.s.
   statically linked), and how names of extensions are formatted are
   implementation dependent issues.

   Parameters

      hSLP
         The language specific SLPHandle to use for locating the
         extension interface.

      pcExtName
         The name of the extention to return.

      ppExtInterface
         On return, contains a pointer to a structure implementing the
         interface.

Returns

   If no error occurs, the return value is SLP_OK. Otherwise, the
   appropriate error code is returned. If no extension is available
   corresponding to pcExtName, the return value is SLP_NOT_IMPLEMENTED
   and the ppExtInterface parameter is NULL.

3.8.11  SLPFreeExtensionInterface

Synopsis

   SLPError SLPFreeExtensionInterface(void **ppExtInterface);

   Kempf and Guttman           Informational                [Page 29]

   Internet Draft              SLP API Revised        Feburary, 2002
Description

   Free up memory and code associated with the interface accessed
   through ppExtInterface. Upon return, ppExtInterface is NULL and
   the memory for the interface is freed.

Parameters

      ppExtInterface
         A valid interface implementation obtained through
         SLPGetExtInterface()

Return

   If no error occurs, the return value is SLP_OK. Otherwise, the
   appropriate error code is returned.

4.0     Implementation Considerations

   This section discusses a number of implementation considerations.

4.1 Callback Semantics

   There will always be at least one callback for every API operation:
   a callback with the error code set to SLP_LAST_CALL indicating that
   the request has completed. There may be more callbacks in certain if
   a result is returned. Any callback in which the error code is not
   set to SLP_LAST_CALL is a return report. If there are no results to
   report, the callback with SLP_LAST_CALL set is the only callback.

   For the SA API, SLPSrvReg() and SLPSrvDereg() callbacks are only
   ever called once with a return report. If the SA API implementation
   performs DA forwarding directly, then it must wait until all DA
   replies are back before calling the callback. If the SA API
   implementation registers with an SA server, the SA server replies
   with a single SrvAck, the contents of which are reported through the
   callback.

   For the UA API, only one callback containing a return report is ever
   made if a DA is in use for SLPFindSrvTypes(). If the UA multicasts a
   request or unicasts to multiple SAs, multiple calls to a callback
   with return reports may result for SLPFindSrvTypes() if multiple
   replies are received. The UA may also collate replies from multiple
   SAs and present them through a single callback. Only one return
   report callback invocation ever occurs for SLPFindAttrs(), and
   multiple callback reports are possible for SLPFindSrvs() regardless
   of how the request was transmitted if multiple URLs are received in
   the reply.

   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
   may terminate 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.
   Kempf and Guttman           Informational                [Page 30]

   Internet Draft              SLP API Revised        Feburary, 2002

   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. 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. Note that this parameter controls
   the number of results received, not the number of return messages.
   In the case of a multicast SrvRqst, for example, the number of
   return messages may be less than the number of results, since one
   message may contain multiple results.

   There are five reasons why a call can terminate:

      DA reply received

         A reply from a DA has been received and therefore nothing more
         is expected, or the request timed out.

      Unicast SA messages received

         All messages were received in reply to a unicast request to
         one or several SAs, or one or more of the requests timed out.

      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 returning the existing
         replies, if any.

      Maximum results

         The user has set the net.slp.maxResults property and that
         number of results has been collected and returned

4.2 Asynchronous Semantics

   If a handle parameter to an API function is opened asynchronously,
   API function calls on the handle check the other parameters, open
   the appropriate operation and return immediately. If the handle
   parameter was opened synchronously, the API function call blocks
   until all results are processed, and returns only after the callback
   function has been called with the callback error code set to
   SLP_LAST_CALL. If an error occurs in the process of starting the SLP
   operation, an error code is returned from the API function. Errors

   Kempf and Guttman           Informational                [Page 31]

   Internet Draft              SLP API Revised        Feburary, 2002
   that occur as a result of the SLP operation are reported to the
   callback, and are not returned from the API function.

   If asynchronous semantics are supported, the API library is required
   to be thread-safe. The API must be re-entrant in order to avoid
   interference between callbacks.


4.3 Scope and DA Configuration and Discovery

   The API must conform to the scope and DA configuration rules
   described in Section 8 of [8]. Preconfigured scopes and DAs, whether
   through static configuration or DHCP configuration, must be
   available via the configuration properties net.slp.configuredScopes
   and net.slp.configuredDAAddresses.

   Functions in the UA API have a scope parameter that determines the
   scopes used in UA requests. If that parameter is not NULL or the
   empty string, then the scopes in that parameter are used for the
   request. If that parameter is NULL or the empty string, the UA API
   library determines the scopes to use in the following fashion. If
   net.slp.configuredScopes is set, the listed scopes on
   net.slp.configuredScopes are used. If net.slp.configuredScopes is
   not set, the UA must use scopes obtained from any configured or
   discovered DAs, or scopes discovered through dynamic SA discovery,
   exactly as would be the case if the SLPFindScopes() function were
   called.

   Dynamic scope and DA information is available at any time through
   the API functions. Calling SLPSrvRqst() with the service type
   parameter set to "service:directory-agent" returns all discoverable
   DAs, including any that were configured. Calling SLPFindScopes()
   returns all discoverable scopes including any that were configured.
   SLPFindScopes() uses the rules outlined in [8] to determine what
   sources to consult for scope information.

4.4 Multithreading

   Implementations of the API are required to make API calls thread-
   safe. Access to data structures shared between threads must be
   coordinated to avoid corruption or invalid access. Implementations
   should also attempt to maximize the amount of concurrent thread
   access to the API library.

4.5 Type Checking for Registrations

   Service templates [9] allow SLP registrations to be type checked for
   correctness. Implementations of the API may use service type
   information for type checking. If a type error occurs, the
   registration should terminate with SLP_TYPE_ERROR.

   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 [9] in order to convert from the string
   representation on the wire to an object typed appropriately.
   Kempf and Guttman           Informational                [Page 32]

   Internet Draft              SLP API Revised        Feburary, 2002
4.6 Refreshing Registrations

   SLP advertisements carry an explicit lifetime. 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: SLPReg() is
   called with the pLifetime parameter equivalent to
   SLP_LIFETIME_MAXIMUM (65535 seconds). Implementations of the SA API
   must provide automatic re-registration if a registration is made
   with the maximum lifetime. A client using 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 times out in
   the DA eventually.

4.7 Character Set Encoding

   Characters buffer parameters are represented in UTF-8 despite the
   defined type of char* or const char*. API functions are required to
   handle the full range of multi-byte 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 anyway.

   Inside URLs, characters that are not allowed by URL syntax [3] 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 API may
   exceed 64K bytes in length. An API function that encounters a string
   longer than 64K should return SLP_PARSE_ERROR.

4.8 Error Handling

   All errors encountered processing SLP messages should be logged,
   especially for the SA server and DA.

   For the UA API, since no errors are returned for multicast requests,
   and only a single DA is ever used at a time, there is only one case
   where multiple invocations of a callback could result in one or more
   calls to callbacks with the error code set to something other than
   SLP_OK: a unicast request to multiple SAs. In all other cases, there
   is a single callback invocation in which the error code is set if an
   error occurs, in addition to the last call callback.

   For the SA client API, a registration or deregistration to one DA
   among several may result in an error, but since only a single
   callback is ever made reporting return status for the SA API, the
   error code is only reported if no SrvAck indicating success was
   received.

   Kempf and Guttman           Informational                [Page 33]

   Internet Draft              SLP API Revised        Feburary, 2002
   Since registration with an SA server results in the same error
   conditions as with a DA, the SA server is not required to forward a
   SrvReg to any DAs if the registration fails. The SA server must
   return a SrvAck to the client with the error code properly set. The
   SA server is also not required to wait to return the SrvAck to the
   SA client until registration with DAs has completed, since any
   errors occurring with DAs are likely to be unrelated to the content
   of the registration if the registration succeeded with the SA
   server.

4.9 Modular Implementations

   Subset implementations that do not support the full range of
   functionality must 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 must be returned. Applications that are
   expected to run on a wide variety of platforms should be prepared
   for subset API implementations by checking returned error codes.

4.10   Handling Special Service Types

   The DA service type, "service:directory-agent", and SA service type,
   "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
   the SA service type and with its URL only to a request for the DA
   service type. The UA would therefore not obtain a complete picture
   of the available DAs and SAs.

4.11 Syntax for String Parameters

   Query strings, attribute registration lists, attribute
   deregistration lists, scope lists, and attribute selection lists
   follow the syntax described in [8] 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 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.

   Kempf and Guttman           Informational                [Page 34]

   Internet Draft              SLP API Revised        Feburary, 2002
   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.12 Client Side Syntax Checking

   Client side API implementations may do syntax checking of scope
   names, naming authority names, and service type names. 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.13 SLP Configuration Properties

   The SLP configuration properties 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.

4.14 Memory Management

   The only API functions returning memory specifically requiring
   deallocation on the part of the client are SLPParseSrvURL(),
   SLPFindScopes(), SLPEscape(), and SLPUnescape(), and
   SLPGetProperty(). This memory should be freed using SLPFree() when
   no longer needed.

   Memory passed to callbacks from the API library belongs to the
   library and MUST NOT be retained or freed 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.15   Multi-homed Hosts

   On a multi-homed host, routing may be disabled between interfaces.
   The net.slp.interfaces property must only be set if there is no
   Kempf and Guttman           Informational                [Page 35]

   Internet Draft              SLP API Revised        Feburary, 2002
   routing between any of the interfaces or if broadcast is used
   instead of multicast. If the net.slp.interfaces is set, the DA (if
   any) and SAs on the host should respond to a DA or SA advertisement
   request with an IP address or host name on the list. Replies to
   requests should be made with service advertisements that are
   reachable through the interface on which the request arrived. If
   packets are routed between the interfaces, then the DA and SAs must
   only advertise on the default interface.

   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 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.


4.16   Unicast UA Requests

   If the net.slp.enableUnicastSARequest property is TRUE, UAs are
   required to use unicast directly to discovered SAs rather than use
   multicast or DAs for the request. This allows the UA to receive
   errors directly from SAs that it otherwise wouldn't, for example, if
   the SA supports simple queries only but the UA issues a complex
   query. For SrvRqst and AttrRqst, prior to sending a request, the UA
   performs a multicast service request for SAs that advertise the
   service type of interest. The request is then unicast to the
   returned SAs. For SrvTypeRqst, the UA performs a service requests
   for all SAs, and either constructs the returned list of service
   types based on the "service-type" attribute definition in the SAs'
   attribute lists, or sends a SrvTypeRqst to each SA individually. The
   UA may cache the results of returned SAAdverts for some period of
   time to avoid having to perform the repeat multicast for SAAdverts.
   Unicasting of UA requests should be used with caution, in
   particular, it should not be used as a substitute for DAs. Deploying
   DAs is likely to result in better network performance and
   scalability.

4.17   UA Caching

   In general, clients of the UA API should limit repeat queries until
   the lifetime of the service advertisement is about to expire.
   Because the base protocol and API lack any support for notification
   when a new service comes up, however, some applications may want to
   poll periodically for new services. Such polling could completely
   overwhelm the network with requests, especially if multicast is in
   use.

   In order to regulate polling, the UA API library should cache the
   results of queries and return them when a repeat query arrives
   within some short time, say 10 seconds. The lifetime of the cache
   entries should be kept short in order to avoid stale information.

   Kempf and Guttman           Informational                [Page 36]

   Internet Draft              SLP API Revised        Feburary, 2002
5.0     Deprecated Features

   The following features were defined in RFC 2614 and have been
   deprecated in this update due to changes in the SLP protocol:

     1) The property net.slp.securityEnabled is no longer supported.
        Security in SLP is now handled through IPSEC. Implementations
        should ignore this property if it is in the configuration file.
     2) Scope lists have been dropped from the serialized registration
        file. Serialized registrations must be made in the configured
        scopes for the DA or SA server. Existing files must be edited
        to remove the scopes attribute definition, because it will
        otherwise be treated as a normal SLP attribute definition
     3) The SLPDelAttrs() function is no longer supported. SLP no
        longer allows incremental update of service advertisements.
        Existing implementations of SLP should return the
        SLP_NOT_IMPLEMENTED error code from this function.
     4) The SLPFindAttrs() function no longer takes a service type
        name. Attribute Request by Service Type has been dropped from
        SLP.
     5) The error codes SLP_AUTHENTICATION_ABSENT,
        SLP_AUTHENTICATION_FAILED, and SLP_INVALID_UPDATE are no longer
        supported because these errors no longer occur in the protocol.

6.0     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
      */
      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.*/
      }

   Kempf and Guttman           Informational                [Page 37]

   Internet Draft              SLP API Revised        Feburary, 2002
   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;
      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
            *     . . .
            */
   Kempf and Guttman           Informational                [Page 38]

   Internet Draft              SLP API Revised        Feburary, 2002

           SLPFreeSrvURL((void*)pSrvURL); /* Free the pSrvURL storage*/
        }

        return SLP_FALSE;                 /* Done! */
      }

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

7.0     Security Considerations

   Security is handled by IPSEC and is not exposed to API clients. An
   adversary could delete valid service advertisements, provide false
   service information and deny UAs knowledge of existing services
   unless IPSEC is used to secure IP traffic between SLP agents, as
   described in [8].

8.0     Acknowledgements


   Kempf and Guttman           Informational                [Page 39]

   Internet Draft              SLP API Revised        Feburary, 2002
   The authors would like to thank Don Provan for his pioneering work
   during the initial stages of the RFC 2614 API definition. The
   contributions of Matt Peterson, Ira McDonald, and Jim Mayer were
   invaluable in preparing the current document.

9.0     References

    [1] Kempf, J. and Guttman, E., "An API for Service Location," RFC
        2614, June, 1999.
    [2] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement
        Levels," BCP 14, RFC 2119, March 1997.
    [3] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
        Resource Identifiers (URI): Generic Syntax," RFC 2396, August
        1998.
    [4] Yergeau, F., "UTF-8, a transformation format of ISO 10646," RFC
        2279, January 1998.
    [5] Howes, T., "The String Representation of LDAP Search Filters,"
        RFC 2254  December 1997.
    [6] Crocker, D. and P. Overell, "Augmented BNF for Syntax
        Specifications: ABNF," RFC 2234, November 1997.
    [7] Alvestrand, H., "Tags for the Identification of Languages," RFC
        1766, March 1995.
    [8] Guttman, E., and J. Kempf, "Service Location Protocol, Version
        2," draft-guttman-rfc2608bis-01.txt, a work in progress.
    [9] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and
        Service: Schemes," RFC 2609, June 1999.

10.0    Editors' Addresses

   Erik Guttman                   James Kempf
   Sun Microsystems, Inc.         DoCoMo Labs, USA
   Eichhoelzelstr. 7              180 Metro Drive, Suite 300
   74915 Waibstadt                San Jose, CA, 95430
   GERMANY                        USA
   Phone: +49 172 865 5497        Phone: +1 408 451 4711
   Email: Erik.Guttman@Sun.Com    Email: kempf@docomolabs-usa.com


11.0    Full Copyright Statement

   Copyright (C) The Internet Society (1999). All Rights Reserved.
   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph
   are included on all such copies and derivative works. However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.
   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.
   Kempf and Guttman           Informational                [Page 40]

   Internet Draft              SLP API Revised        Feburary, 2002
   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
   Funding for the RFC Editor function is currently provided by the
   Internet Society.
















































   Kempf and Guttman           Informational                [Page 41]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/