rfc2614.txt

SLP协议在linux下的实现。此版本为1.2.1版。官方网站为www.openslp.org

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


                      An API for Service Location

Status of This Memo

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

Abstract

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

Table of Contents

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




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


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



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


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






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


1. Introduction

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

1.1. Goals

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

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

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

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

1.2. Terminology

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

      Service Location Protocol (SLP)

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







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


      SLP framework

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

      Directory Agent (DA)

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

      User Agent (UA)

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

      Service Agent (SA)

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

      SA Server

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

      Service Advertisement

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

      Locale

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



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


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

      Service Template

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

      The service:  URL

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

      Service Attributes

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

      Scope

         A string used to control the availability of service
         advertisements.  Every SLP Agent is configured with one or more
         scope strings.  Scopes are assigned by site administrators to