Service Location Working Group Erik Guttman INTERNET DRAFT James Kempf Sun Microsystems Don Provan 30 November 1997 Novell, Inc. An API for Service Location draft-ietf-svrloc-api-02.txt Status of This Memo This document is a submission by the Service Location Working Group of the Internet Engineering Task Force (IETF). Comments should be submitted to the srvloc@corp.home.net mailing list. Distribution of this memo is unlimited. This document is an Internet-Draft. 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.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (North Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). 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 communication with network administrators prior to use. This document describes standardized API's for SLP in C and Java. The API's are modular and are designed to allow implementions to offer just the feature set needed. In addition, a standardized configuration file format and a format for proxy registrations is defined. The configuration file format allows SLP agents to set network and other parameters in a portable way. The proxy file format allows legacy services to be registered with SLP directory Guttman, Kempf, Provan Expires 31 May 1998 [Page i] Internet Draft Service Location API 30 November 1997 agents in cases where modifying the legacy service program code is difficult or impossible. Guttman, Kempf, Provan Expires 31 May 1998 [Page ii] Internet Draft Service Location API 30 November 1997 Contents Status of This Memo i Abstract i 1. Introduction 1 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. File Formats 5 2.1. Configuration File Format . . . . . . . . . . . . . . . . 5 2.1.1. DA configuration . . . . . . . . . . . . . . . . 6 2.1.2. UA and SA Static Configuration . . . . . . . . . 6 2.1.3. Tracing and Logging . . . . . . . . . . . . . . . 7 2.1.4. Proxy Registration . . . . . . . . . . . . . . . 7 2.1.5. Networking Configuration Parameters . . . . . . . 8 2.1.6. Default Header Information . . . . . . . . . . . 9 2.1.7. Security . . . . . . . . . . . . . . . . . . . . 9 2.2. Proxy Registration File . . . . . . . . . . . . . . . . . 10 2.3. Proccessing Proxy and Configuration Files . . . . . . . . 10 3. Binding Independent Implementation Considerations 10 3.1. Multithreading . . . . . . . . . . . . . . . . . . . . . 11 3.2. Type Checking for Service Types . . . . . . . . . . . . . 11 3.3. Refreshing Registrations . . . . . . . . . . . . . . . . 11 3.4. Configuration File Processing . . . . . . . . . . . . . . 11 3.5. Attribute Types . . . . . . . . . . . . . . . . . . . . . 12 3.6. Removal of Duplicates . . . . . . . . . . . . . . . . . . 12 3.7. SA Implementation . . . . . . . . . . . . . . . . . . . . 12 4. C Language Binding 13 4.1. Constant Types . . . . . . . . . . . . . . . . . . . . . 13 4.1.1. URL Lifetimes . . . . . . . . . . . . . . . . . . 13 4.1.2. Error Codes . . . . . . . . . . . . . . . . . . . 13 4.2. Struct Types . . . . . . . . . . . . . . . . . . . . . . 16 4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . . . 16 4.2.2. SLPConn . . . . . . . . . . . . . . . . . . . . . 17 4.2.3. SLPConn . . . . . . . . . . . . . . . . . . . . . 17 4.3. Opening and Closing a Connection . . . . . . . . . . . . 17 4.3.1. SLPOpen . . . . . . . . . . . . . . . . . . . . . 17 4.3.2. SLPClose . . . . . . . . . . . . . . . . . . . . 18 4.4. Protocol API . . . . . . . . . . . . . . . . . . . . . . 18 4.4.1. SLPReg . . . . . . . . . . . . . . . . . . . . . 18 4.4.2. SLPDereg . . . . . . . . . . . . . . . . . . . . 19 Guttman, Kempf, Provan Expires 31 May 1998 [Page iii] Internet Draft Service Location API 30 November 1997 4.4.3. SLPFindSrvTypes . . . . . . . . . . . . . . . . . 20 4.4.4. SLPFindSrvs . . . . . . . . . . . . . . . . . . . 22 4.4.5. SLPFindAttrs . . . . . . . . . . . . . . . . . . 23 4.5. Miscellaneous Functions . . . . . . . . . . . . . . . . . 25 4.6. SLPFindScopes . . . . . . . . . . . . . . . . . . . . . . 25 4.7. SLPFree . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.7.1. SLPOpaqueToRadix64 . . . . . . . . . . . . . . . 26 4.7.2. SLPRadix64ToOpaque . . . . . . . . . . . . . . . 27 4.7.3. SLPEscape . . . . . . . . . . . . . . . . . . . . 28 4.7.4. SLPUnescape . . . . . . . . . . . . . . . . . . . 29 4.7.5. SLPGetProperty . . . . . . . . . . . . . . . . . 30 4.7.6. SLPSetProperty . . . . . . . . . . . . . . . . . 30 4.8. Implementation Notes . . . . . . . . . . . . . . . . . . 31 4.8.1. Initialization . . . . . . . . . . . . . . . . . 31 4.8.2. Multithreading . . . . . . . . . . . . . . . . . 31 4.8.3. Syntax for String Parameters . . . . . . . . . . 31 4.8.4. Client Side Syntax Checking . . . . . . . . . . . 32 4.8.5. Character Set Encoding . . . . . . . . . . . . . 32 4.8.6. System Properties . . . . . . . . . . . . . . . . 32 4.8.7. Registration and the Fresh Flag . . . . . . . . . 32 4.8.8. Memory Management . . . . . . . . . . . . . . . . 33 4.9. Examples . . . . . . . . . . . . . . . . . . . . . . . . 33 5. Java Language Binding 35 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 35 5.2. Basic Data Structures . . . . . . . . . . . . . . . . . . 36 5.2.1. Class ServiceLocationAttribute . . . . . . . . . 36 5.2.2. Class ServiceURL . . . . . . . . . . . . . . . . 38 5.3. SLP Access Interfaces . . . . . . . . . . . . . . . . . . 44 5.3.1. Interface Advertiser . . . . . . . . . . . . . . 44 5.3.2. Interface Locator . . . . . . . . . . . . . . . . 49 5.3.3. Interface TemplateRegistry . . . . . . . . . . . 54 5.4. The Service Location Manager . . . . . . . . . . . . . . 57 5.4.1. Class ServiceLocationManager . . . . . . . . . . 57 5.5. Service Type Template Introspection . . . . . . . . . . . 59 5.5.1. Interface ServiceLocationAttributeVerifier . . . 59 5.5.2. Interface ServiceLocationAttributeDescriptor . . 62 5.6. Exceptions . . . . . . . . . . . . . . . . . . . . . . . 64 5.6.1. Class ServiceLocationException . . . . . . . . . 64 5.6.2. Class ServiceLocationAuthenticationException . . 65 5.6.3. Class ServiceLocationCharsetNotUnderstoodException 65 5.6.4. Class ServiceLocationLanguageNotSupportedException 65 5.6.5. Class ServiceLocationScopeNotSupportedException . 66 5.6.6. Class ServiceLocationParseException . . . . . . . 66 5.6.7. Class ServiceLocationInvalidRegistrationException 67 5.6.8. Class ServiceLocationInternalSystemException . . 67 5.6.9. Class ServiceLocationInternalNetException . . . . 67 5.6.10. Class ServiceLocationInitNetException . . . . . . 68 5.7. Implementation Notes . . . . . . . . . . . . . . . . . . 68 Guttman, Kempf, Provan Expires 31 May 1998 [Page iv] Internet Draft Service Location API 30 November 1997 5.7.1. Client Side Syntax Checking . . . . . . . . . . . 68 5.7.2. Character Set Encoding . . . . . . . . . . . . . 68 5.7.3. Language Locale Handling . . . . . . . . . . . . 69 5.7.4. Setting SLP System Properties . . . . . . . . . . 69 5.7.5. Implementing register() and addAttributes() . . . 69 5.7.6. Exceptions . . . . . . . . . . . . . . . . . . . 70 5.7.7. Multithreading . . . . . . . . . . . . . . . . . 70 5.7.8. Return of Unscoped Services . . . . . . . . . . . 71 5.7.9. Modular Implementations . . . . . . . . . . . . . 71 5.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 72 6. Internationalization Considerations 75 6.1. service: URL . . . . . . . . . . . . . . . . . . . . . . 75 6.2. Character Set Identification and Use . . . . . . . . . . 75 7. Security Considerations 76 1. Introduction The Service Location API is designed to be a standardized way to programmatically access the Service Location Protocol (SLP). The API's 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, a standardized format for configuration files and for proxy registration files is presented. These files allow SLP agents to configure network parameters and to register legacy services that have not been SLP enabled. 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 standardized configuration file and proxy file formats are the following: Simple Syntax The configuration and proxy file formats are designed to be simple, and easily parsable, but nevertheless, readable by humans. Guttman, Kempf, Provan Expires 31 May 1998 [Page 1] Internet Draft Service Location API 30 November 1997 Complete Coverage The individual properties specified in the configuration file format are designed to give complete coverage of all interesting SLP, basic network, and other parameters that might be of interest to a system administrator. Securely Support Security SLP's security requirements are supported by the configuration file, but security information that should remain strictly private, such as private keys, is left out. The individual goals of the C and Java bindings are somewhat different. For the C binding, the goals are: Minimal but Complete The C binding is designed to provide a minimal but complete implementation of SLP. While the C binding does provide complete support for the base SLP protocol, support for additional features, such as service type templates [11], has not been specified. Simple Memory Management The C binding is designed to have simple, transparent memory management. Dynamic memory requirements are kept limited to facilitate small memory or ROMable implementations. Simple Data Structures The protocol makes extensive use of strings, and this is reflected in the C binding. The data structures are easy to keep track of and do not require extensive dynamic allocation. In addition, the API should be implementable on 16 bit microcontrollers. Limited Code Size The C binding is designed so that the size of the resulting object code is minimized. The goals of the Java binding are: Modular Implementation In addition to complete access to the protocol, the Java binding is designed to provide access to additional features, Guttman, Kempf, Provan Expires 31 May 1998 [Page 2] Internet Draft Service Location API 30 November 1997 such as service type templates. The design is organized such that subsets for small memory or ROMable implementations can leave off those features that are not of interest. Reflect SLP Entities as Objects The Java binding reflects the important entities in SLP (service: URL's, attributes, etc.) as objects. The result is an object-oriented API rather than a string-based one, as is appropriate for Java's language emphasis. Flexible Data Types The Java binding data types are designed for flexible access. For example, Vector objects are used consistently across the API instead of arrays of objects because adding and removing elements is considerably simpler. Modular Memory Requirments The Java binding allows various subsets to be dynamically linked, so the API implementation only requires as much memory as the feature set used by the client or service program. 1.2. Terminology Service Location Protocol (SLP) The underlying protocol allowing dynamic and scalable service discovery. This protocol is specified in the Service Location Protocol [5]. SLP framework When a 'Service Location framework' is mentioned, it refers to both the SLP implementation and interface implementation; ie. whatever provides the SLP functionality to user level programs. Directory Agent (DA) A service which automatically gathers service advertisements from SAs in order to provide them to UAs. User Agent (UA) This is the Service Location process or library which allows SLP requests to be made on behalf of a client process. UAs Guttman, Kempf, Provan Expires 31 May 1998 [Page 3] Internet Draft Service Location API 30 November 1997 direct requests to DAs when they exist automatically. In their absense, UAs make requests directly from SAs. Service Agent (SA) This is the Service Location process or library which allows service software to register and deregister itself with the SLP framework. The SA SHOULD also respond to UA requests directly in the absense of DAs. Service Advertisement A service: URL possibly combined with service attributes. These are distributed by the SLP framework to Directory Agents. Service Type Template A document which describes the syntax of the service: URL for a given service type, the protocol the client will use to make use of the service and a definition of all service attributes: the meaning, defaults, constraints of each value the attributes can take on. See [11] for more information o service type templates. Each service type is identified by a string (usually the same name as the protocol used to deliver the service). The service: URL A service of a particular type announces its availability with a service: URL which includes its service access point (domain name and possibly its port number) and optionally basic configuration parameters. The syntax of the service: URL is defined in the service type template. Service Attributes The attributes associated with a given service. The values that can be assigned to service attributes are defined by the service type template. Scope A string used to control the availability of service advertisements. Scopes are assigned by site administrators to group services for many purposes, but chiefly as a means of scalability. DAs assigned a scope will store only services advertised with the same scope value. UAs SHOULD use a scope string in requests whenever possible. Guttman, Kempf, Provan Expires 31 May 1998 [Page 4] Internet Draft Service Location API 30 November 1997 Naming Authority (NA) This is a 'suffix' to the service type string. It completely changes the meaning of the service type. NAs are used for private definitions of well known Service Types and experimental Service Type extensions. The default NA is "IANA", which may be omitted. Service types with the IANA naming authority are registered with the Internet Assigned Numbers Authority (see [11] for more information on the registration procedure). 2. File Formats This section describes the configuration and proxy registration file formats. Both files are defined in the ASCII character set [1]. 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 grammer in ABNF [3] syntax is: config-file = line-list line-list = line line line-list line = property-line comment-line comment-line = ( "#" ";" ) 1*allchar newline property-line = property newline property-def = property "=" value property = prop | prop "." property prop = 1*char value = integer / boolean / vector / string integer = 1*digit digit = "0" / "1" / "2" / "3" / "4" / "5" "6" / "7" / "8" / "9" boolean = "true" / "false" newline = CR / ( CR LF ) vector = "[" value-list "]" value-list = value / value "," value-list string = 1*char char = digit | alpha | other Guttman, Kempf, Provan Expires 31 May 1998 [Page 5] Internet Draft Service Location API 30 November 1997 alpha = ;Any ASCII alpha character, A-Z, a-z other = ;All printable ASCII characters ; other than alpha and digit, with ; the exception of tab, space and ; newline. allchar = char | tab | space The properties break down into seven general areas. Each of the following subsections describes an area and its properties. 2.1.1. DA configuration Important configuration parameters for DA's are included in this section. These are: net.slp.isDA A boolean indicating if SLP is to act as a DA. If false, not run as a DA. Default is false. net.slp.DAScopes A vector of strings giving scope names for the DA. If absent, the DA is unscoped. Ignored if isDA is false. Default is unscoped. net.slp.DAHeartBeat A 64 bit integer giving the number of milliseconds for the DA heartbeat. Default is 3 hours (10800000 milliseconds). Ignored if isDA is false. net.slp.isDAStateful A boolean indicating if the DA will start stateful. Ignored if isDA is false. Default is false. 2.1.2. UA and SA Static Configuration This property gives the DA addresses that statically configured UA's and SA's should use. net.slp.DAAddresses A vector of IP addresses or DNS-resolvable names giving the DA's to use for statically configured UA's and SA's, along Guttman, Kempf, Provan Expires 31 May 1998 [Page 6] Internet Draft Service Location API 30 November 1997 with their scopes. Ignored if isDA is true. Default is none. Addresses obtained via DHCP take precedence over these. Scoped DAs are listed with a comma delimited list inside brackets following the DA address. For example: da1.freeb.org, da2.freeb.org[scope1,scope2], da3.freeb.org[scope3] Here da1 has no scope, da 2 has scope1 and scope2, da3 has only scope3. 2.1.3. Tracing and Logging This section allows tracing and logging information to be printed by the various agents. net.slp.traceDATraffic A boolean controlling printing of messges about traffic with DA's. Default is false. net.slp.traceReg A boolean controlling printing of messages upon registration and deregistration, including the dumping of registration records of all existing registrations. Default is false. net.slp.traceDrop A boolean controlling printing of a message when a registration is dropped for any reason. Default is false. 2.1.4. Proxy Registration This property indicates where the proxy registration document is located. net.slp.proxyURL A string containing a URL pointing to a document containing proxy registrations that should be done when the DA or SA starts up. Default is none. Guttman, Kempf, Provan Expires 31 May 1998 [Page 7] Internet Draft Service Location API 30 November 1997 2.1.5. Networking Configuration Parameters The properties in this section allow various network configuration parameters to be set. net.slp.isBroadcastOnly A boolean indicating if use broadcast should be used instead of multicast. Default is false. net.slp.multicastRadius A positive integer less than or equal to 32, giving the multicast radius. Default is 32. net.slp.TCPTimeout A 16 bit integer giving the timeout on all TCP connections, in milliseconds. Default is 1500 (1.5 seconds). net.slp.maxWait A 32 bit integer giving the timeout in milliseconds on all requests. Default is 90000 ms. Settings should be in increments of 500 ms. net.slp.multicastTimeouts A vector of 16 bit integers used as timeouts, in milliseconds, to implement the multicast convergence alorithm. Ignored if isDA is true. Default is: [ 500, 1000, 1500 ]. net.slp.passiveDADetection A boolean indicating that DA discovery should be passive. Ignored if isDA is true. Default is true. net.slp.DADiscoveryTimeout A 16 bit integer indicating the timeout, in milliseconds, for active DA discovery. Ignored if isDA or passiveDADetection is true. Default is 2000 (2 seconds). net.slp.MTU A 16 bit integer giving the network packet MTU, in bytes. Default is 1400. Guttman, Kempf, Provan Expires 31 May 1998 [Page 8] Internet Draft Service Location API 30 November 1997 net.slp.multicastInterfaces Vector of strings giving the names of network interfaces on which a DA or SA should listen for multicast. Default is empty, i.e. just listen on the main network interface. 2.1.6. Default Header Information This section contains defaults for the various SLP header fields. net.slp.isMonolingual A boolean indicating whether the monolingual flag should be set. Default is true. net.slp.locale A two character ISO-639 [10] language code for the language locale. Default is "en". Setting this property causes the property value to become the default locale for SLP messages. net.slp.characterEncoding A string giving the the official name of the IANA character set encoding. Default is "US-ASCII". net.slp.maximumResults A 16 bit integer giving the maximum number of results to return for a request. Positive integers and -1 are legal values. If -1, indicates that all results should be returned. 2.1.7. Security The properties in this section allow security parameters to be configured. net.slp.publicKey A radix-64 [12] public key for DA's and UA's. If present, indicates that URL and attribute authentication should be used. net.slp.cryptoalgorithm A string indicating the cryptoalgorthm to use for authenticating URL's and attributes. The default is "md5WithRSAEncryption". Ignored if publicKey is absent. Guttman, Kempf, Provan Expires 31 May 1998 [Page 9] Internet Draft Service Location API 30 November 1997 2.2. Proxy Registration File The proxy registration file contains a group of registrations which a DA or SA server (if one exists) registers when it starts up. These registrations are primarily for older service programs that do not internally support SLP and cannot be converted. The syntax of the proxy registration file, in ABNF format [3], is as follows: proxy-file = proxy-reg-list proxy-reg-list= proxy-reg proxy-reg proxy-reg-list proxy-reg = url-props attr-list newline url-props = service-url ,lifetime `,lang service-url = ;The registration's service: URL. See ; [11] for syntax. lifetime = ;Positive integer <= 65536 language = ;Two character ISO-639 language code, ; see [10]. attr-list = attr-id =attr-val-list newline attr = ;Attribute id, see [11] ; for syntax. attr-val-list = attr-val attr-val ,attr-val-list attr-val = ;Attribute value, see [11] ; for syntax. newline = CR / ( CR LF ) 2.3. Proccessing Proxy and Configuration Files Implementations are encouraged to make processing of configuration and proxy files as transparent as possible to clients of the API. At the latest, errors must be caught when the relevent configuration or proxy registration file item is used. At the earliest, errors may be caught when the relevent file is loaded into the executing agent. Errors should be reported by logging to the appropriate platform logging file, error output, or log device, and the default value substituted. Configuration file loading must be complete prior to the initiation of the first networking connection. Proxy registration may occur at any point before the DA accepts the first network request. 3. Binding Independent Implementation Considerations This section discusses a number of implementation considerations independent of language binding, with language specific notes where applicable. Guttman, Kempf, Provan Expires 31 May 1998 [Page 10] Internet Draft Service Location API 30 November 1997 3.1. Multithreading Implementations of both the C and Java API's are required to make API calls thread-safe. This means that access to data structures shared between threads must be co-ordinated to avoid corruption or invalid access. One way to achieve this goal is to allow only one thread at a time in the implementing library. Performance in such an implementation will suffer, however. Therefore, where possible, implementations are encouraged to make access thread-hot, allowing multiple threads within the SLP API library. 3.2. Type Checking for Service Types Service type templates [11] allow SLP registrations to be type checked for correctness. Implementations of the API are free to make use of service type information for type checking, but are not required to do so. 3.3. Refreshing Registrations SLP advertisements carry an explicit lifetime with them. After the lifetime expires, the DA flushes the registration from it's cache. Implementations of the SA API are encouraged to provide an automatic refreshing capability, so that service advertiser applications can simply register their services for as long as they continue running. The SA API is required to deregister any such advertisements as soon as the calling application exits. If the underlying platform does not support multithreading, implementing automatic refreshing may be difficult. 3.4. Configuration File Processing DA's, SA's and UA's processing the configuration file, and DA's processing the proxy registration file are required to log any errors using whatever underlying error mechanism is appropriate for the platform. Examples include include writing error messages to the standard output, writing to a system logging device, or displaying the errors to a logging window. After the error is reported, the offending parameter must be set to the default and program execution continued. In no case should the agent break off processing, abort the program, or throw an exception if a file format error occurs. Guttman, Kempf, Provan Expires 31 May 1998 [Page 11] Internet Draft Service Location API 30 November 1997 3.5. Attribute Types Because SLP is a string protocol, attribute values have no type information on the wire. All UA implementations and those SA and DA implementations that choose to support type checking should use the type rules described in [11] in order to convert from the on the wire string representation to an object typed appropriately in the language of implementation. 3.6. Removal of Duplicates The UA implementation should always collate results to remove duplicates. This is especially important for the results of the SLP find attributes request for a service type and the find service type request when there are no DA's. The request will be multicast to all SA's, and the results will no doubt include duplicate values. 3.7. SA Implementation An SA implementation requires as a minimum that service advertisements be registered with a DA. They SHOULD be able to respond to UA queries directly in the absense of a DA. If the latter feature is implemented, the SA will run on the same host, and need some way to service UA requests on behalf of all the host's services. This SA must listen for TCP requests. Since only one process per host may be bound to a particular TCP port, the SA process will have to be a shared resource and communicate with the different service processes using some form of interprocess communication, as an SA server. There is a subtle bending of the semantics of Service Location if a SA and DA are collocated on the same host. On some socket based implementations of IP multicast, the following occurs: Two sockets are bound to the same UDP port. One of the sockets has joined a multicast group, the other hasn't. A multicast datagram arriving for that multicast group, for the port in question, is delivered to BOTH sockets. Suppose a DA is listening for unicast datagrams on the SLP port, while the SA is listening for multicast packets on the same port. A multicast datagram arrives for the SA, but is delivered to the DA as well. In the worst case, BOTH respond. This will possibly supply redundant information (if the SA services are registered with the DA.) Worse, the DA may reply with information which it 'shouldn't.' None of this is very serious, because the worst that can happen is the UA will receive more information than it would have otherwise. The UA will only receive correct information in any case; it MUST satisfy the UAs request or it won't be returned. Guttman, Kempf, Provan Expires 31 May 1998 [Page 12] Internet Draft Service Location API 30 November 1997 4. C Language Binding The C language binding presents a minimal overhead implemention that maps directly into the protocol. There is one C language function per protocol request, with the exception of the SLPDereg() and SLPDelAttrs() functions, which map into different uses of the SLP deregister request. Parameters are string values or arrays of simple struct's, and memory management is kept simple by requiring the user to supply memory where possible, and having an explicit SLPFree() function where the appearance of differently sized data structures from the network make user-supplied memory impossible. The return value from each function is a long. If the function returned successfully, then the value contains the number of returned items, the size of the dynamically allocated buffer returned, etc. If an error occured, the return value is a negative integer error code. If the no values were returned, then the return value is zero. Clients can differentiate between errors and successful returns by checking whether the return value is negative or positive. 4.1. Constant Types 4.1.1. URL Lifetimes 4.1.1.1. Synopsis typedef enum { SLP_LIFETIME_NONE = 0, SLP_LIFETIME_DEFAULT = 108000, SLP_LIFETIME_PERMANENT = -1 } SLPURLLifetime; 4.1.1.2. Description The SLPURLLifetime enum type contains URL lifetime values that are frequently used. The SLP_LIFETIME_DEFAULT value corresponds to the CONFIG_INTERVAL_1 in [5]. 4.1.2. Error Codes 4.1.2.1. Synopsis typedef enum { Guttman, Kempf, Provan Expires 31 May 1998 [Page 13] Internet Draft Service Location API 30 November 1997 SLP_OK = 0, SLP_LANG_NOT_SUPPORTED = -1, SLP_PROTOCOL_PARSE_ERR = -2, SLP_INVALID_REGISTRATION = -3, SLP_SCOPE_NOT_SUPPORTED = -4, SLP_CHARSET_NOT_UNDERSTOOD = -5, SLP_AUTHENTICATION_INVALID = -6, SLP_AUTHENTICATION_FAILED = -7, SLP_BUFFER_OVERFLOW = -9, SLP_REQUEST_TIMED_OUT = -10, SLP_COULD_NOT_INIT_NET_RESOURCES = -11, SLP_COULD_NOT_ALLOCATE_MEMORY = -12, SLP_PARAMETER_BAD = -13, SLP_INTERNAL_NET_ERROR = -14, SLP_INTERNAL_SYSTEM_ERROR = -15 } SLPError ; 4.1.2.2. Description The SLPError enum contains error codes that are returned from API functions. The SLP protocol will only return an error code when an operation fails completely. The following errors report SLP protocol problems. The problem could be in the data supplied by the application or in the interaction of the local SLP implementation with a remote agent. In the latter case, the error can only be taken as a hint. Different remote agents may have returned several different errors. SLP might pick one to return to the operation, but it cannot guarantee that's the primary cause of the failure. SLP_LANG_NOT_SUPPORTED No DA or SA has service advertisement information in the language requested, but at least one DA or SA indicated, via the LANGUAGE_NOT_SUPPORTED error code, that it might have information for that service in another language. SLP_PROTOCOL_PARSE_ERR The SLP message was rejected by a remote SLP entity. The API returns this error only when no information was retrieved, and at least one SA or DA indicated a protocol error. This suggests an implementation error in either the local implementation or some other SLP implementation on the network. It can also be caused by damage to the packet in the network. Guttman, Kempf, Provan Expires 31 May 1998 [Page 14] Internet Draft Service Location API 30 November 1997 SLP_INVALID_REGISTRATION The API may return this error if an attempt to register a service was rejected by all DAs because of a malformed URL or attributes. SLP will not return the error if at least one DA accepted the registration. SLP_SCOPE_NOT_SUPPORTED The API may return this error code if the indicated scope is not known. For example, if a DA is configured to allow only particular scopes, a request using a scope not in that list would result in this error. SLP_CHARSET_NOT_UNDERSTOOD The API returns this error code if it does not understand the indicated character set, or if the operation fails because no DA or SA understands the character set, and the request cannot be converted into a more common character set such as ASCII. SLP_AUTHENTICATION_INVALID If the SLP framework supports authentication, this error will arise when a remote DA fails to accept a registration. This error will not occur if a UA rejects a reply to a request: The UA will simply silently discard (and possibly log) the rejected reply. The following errors are generated through a program interacting with the API and SLP implementation. The operation failed. SLP_NOT_SUPPORTED_YET If a particular feature is used that is not implemented in the API, this error is returned. SLP_REQUEST_TIMED_OUT When no reply can be obtained in the time specified by the configured timeout interval, this error is returned instead. SLP_COULD_NOT_INIT_NET_RESOURCES If the SLP framework cannot initialize properly, this error will be returned. Guttman, Kempf, Provan Expires 31 May 1998 [Page 15] Internet Draft Service Location API 30 November 1997 SLP_COULD_NOT_ALLOCATE_MEMORY If the API fails to allocate memory, the operation is aborted and returns this. SLP_PARAMETER_BAD If a parameter passed into an interface is bad, this error is returned. SLP_INTERNAL_NET_ERROR The failure of networking during normal operations causes this error to be returned. SLP_INTERNAL_SYSTEM_ERROR A basic failure of the API causes this error to be returned. This occurs when a system call or library fails. The operation could not recover. 4.2. Struct Types 4.2.1. SLPSrvURL 4.2.1.1. Synopsis typedef struct srvurl { char *s_pcURL; long s_lifetime; } SLPSrvURL; 4.2.1.2. Description Arrays of SLPSrvURL structs are passed to the SLPReg() function to register services and to the SLPFindSrvs() function to hold services returned from a query. The values of s_lifetime are restricted to 1 to 65535 and indicate the number of seconds that the advertisment should remain valid. Guttman, Kempf, Provan Expires 31 May 1998 [Page 16] Internet Draft Service Location API 30 November 1997 4.2.2. SLPConn 4.2.2.1. Synopsis typedef void* SLPConn; The SLPConn type is returned by SLPOpen() and is a parameter to all SLP functions. It serves as a handle for the SLP connection. The type is opaque, since the exact nature differs depending on the implementation. 4.2.3. SLPConn 4.2.3.1. Synopsis typedef unsigned char* SLPOpaque; The SLPOpaque type models the SLP OPAQUE attribute value type. Opaques are converted to strings for transmission across the wire, but can be used to model any other type. 4.3. Opening and Closing a Connection 4.3.1. SLPOpen 4.3.1.1. Synopsis SLPConn SLPOpen(const char *pcLang); 4.3.1.2. Description Returns a SLPConn handle for the language locale passed in as a parameter. The handle encapsulates the language locale for SLP requests issued through the handle, and any other resources required by the implementation. If an error occurs, returns NULL. Guttman, Kempf, Provan Expires 31 May 1998 [Page 17] Internet Draft Service Location API 30 November 1997 4.3.1.3. Parameters pcLang A pointer to an array of characters containing the two character ISO-639 [10] code for the natural language locale of requests issued on the handle. May not be NULL. 4.3.2. SLPClose 4.3.2.1. Synopsis void SLPClose(SLPConn conn); 4.3.2.2. Description Closes the SLP connection on the handle, and frees all resources associated with the handle. If the handle was invalid, the function returns silently. Ignored if NULL. 4.3.2.3. Parameters SLPConn A SLPConn connection handle returned from a call to SLPOpen(). 4.4. Protocol API 4.4.1. SLPReg 4.4.1.1. Synopsis long SLPReg(SLPConn conn, SLPSrvURL *pURL, const char *pcAttrs); 4.4.1.2. Description Registers the service: URL in the pURL struct with the attribute list in pcAttr. A call to SLPReg() with a URL that has already Guttman, Kempf, Provan Expires 31 May 1998 [Page 18] Internet Draft Service Location API 30 November 1997 been registered in the language locale of the handle adds the new values to attributes previously registered, if the update contains attributes having the same id. Boolean attributes are merged using logical ``and'', as they cannot be multivalued. Attributes with new id's are added to the attribute set for the advertisement in the language locale of the registration. An attribute with the id "scope" is handled differently. It determines the scope or scopes of the registration. DA's can be configured to only accept registrations from particular scopes. If the scope attribute of the registration does not match the scope of the available DA's, then a SLP_SCOPE_NOT_SUPPORTED error is returned. If no scope attribute is given, the advertisement is registered unscoped. 4.4.1.3. Parameters conn The language specific connection on which to register the advertisement. May not be NULL. pURL The service: URL to register. May not be NULL. pcAttrs A comma separated list of attribute assignment expressions for the attributes of the advertisement. See Section 9. in [5] for a description of the list format. May not be NULL. Use empty string, "" for no attributes. 4.4.1.4. Returns If no error occurs and the registration is a new registration, the return value is 1. If the registration is an update, the return value is 0. Otherwise, if an error occurs, one of the SLPError codes is returned. 4.4.2. SLPDereg 4.4.2.1. Synopsys long SLPDereg(SLPConn conn, Guttman, Kempf, Provan Expires 31 May 1998 [Page 19] Internet Draft Service Location API 30 November 1997 SLPSrvURL *pURL, const char *pcAttrs); 4.4.2.2. Description If pcAttrs is NULL, deregisters the advertisment for service: URL pURL in all language locales, not just the locale of the connection. If pcAttrs is not NULL, then only delete the selected attributes in the locale of the connection. 4.4.2.3. Parameters conn The language specific connection on which to delete attributes, or to use for deregistering. May not be NULL. pURL The service: URL to deregister or delete attributes from. May not be NULL. pcAttrs A comma separated list of attribute id's for the attributes to deregister. See Section 9. in [5] for a description of the list format. If NULL, then the advertisment is deregistered. 4.4.2.4. Returns If no error occurs, the return value is 0. Otherwise, if an error occurs, one of the SLPError codes is returned. 4.4.3. SLPFindSrvTypes 4.4.3.1. Synopsis long SLPFindSrvTypes(SLPConn conn, const char* pcNamingAuthority, const char* pcScope, char** ppcSrvTypes, long lSize); Guttman, Kempf, Provan Expires 31 May 1998 [Page 20] Internet Draft Service Location API 30 November 1997 The SLPSrvType() function issues an SLP service type request and returns the result as an array of pointers to char in ppcSrvTypes. The lSize parameter indicates the size of the ppcSrvTypes array. The service types are returned independent of language locale, but only for the scope passed as pcScope and for the indicated naming authority. If the naming authority is "*", then results are returned for all naming authorities. If the naming authority is the empty string, i.e. "", then the default naming authority, "IANA", is used. If pcScope is NULL, then only those advertisements having no scope attribute are searched. The service type names are returned with the naming authority included, i.e. as: service-type "." naming-authority 4.4.3.2. Parameters conn The connection on which to search for types. May not be NULL. pcNamingAuthority The naming authority to search. Use "*" for all naming authorities and the empty string, "", for the default naming authority. May not be NULL. pcScope A pointer to a char containing the name of the scope attribute advertisements to search are required to have. May not be NULL. Use empty string, "", to indicate that the advertisements to search have no scope attribute. ppcSrvTypes A pointer to an array of char* in which the returned scope strings are placed. The service type strings themselves should be deallocated using SLPFree() when no longer needed. If the number of strings is less than the lSize parameter, the array element after the last string is NULL. May not be NULL. lSize The number of array items in the ppcSrvTypes array. Guttman, Kempf, Provan Expires 31 May 1998 [Page 21] Internet Draft Service Location API 30 November 1997 4.4.3.3. Returns If no error occurs, the return value is the number of returned strings in ppcSrvTypes. Otherwise, if an error occurs, one of the SLPError codes is returned. If the ppcSrvTypes array does not contain enough storage for all the returned strings, the return value is SLP_PARAMETER_BAD, but the array contents are usable. 4.4.4. SLPFindSrvs 4.4.4.1. Synopsis long SLPFindSrvs(SLPConn conn, const char* pcQuery, SLPSrvURL* pSrvURL, long lSize); 4.4.4.2. Description Issue the query for services on the language specific connection and return the results in paSrvURL. The exact format of pcQuery is described in Section 5.0 of [5]. The pcQuery string includes three parts: Service Type The service type can be discovered using SLPSrvTypes(). Scope The scope can be discovered using SLPFindScopes(). Note that even if a scope is given, the result will also return services that are unscoped, due to a peculiarity in SLP scope semantics (see [5]). Query The query is formulated of attribute pattern matching expressions in either a prefix or comma-separated list format. The exact syntax of the query is described in Sections 5.3, 5.4, and 5.5 of [5]. Guttman, Kempf, Provan Expires 31 May 1998 [Page 22] Internet Draft Service Location API 30 November 1997 4.4.4.3. Parameters conn The language specific connection on which to search for services. May not be NULL. pcQuery The query string to use. May not be NULL. pSrvURL A pointer to an array of SLPSrvURL structs in which the returned service: URL's are placed. The SLPSrvURL s_pcURL strings should be deallocated using SLPFree() when no longer needed. If the number of array elements is less than the lSize parameter, the s_pcURL field of the array element after the last string is NULL. May not be NULL. lSize The number of array items in the pSrvURL array. 4.4.4.4. Returns If no error occurs, the return value is the number of returned array items in pSrvURL. Otherwise, if an error occurs, one of the SLPError codes is returned. If the pSrvURL array does not contain enough storage for all the returned strings, the return value is SLP_PARAMETER_BAD, but the array contents are usable. 4.4.5. SLPFindAttrs 4.4.5.1. Synopsis long SLPFindAttrs(SLPConn conn, const char* pcURL, const char* pcScope, const char* pcAttrIds, char* pcAttrs, long lSize); Guttman, Kempf, Provan Expires 31 May 1998 [Page 23] Internet Draft Service Location API 30 November 1997 4.4.5.2. Description Return service attributes matching the attribute id's for the indicated full or partial URL. If pcURL is a complete service: URL, the attribute information returned is for that particular service in the language locale of the connection. If pcURL is a partial URL, then all attributes for the service type are returned regardless of the language of registration. The syntax for a partial URL string is given in Section 12 of [5]. The result is filtered with an SLP attribute request filter string parameter, the syntax of which is described in Section 12 of [5]. If the filter string is the empty string, i.e. "", all attributes are returned. 4.4.5.3. Parameters conn The language specific connection on which to search for attributes. May not be NULL. pcURL The full or partial URL. See Section 12 of [5] for partial URL syntax. May not be NULL. pcScope The scope name. Use empty string, "", to indicate an unscoped request. May not be NULL. pcAttrIds The filter string indicating which attribute values to return. Use empty string, "", to indicate all values. Wildcards matching all attribute id's having a particular prefix or suffix are also possible. See Section 12 of [5] for the exact format of the filter string. May not be NULL. pcAttrs A pointer to a buffer of char where the character string containing a comma separated list of attribute assignment expressions for the return is put. May not be NULL. Guttman, Kempf, Provan Expires 31 May 1998 [Page 24] Internet Draft Service Location API 30 November 1997 lSize The number of array items in the pcAttrs array. 4.4.5.4. Returns If no error occurs, the return value is the number of characters in pcAttrs. Otherwise, if an error occurs, one of the SLPError codes is returned. If the pcAttrs array does not contain enough storage for all the returned attributes, the return value is SLP_PARAMETER_BAD. 4.5. Miscellaneous Functions 4.6. SLPFindScopes 4.6.0.5. Synopsis void SLPFindScopes(SLPConn conn, char** ppcScopes, long lSize); 4.6.0.6. Description Returns an array of strings with all available scope values. The list of scopes could be configured manually, determined with DHCP, or built from the DA discovery process. If there is any order to the scopes, preferred scopes are listed before less desirable scopes. There will always be at least one string in the array, the empty string, "", indicating unscoped. 4.6.0.7. Parameters conn The connection on which to search for scopes. May not be NULL. ppcScopes An array of pointers to char supplied by the caller to hold the results. If the number of strings is less than the lSize parameter, the array element after the last string is NULL. The strings should be freed using SLPFree() when no longer needed. May not be NULL. Guttman, Kempf, Provan Expires 31 May 1998 [Page 25] Internet Draft Service Location API 30 November 1997 lSize The number of array items in the ppcScopes array. 4.6.0.8. Returns If no error occurs, the return value is the number of characters in strings in the ppcScopes array. Otherwise, if an error occurs, one of the SLPError codes is returned. If the ppcScopes array does not contain enough storage for all the returned attributes, the return value is SLP_PARAMETER_BAD, but the array contents are usable. 4.7. SLPFree 4.7.0.9. Synopsis void SLPFree(char* pcStorage); 4.7.0.10. Description Frees the storage pcStorage allocated by the SLP API. The only storage that needs freeing are the char* returned from SLPFindSrvTypes() and SLPFindScopes(), and the s_pcURL field char* returned as part of the SLPSrvURL structs returned from SLPFindSrvs(). 4.7.0.11. Parameters pcStorage A pointer to the storage allocated through the SLP API. Ignored if NULL. 4.7.1. SLPOpaqueToRadix64 4.7.1.1. Synopsis logn SLPOpaqueToRadix64(const SLPOpaque opaque, const long lOSize, char* pcBuf, long lSize); Guttman, Kempf, Provan Expires 31 May 1998 [Page 26] Internet Draft Service Location API 30 November 1997 4.7.1.2. Description Convert an SLPOpaque into a radix-64 encoded string for transmission over the wire. See [12] for a description of radix-64 format and [5] for how it is used in SLP. 4.7.1.3. Parameters opaque The opaque value to convert. May not be NULL. lOSize The number of bytes in the opaque. pcBuf A client supplied buffer into which the null terminated radix-64 value is put. May not be NULL. lSize The number of array elements in the pcBuf array. 4.7.1.4. Returns Returns the number of characters in pcBuf or SLP_PARAMETER_BAD error if the buffer overflows. 4.7.2. SLPRadix64ToOpaque 4.7.2.1. Synopsis logn SLPRadix64ToOpaque(const char* pcRadix64, SLPOpaque opaque, long lSize); Guttman, Kempf, Provan Expires 31 May 1998 [Page 27] Internet Draft Service Location API 30 November 1997 4.7.2.2. Description Convert a radix-64 encoded SLPOpaque into binary format. See [12] for a description of radix-64 format and [5] for how it is used in SLP. 4.7.2.3. Parameters pcRadix64 The radix-64 value to convert, as a null terminated string. May not be NULL. opaque A buffer containing storage for where the binary opaque should be placed. May not be NULL. lOSize The number of bytes in the opaque. 4.7.3. SLPEscape 4.7.3.1. Synopsis long SLPEscape(const char* pcEscapee char* pcBuf, long lSize); 4.7.3.2. Description Escape any escapable characters in pcEscapee into the escape format described in [5]. Use the currently active character encoding established for the API via the property setting for net.slp.characterEncoding. 4.7.3.3. Parameters pcEscapee Null terminated string to escape. May not be NULL. Guttman, Kempf, Provan Expires 31 May 1998 [Page 28] Internet Draft Service Location API 30 November 1997 pcBuf A buffer containing storage for where the escaped string is to be placed. May not be NULL. lSize The number of bytes in pcBuf. 4.7.3.4. Returns If no error, returns the number of bytes in pcBuf. If an error ocurs, returns SLP_PARAMETER_BAD error if the buffer overflows. 4.7.4. SLPUnescape 4.7.4.1. Synopsis long SLPUnescape(const char* pcUnescapee char* pcBuf, long lSize); 4.7.4.2. Description Unescape any escapable characters in pcUnescapee out of the escape format described in [5]. Use the currently active character encoding established for the API via the property setting for net.slp.characterEncoding. 4.7.4.3. Parameters pcUnescapee Null terminated string to escape. May not be NULL. pcBuf A buffer containing storage for where the unescaped string is to be placed. May not be NULL. lSize The number of bytes in pcBuf. Guttman, Kempf, Provan Expires 31 May 1998 [Page 29] Internet Draft Service Location API 30 November 1997 4.7.4.4. Returns If no error, returns the number of bytes in pcBuf. If an error ocurs, returns SLP_PARAMETER_BAD error if the buffer overflows. 4.7.5. SLPGetProperty 4.7.5.1. Synopsis const char* SLPGetProperty(const char* pcName); 4.7.5.2. Description Returns the value of the corresponding SLP property name, or NULL if none. 4.7.5.3. Parameters pcName Null terminated string with the property name, from Section 2.1. May not be NULL. 4.7.5.4. Returns If no error, returns a pointer to the property value. If an error occurs, returns NULL. The returned string should NOT be freed. 4.7.6. SLPSetProperty 4.7.6.1. Synopsis void SLPSetProperty(const char* pcName, const char* pcValue); 4.7.6.2. Description Sets the value of the SLP property to the new value. The pcValue parameter should be the property value as a string. Guttman, Kempf, Provan Expires 31 May 1998 [Page 30] Internet Draft Service Location API 30 November 1997 4.7.6.3. Parameters pcName Null terminated string with the property name, from Section 2.1. May not be NULL. pcValue Null terminated string with the property value, in character format. May not be NULL. 4.8. Implementation Notes 4.8.1. Initialization Dynamic link libraries are encouraged to initialize the SLP library when linking occurs, provided the platform supports dynamically linked library initialization. Statically linked applications are required to initialize on the first call to SLPOpen(). 4.8.2. Multithreading Since C has no language level thread access package, access to multithreading is necessarily platform specific. However, implementations are required to be thread safe. At the grossest level, thread safety can be achieved by simply locking the library whenever a thread enters, but the lack of multithreaded access to the library reduces performance. At the next level, access to the library through the SLPConn handles can be locked, so only one thread can invoke library operations on a SLPConn handle at a time. The SLPConn handles may internally need to store thread state in order to achieve this. Finally, at the finest level, individual functions and data structures internal to the SLP API implementation can be locked, so that the maximum amount of throughput is obtained. 4.8.3. Syntax for String Parameters Query strings, attribute registration lists, attribute deregistration lists, and attribute selection lists follow the syntax described in [5] 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, Guttman, Kempf, Provan Expires 31 May 1998 [Page 31] Internet Draft Service Location API 30 November 1997 including escaping and converting opaque values to radix-64 encoded strings. Similarly, on output, clients are required to unescape strings and convert radix-64 encoded opaques to binary. Utility functions are included to help in the process. 4.8.4. Client Side Syntax Checking Implementations may do syntax checking of scope names, naming authority names, and service type names on the client side, but are not required to do so. 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 should be returned. If any parameter is NULL and is required to be nonNULL, SLP_PARAMETER_BAD is returned. 4.8.5. Character Set Encoding Implementations are required to support US-ASCII, LATIN1, and UTF8 IANA character set encodings, and are encouraged to support Unicode. The net.slp.characterEncoding property supplies the currently active encoding to use. The API must translate between the string property value and the IANA MIB enum value to use in the protocol header. 4.8.6. System Properties The system properties established in the configuration file are accessable through the SLPGetProperties() and SLPSetProperties() functions. 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. In general, individual agents should rarely be required to override these properties, since they reflect properties of the SLP network which are not of concern to individual agents. If changes are required, system administrators should modify the configuration file. 4.8.7. Registration and the Fresh Flag Implementations are required to return the value of the SLP protocol fresh flag received as part of the SLP reply to a registration request, as the return value of SLPReg(). The client can use the fresh flag to determine if the registration is new or if it is an update. Guttman, Kempf, Provan Expires 31 May 1998 [Page 32] Internet Draft Service Location API 30 November 1997 4.8.8. Memory Management Character strings returned via the SLPFindSrvTypes(), SLPFindSrvs(), and SLPFindScopes() functions should be freed when no longer needed via the SLPFree() function. Character strings returned via the SLPGetProperty() function should NOT be freed. Most functions require the client to pass in an array of the appropriate data type and an array size, and return the number of items in the array, or an error if a buffer overflow occured. 4.9. Examples Suppose web servers register themselves with the SLP framework. The attributes they register are a scope, and index of all the home pages available on the server. The homepages are listed as "::" "::" <description> The web server code does the following: long err = SLP_OK; SLPConn sh = SLPOpen("en") /*an English connection*/ if( sh == NULL ) { /*Deal with error.*/ } /*Create the service: URL and attribute parameters.*/ SLPSrvURL surl = { "service:http://myhost.sun.com", /*the URL */ SLP_LIFETIME_DEFAULT }; /*default lifetime*/ const char* attrs = "(SCOPE=ENGINEERING)," "(HOME PAGES=" "schedule/index.html::Schedule::" "This site contains updated timelines for all the work in" "the F.L.O.R.B. project," "snort/releases.html::Bob Snort's Home::" "Release engineer Bob posts results of all the builds " "here," "specs/index.html::Specs galore::" "Technical specifications for the F.L.O.R.B. and X872" Guttman, Kempf, Provan Expires 31 May 1998 [Page 33] Internet Draft Service Location API 30 November 1997 "projects.)"; err = SLPRegister(sh,surl,attrs); if (err < 0 ) { /*Deal with error.*/ } A web browser uses the SLP framework to find a particular web site. Unlike web indexing search engines, SLP keeps the information up to date and the information is available within a few seconds after a web server registers itself. /* * The client calls SL_Open, exactly as above. */ const char* srvtype = "http"; /*the service type */ const char* scope = "ENGINEERING"; /*the scope */ const char* attrids = "HOME PAGES"; /*the attribute id */ char* attrbuf[MAXBUF]; /*the return buffer*/ long err = SLPFindAttrs(sh,srvtype,scope,attrids,attrbuf,MAXBUF); if (err < 0 ) { /*Deal with error.*/ } /* * The client will examine the AttrResult and * choose a HOME PAGE */ const char* query = "http/" /*the service type*/ "engineering/" /*the scope */ "Technical specifications " /*the description */ "for the F.L.O.R.B. and X872 " "projects./"; SLPSrvURL surls[MAXURL]; Guttman, Kempf, Provan Expires 31 May 1998 [Page 34] Internet Draft Service Location API 30 November 1997 err = SLPFindSrvs(sh,query,surls,MAXURL); if( err < 0 ) { /*Deal with error.*/ } This will return a SLPService with the URL: "service:http://myhost.sun.com" The application can append on the "specs/index.html" from the attribute to obtain a URL for the browser to use: "http://myhost.sun.com/specs/index.html" 5. Java Language Binding 5.1. Introduction The Java API is designed to model the various SLP entities in classes and objects. API's are provided for SA, UA, and service type template access capabilities. The ServiceLocationManager class contains methods which return instances of objects implementing SA, UA, and service type template access capability. Each of these is modelled in an interface. The Locator interface provides UA capability, the Advertiser interface provides SA capability, and the TemplateRegistry provides access to service type templates. The TemplateRegistry interface contains methods that return objects for template introspection and attribute type checking. The ServiceURL class and ServiceLocationAttribute class model the basic service: URL and attribute concepts. All SLP classes and interfaces are located within a single package. The package name should begin with the name of the implementation and conclude with the suffixnet.slp. Thus, the name for a hypothetical implementation from the University of Michigan would look like: edu.umich.net.slp This follows the Java convention of prepending the top level DNS domain name for the organization implementing the package onto the organization's name and using that as the package prefix. Guttman, Kempf, Provan Expires 31 May 1998 [Page 35] Internet Draft Service Location API 30 November 1997 5.2. Basic Data Structures 5.2.1. Class ServiceLocationAttribute 5.2.1.1. Synopsis public final class ServiceLocationAttribute extends Object 5.2.1.2. Description The ServiceLocationAttribute class models SLP attributes. Instances of this class are returned by Locator.findAttributes() and are communicated along with register/deregister requests. 5.2.1.3. Constructors public ServiceLocationAttribute(String id,Vector values) Construct a service location attribute. Parameters: id The attribute name. The String can consist of any Unicode character. values A Vector of one or more attribute values. Vector contents must be uniform in type and one of Integer, String, Boolean, or byte[]. If the attribute is a keyword attribute, then parameter should be null. String values can consist of any Unicode character. Throws: IllegalArgumentException Thrown if either parameter is null or the Vector contents has a type mismatch. Guttman, Kempf, Provan Expires 31 May 1998 [Page 36] Internet Draft Service Location API 30 November 1997 5.2.1.4. Instance Methods public final Vector getValues() Returns a cloned vector of attribute values, or null if the attribute is a keyword attribute. If the attribute is single-valued, then the vector contains only one object. public final String getId() Returns the attribute's name. public final String getEscapedId() Returns an escaped version of the id, suitable for inclusion in a query. The character encoding used to convert escapable characters to escape form is the encoding specified in the SLP configuration file, or, if unset, the default Java encoding. public final Vector getEscapedValues() Returns a Vectors containing the escaped values as Strings, suitable for inclusion in a query. Binary arrays are converted into radix-64 [12] format and the character encoding used to convert escapable characters to escape form is the encoding specified in the SLP configuration file, or, if unset, the default Java encoding. public boolean equals(Object o) Overrides Object.equals(). public String toString() Overrides Object.toString(). Guttman, Kempf, Provan Expires 31 May 1998 [Page 37] Internet Draft Service Location API 30 November 1997 5.2.2. Class ServiceURL 5.2.2.1. Synopsis public class ServiceURL extends Object 5.2.2.2. Description The ServiceURL object models the SLP service: URL. These objects are returned from service lookup requests, and describe the registered services. The constructors provide access to various levels of the service: URL BNF grammer. 5.2.2.3. Class Variables public static final int NO\_PORT Indicates that no port information is required or was returned for this service: URL. public static final int LIFETIME\_NONE Indicates that the service: URL has no lifetime. public static final int LIFETIME\_DEFAULT The default service: URL lifetime. public static final int LIFETIME\_PERMANENT The service should last as long as the registering application continues in execution. 5.2.2.4. Constructors Guttman, Kempf, Provan Expires 31 May 1998 [Page 38] Internet Draft Service Location API 30 November 1997 public ServiceURL(String serviceURL) Construct a service: URL object. Parameters: serviceURL The service: URL as a string. Throws: IllegalArgumentException Thrown if parse errors occur in the parameter. public ServiceURL(String sURL,int iLifetime) Construct a service: URL object. Parameters: serviceURL The service: URL as a string. lifetime The service advertisement lifetime. Throws: IllegalArgumentException Thrown if parse errors occur in the parameter. public ServiceURL(String serviceTypeAndNamingAuthority, String servicePart, int iLifetime) Construct a service: URL object. Parameters: Guttman, Kempf, Provan Expires 31 May 1998 [Page 39] Internet Draft Service Location API 30 November 1997 serviceTypeAndNamingAuthority The name for a registered service type, including naming authority. They are separated with a "." servicePart The host name or number, port, and URL path to the service. lifetime The duration of the registration in seconds. Throws: IllegalArgumentException Thrown if parse errors occur in the parameter. public ServiceURL(String serviceTypeAndNamingAuthority, String login, String sURLPath, int iLifetime) Construct a service: URL object. Parameters: serviceTypeAndNamingAuthority The name for a registered service type, including naming authority. login The host name or number, and port. URLPath The URL path to the service, if any. lifetime The service advertisement lifetime. Throws: Guttman, Kempf, Provan Expires 31 May 1998 [Page 40] Internet Draft Service Location API 30 November 1997 IllegalArgumentException Thrown if parse errors occur in any parameter. public ServiceURL(String serviceType, String namingAuthority, String hostPort, String sURLPath, int iLifetime) Construct a service: URL object. Parameters: serviceType The name for a registered service type. namingAuthority The naming authority for the service. hostPort The machine name or IP address and TCP port number, if any. URLPath The URL path to the service, if any. lifetime The service advertisement lifetime. Throws: IllegalArgumentException Thrown if parse errors occur in any parameter. public ServiceURL(String serviceType, String namingAuthority, String address, int iPort, String URLPath, int iLifetime) Guttman, Kempf, Provan Expires 31 May 1998 [Page 41] Internet Draft Service Location API 30 November 1997 Construct a service: URL object. Parameters: serviceType The name for a service type. namingAuthority The naming authority for the service. host The machine name or IP address. port The TCP port number, if any. Use NO_PORT if none. URLPath The URL path to the service, if any. lifetime The service advertisement lifetime. Throws: IllegalArgumentException Thrown if parse errors occur in any parameter. 5.2.2.5. Methods public final String getServiceType() Returns the service type name. public final String getServicePart() Guttman, Kempf, Provan Expires 31 May 1998 [Page 42] Internet Draft Service Location API 30 November 1997 Returns the service part (host + port + URL path). public final String getHost() Returns the machine name or IP address. public final int getPort() Returns the port number, if any. public final String getURLPath() Returns the URL path description, if any. public final int getLifetime() Returns the service advertisement lifetime. public final String getNamingAuthority() Returns the naming authority for the ServiceURL. An empty string means the default. public final String getServiceTypeAndNamingAuthority() Returns the service type and naming authority. public final String toString() Returns formatted string with the service: URL. Overrides Object.toString() Guttman, Kempf, Provan Expires 31 May 1998 [Page 43] Internet Draft Service Location API 30 November 1997 5.3. SLP Access Interfaces 5.3.1. Interface Advertiser 5.3.1.1. Synopsis public interface Advertiser 5.3.1.2. Description The Advertiser is the SA interface, allowing clients to register new service instances with SLP, to change the attributes of existing services, and to deregister service instances. New registrations and modifications of attributes are made in the language locale with which the Advertiser was created, deregistrations of service instances are made for all locales. 5.3.1.3. Instance Methods public abstract Locale getLocale() Return the language locale with which this object was created. public abstract Vector findScopes() Returns a vector Strings giving known scope names. The vector will always have at least one element: "", the empty string, for unscoped. public abstract void register(ServiceURL URL, Vector scopeNames, Vector attributes) throws ServiceLocationException Register a new service with SLP. Parameters: Guttman, Kempf, Provan Expires 31 May 1998 [Page 44] Internet Draft Service Location API 30 November 1997 URL The service: URL for the service. vScopes The SLP scopes of the service. attributes A vector of ServiceLocationAttribute objects describing the service. Throws : IllegalArgumentException Thrown if any parameter is null. ServiceLocationCharsetNotSupportedException Thrown if the SA server (if one exists) or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationAuthenticationException Thrown if one or more of the scopes are protected and the SLP framework for the Advertiser is not part of the protected scope. ServiceLocationInternalNetException Thrown if an error occurs in network communication. ServiceLocationScopeNotSupportedException Thrown if the DA is not part of one of the scopes. ServiceLocationParseException Thrown if the DA or SA server (if one exists) encounters an unspecified error. public abstract void deregister(ServiceURL URL) throws ServiceLocationException Guttman, Kempf, Provan Expires 31 May 1998 [Page 45] Internet Draft Service Location API 30 November 1997 Deregister a service with the service location protocol. This has the effect of deregistering the service from every language locale and scope it was registered under. Parameters: URL The service: URL for the service. Throws: IllegalArgumentException Thrown if the parameter is null. ServiceLocationCharsetNotSupportedException Thrown if the SA server (if one exists) or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationAuthenticationException Thrown if one or more of the scopes in which the argument service: URL ia registered are protected and the SLP framework for the Advertiser is not part of the protected scope. ServiceLocationInternalNetException Thrown if an error occurs in network communication. ServiceLocationInvalidRegistrationException Thrown if the argument service: URL was not registered. ServiceLocationParseException Thrown if the DA or SA server (if one exists) encounters an unspecified error. public abstract void addAttributes(ServiceURL URL, Vector scopeNames, Vector attributes) throws ServiceLocationException Guttman, Kempf, Provan Expires 31 May 1998 [Page 46] Internet Draft Service Location API 30 November 1997 Update the registration by adding the given attributes. Parameters: URL The service: URL for the service. vScopes The SLP scopes of the service. attributes A vector of ServiceLocationAttribute objects to add to the existing registration. Throws: IllegalArgumentException Thrown if any parameter is null. ServiceLocationCharsetNotSupportedException Thrown if the SA server (if one exists) or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationAuthenticationException Thrown if one or more of the scopes are protected and the SLP framework for the Advertiser is not part of the protected scope. ServiceLocationInternalNetException Thrown if an error occurs in network communication. ServiceLocationInvalidRegistrationException Thrown if the type of an attribute value does not match the type of an existing attribute. ServiceLocationScopeNotSupportedException Thrown if the DA is not part of one of the scopes. Guttman, Kempf, Provan Expires 31 May 1998 [Page 47] Internet Draft Service Location API 30 November 1997 ServiceLocationParseException Thrown if the DA or SA server (if one exists) encounters an unspecified error. public abstract void deleteAttributes(ServiceURL URL, Vector attributeIds) throws ServiceLocationException Delete the attributes from a service: URL in all scopes for the locale with which the Advertiser was created. Parameters: URL The service: URL for the service. attributeIds A vector of Strings indicating the id's of the attributes to remove. Throws: IllegalArgumentException Thrown if any parameter is null. ServiceLocationCharsetNotSupportedException Thrown if the SA server (if one exists) or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationAuthenticationException Thrown if one or more of the scopes in which the URL is registered are protected and the SLP framework for the Advertiser is not part of the protected scope. ServiceLocationInternalNetException Thrown if an error occurs in network communication. Guttman, Kempf, Provan Expires 31 May 1998 [Page 48] Internet Draft Service Location API 30 November 1997 ServiceLocationInvalidRegistrationException Thrown if the URL is not registered or not registered in the language locale of the Advertiser, if the service: URL has no attributes, or if there are no attributes matching the tags. ServiceLocationParseException Thrown if the DA or SA server (if one exists) encounters an unspecified error. 5.3.2. Interface Locator 5.3.2.1. Synopsis public interface Locator 5.3.2.2. Description The Locator is the UA interface, allowing clients to query the SLP framework about existing service types, services instances, scopes, and about the attributes of an existing service instance or service type. Queries for services and attributes are made in the locale the Locator was created with, queries for service types and scopes are independent of locale. 5.3.2.3. Instance Methods public abstract Locale getLocale() Return the language locale with which this object was created. public abstract Vector findScopes() Returns a vector Strings giving known scope names. The vector will always have at least one element: "", the empty string, for unscoped. public abstract Vector Guttman, Kempf, Provan Expires 31 May 1998 [Page 49] Internet Draft Service Location API 30 November 1997 findServiceTypes(String namingAuthority, String scope) throws ServiceLocationException Returns a vector Strings givning known service types for this scope and naming authority. If no service types are found, an empty vector is returned. The service type names are returned with the naming authority included, i.e. as: service-type "." naming-authority Parameters: namingAuthority The naming authority. Use the empty string, "", for the default naming authority or "*" for all naming authorities. scope The scope name. Use the empty string for no scope. Throws: IllegalArgumentException Thrown if either the scope or the naming authority contain illegal characters, or if either parameter is null. ServiceLocationCharsetNotSupportedException Thrown if the SA or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationScopeNotSupportedException Thrown if the DA does not support the scope. ServiceLocationParseException Thrown if the DA or SA encounters an unspecified error. public abstract Vector findServices(String serviceType, String namingAuthority, Guttman, Kempf, Provan Expires 31 May 1998 [Page 50] Internet Draft Service Location API 30 November 1997 String scope, String query) throws ServiceLocationException Returns a vector of ServiceURL objects for services matching the query. If no services are found, an empty vector is returned. Parameters: serviceType The SLP service type of the service. namingAuthority The naming authority for the type. Use empty string, "", for default. scope The name of the scope. Use empty string for no scope. query A string with the SLP query. The query must be properly formatted according to the rules in Section 5. of [5]. In particular, all escapable characters in the attribute id's and patterns must be escaped, and byte array patterns must be in radix-64 [12] format. The ServiceLocationAttribute.getEscapedId() and ServiceLocationAttribute.getEscapedValues() methods can be used to obtain escaped id and value strings for use in formulating a query. In addition, patterns may use wildcards as described in [5] to match a range of string attribute values. An empty string, "", for the query returns all services having the indicated service type, naming authority, and scope. Throws: IllegalArgumentException Thrown if any parameter contains illegal characters, or is null. Guttman, Kempf, Provan Expires 31 May 1998 [Page 51] Internet Draft Service Location API 30 November 1997 ServiceLocationCharsetNotSupportedException Thrown if the SA or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationLanguageNotSupportedException Thrown if the net.slp.isMonolingual property is true and the SA or DA has registrations for another language locale but not for the language locale of this Locator. ServiceLocationScopeNotSupportedException Thrown if the DA does not support the scope. ServiceLocationParseException Thrown if the DA or SA encounters an unspecified error or the query is improperly formatted. public abstract Vector findAttributes(ServiceURL URL, String scope, Vector attributeIds) throws ServiceLocationException For the service: URL and scope, return a Vector of ServiceLocationAttribute objects whose id's match the String patterns in the attributeIds Vector. The request is made in the language locale of the Locator. If no attributes match, an empty vector is returned. Parameters: URL The service: URL for which the attributes are desired. scope The scope. Use empty string for no scope. attributeIds A Vector of String patterns identifying the desired attributes. An empty vector means return all attributes. As described in [5], Section 12., the patterns may include wildcards to Guttman, Kempf, Provan Expires 31 May 1998 [Page 52] Internet Draft Service Location API 30 November 1997 match all prefixes or suffixes. The patterns may include escapable characters. Throws: IllegalArgumentException Thrown if any parameter is null or the scope name contains illegal characters. ServiceLocationCharsetNotSupportedException Thrown if the SA or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationLanguageNotSupportedException Thrown if the net.slp.isMonolingual property is true and the SA or DA has registrations for another language locale but not for the language locale of this Locator. ServiceLocationScopeNotSupportedException Thrown if the DA does not support the scope. ServiceLocationParseException Thrown if the DA or SA encounters an unspecified error. public abstract Vector findAttributes(String serviceType, String namingAuthority, String scope, Vector attributeIds) throws ServiceLocationException For the type and scope, return a Vector of all ServiceLocationAttribute objects whose id's match the String patterns in the attributeIds Vector. The request is made independent of language locale. If no attributes are found, an empty vector is returned. Parameters: serviceType The service type. Guttman, Kempf, Provan Expires 31 May 1998 [Page 53] Internet Draft Service Location API 30 November 1997 namingAuthority The naming authority for the type. Use the empty string, "", for default. scope The scope. Use empty string for no scope. attributeIds A Vector of String patterns identifying the desired attributes. An empty vector means return all attributes. As described in [5], Section 12., the patterns may include wildcards to match all prefixes or suffixes. The patterns may include escapable characters. Throws: IllegalArgumentException Thrown if any parameter is null or contains illegal characters. ServiceLocationCharsetNotSupportedException Thrown if the SA or DA does not support the character set encoding set by the net.slp.characterEncoding property. ServiceLocationScopeNotSupportedException Thrown if the DA does not support the scope. ServiceLocationParseException Thrown if the DA or SA encounters an unspecified error. 5.3.3. Interface TemplateRegistry 5.3.3.1. Synopsis public interface TemplateRegistry Guttman, Kempf, Provan Expires 31 May 1998 [Page 54] Internet Draft Service Location API 30 November 1997 5.3.3.2. Description The TemplateRegistry interface provides access to service location templates [11]. Classes implementing TemplateRegistry register and unregister service templates, look up template URL's based on the service type name, and return attribute verifiers for verifying that vectors of attributes to be used in registering a service instance match the service's template, and for introspection on the template definition. Note that the Advertiser is not required to verify attributes before registering. 5.3.3.3. Instance Methods public abstract void registerServiceTemplate(String serviceType, String documentURL, String version, Locale locale, String description, String urlPathRules) throws ServiceLocationException Register the service template with the template registry. Parameters: serviceType The service type name, including naming authority. documentURL The URL of the template document. version The version number of template document. locale The language locale of the template. description Help text describing the service. Guttman, Kempf, Provan Expires 31 May 1998 [Page 55] Internet Draft Service Location API 30 November 1997 urlPathRules The ABNF grammer describing the service: URL's url part. Throws: InvalidArgumentException Thrown if any parameter is null, if the service type name has illegal characters, or if the document URL has an invalid format. ServiceLocationInvalidRegistrationException Thrown if the template is already registered or the registration fails. public abstract void deregisterServiceTemplate(String serviceType) throws ServiceLocationException Deregister the template for service type. Parameters: serviceType The service type name, including naming authority. Throws: IllegalArgumentException Thrown if the parameter is null or contains illegal characters. ServiceLocationInvalidRegistrationException Thrown if the template is not registered. public abstract ServiceLocationAttributeVerifier attributeVerifier(String serviceType) throws ServiceLocationException Guttman, Kempf, Provan Expires 31 May 1998 [Page 56] Internet Draft Service Location API 30 November 1997 Returns an attribute verifier for the service type. The attribute verifier can be used to verify that attributes for registration match the template, and can for introspection on the template definition. Parameters: serviceType A String containing the name of the service type. Throws: IllegalArgumentException Thrown if the parameter is null or if the service type contains illegal characters. ServiceLocationParseException Thrown if any syntax errors are encountered during parsing of service's template document. The message describes the error in more detail 5.4. The Service Location Manager 5.4.1. Class ServiceLocationManager 5.4.1.1. Synopsis public class ServiceLocationManager extends Object 5.4.1.2. Description The ServiceLocationManager manages access to the connection with the service location framework. Clients obtain the Locator, Advertiser, and TemplateRegistry objects for UA, SA, and service template access from the ServiceLocationManager. 5.4.1.3. Class Methods public static Locator getLocator(Locale locale) Guttman, Kempf, Provan Expires 31 May 1998 [Page 57] Internet Draft Service Location API 30 November 1997 throws ServiceLocationException Return a Locator object for the given language Locale. If the implementation does not support UA functionality, returns null. Parameters: locale The language locale of the Locator. The default locale is uses if null. Throws: ServiceLocationInternalSystemException Thrown if any internal errors occur. ServiceLocationInitNetException Thrown if the network connection to multicast or DA unicast cannot be initiated. ServiceLocationInternalNetException Thrown if errors occur in network communication. public static Advertiser getAdvertiser(Locale locale) throws ServiceLocationException Return an Advertiser object for the given language locale. If the implementation does not support SA functionality, returns null. Throws: ServiceLocationInternalSystemException Thrown if any internal errors occur. ServiceLocationInitNetException Thrown if the network connection to multicast or DA unicast cannot be initiated. Guttman, Kempf, Provan Expires 31 May 1998 [Page 58] Internet Draft Service Location API 30 November 1997 ServiceLocationInternalNetException Thrown if errors occur in network communication. public static TemplateRegistry getTemplateRegistry() throws ServiceLocationException Return a TemplateRegistry object for programmatic access to service location type template documents. If the implementation does not support template registry functionality, returns null. Throws: ServiceLocationInternalSystemException Thrown if the root template document can't be found. 5.5. Service Type Template Introspection 5.5.1. Interface ServiceLocationAttributeVerifier 5.5.1.1. Synopsis public interface ServiceLocationAttributeVerifier 5.5.1.2. Description The ServiceLocationAttributeVerifier provides access to service type templates. Classes implementing this interface parse SLP template definitions, provide information on attribute definitions for service types, and verify whether a ServiceLocationAttribute object matches a template for a particular service type. Clients obtain ServiceLocationAttributeVerifier objects for specific SLP service types through the TemplateRegistry. 5.5.1.3. Instance Methods public abstract String getServiceType() Guttman, Kempf, Provan Expires 31 May 1998 [Page 59] Internet Draft Service Location API 30 November 1997 Returns the SLP service type for which this is the verifier. public abstract Vector getTemplateAttributeDescriptors() Returns a Vector of ServiceLocationAttributeDescriptor objects describing the template service type attributes. The template service type attributes are: service-type The SLP service type name. version The version number of the template. language The ISO-639 [10] language locale of the template. description A natural language description of the service in the language of the language locale. url-syntax An ABNF [3] description for the service part of the service type's service: URL. public abstract Vector getTemplateAttributes() Returns a Vector of ServiceLocationAttribute objects for the template attributes of this service type. The template attributes are listed above. The ServiceLocationAttribute objects in this vector will have the actual values of the template attributes. public abstract Dictionary getAttributeDescriptors() Guttman, Kempf, Provan Expires 31 May 1998 [Page 60] Internet Draft Service Location API 30 November 1997 Returns a Dictionary allowing introspection on the attribute definition in the service type template. The Dictionary has the attribute id's as the keys and ServiceLocationAttributeDescriptor objects for the attributes as values. This method is primarily for GUI tools to display attribute information. Programmatic verification of attributes should use the verifyAttribute() method. Note that small memory implementations may want to implement the Dictionary so that attributes are parsed on demand rather than at creation time. public abstract void verifyAttribute( ServiceLocationAttribute attribute) throws ServiceLocationParseException Verify that the attribute matches the template definition. Parameters: attribute The ServiceLocationAttribute object to be verified. Throws: ServiceLocationParseException Thrown if the attribute does not match a template definition. The message contains information on the attribute name and problem. public abstract void verifyRegistration( Vector attributeVector) throws ServiceLocationParseException Verify that the Vector of ServiceLocationAttribute objects matches the template for this service type. The vector must contain all the required attributes, and all attributes must match their template definitions. Parameters: Guttman, Kempf, Provan Expires 31 May 1998 [Page 61] Internet Draft Service Location API 30 November 1997 attributeVector A Vector of ServiceLocationAttribute objects for the registration. Throws: ServiceLocationParseException Thrown if the attribute vector does not contain the required attributes in the template, if any of the attributes do not match their template definition, or if the vector contains attributes not defined in the template. 5.5.2. Interface ServiceLocationAttributeDescriptor 5.5.2.1. Synopsis public interface ServiceLocationAttributeDescriptor 5.5.2.2. Description The ServiceLocationAttributeDescriptor interface provides introspection on a template attribute defintion. Classes implementing the ServiceLocationAttributeDescriptor interface return information on a particular service location attribute definition from the service type template. This information is primarily for GUI tools. Programmatic attribute verification should be done through the ServiceLocationAttributeVerifier. 5.5.2.3. Instance Methods public abstract String getId() Return a String containing the attribute's id. public abstract String getValueType() Guttman, Kempf, Provan Expires 31 May 1998 [Page 62] Internet Draft Service Location API 30 November 1997 Return a String containing the fully package-qualified Java type of the attribute. SLP types are translated into Java types as follows: STRING "java.lang.String" INTEGER "java.lang.Integer" BOOLEAN "java.lang.Boolean" OPAQUE "[B" (i.e. array of byte, byte[]) KEYWORD empty string, "" public abstract String getDescription() Return a String containing the attribute's help text. public abstract Enumeration getAllowedValues() Return an Enumeration of allowed values for the attribute type. For keyword attributes returns null. For no allowed values (i.e. unrestricted) returns an empty Enumeration. Small memory implementations may want to parse values on demand rather than at the time the descriptor is created. public abstract Enumeration getDefaultValues() Return an Enumeration of default values for the attribute type. For keyword attributes returns null. For no allowed values (i.e. unrestricted) returns an empty Enumeration. Small memory Guttman, Kempf, Provan Expires 31 May 1998 [Page 63] Internet Draft Service Location API 30 November 1997 implementations may want to parse values on demand rather than at the time the descriptor is created. public abstract boolean getIsMultivalued() Returns true if the "M" flag is set. public abstract boolean getIsOptional() Returns true if the "O"" flag is set. public abstract boolean getRequiresExplicitMatch() Returns true if the "X"" flag is set. public abstract boolean getIsLiteral() Returns true if the "L" flag is set. public abstract boolean getIsKeyword() Returns true if the attribute is a keyword attribute. 5.6. Exceptions 5.6.1. Class ServiceLocationException 5.6.1.1. Synopsis abstract public class ServiceLocationException extends Exception Guttman, Kempf, Provan Expires 31 May 1998 [Page 64] Internet Draft Service Location API 30 November 1997 5.6.1.2. Description The ServiceLocationException class is the superclass for all SLP exceptions. 5.6.2. Class ServiceLocationAuthenticationException 5.6.2.1. Synopsis public class ServiceLocationAuthenticationException extends ServiceLocationException 5.6.2.2. Description The ServiceLocationAuthenticationException class implements the AUTHENTICATION_ABSENT and AUTHENTICATION_FAILED error codes from Section 23 of [5]. 5.6.3. Class ServiceLocationCharsetNotUnderstoodException 5.6.3.1. Synopsis public class ServiceLocationCharsetNotUnderstoodException extends ServiceLocationException 5.6.3.2. Description The ServiceLocationCharsetNotUnderstoodException class implements the CHARSET_NOT_UNDERSTOOD error code from Section 23 of [5]. 5.6.4. Class ServiceLocationLanguageNotSupportedException 5.6.4.1. Synopsis public class ServiceLocationLanguageNotSupportedException extends ServiceLocationException Guttman, Kempf, Provan Expires 31 May 1998 [Page 65] Internet Draft Service Location API 30 November 1997 5.6.4.2. Description The ServiceLocationLanguageNotSupportedException class implements the LANGUAGE_NOT_SUPPORTED error code from Section 23 of [5]. 5.6.5. Class ServiceLocationScopeNotSupportedException 5.6.5.1. Synopsis public class ServiceLocationScopeNotSupportedException extends ServiceLocationException 5.6.5.2. Description The ServiceLocationScopeNotSupportedException class implements the SCOPE_NOT_SUPPORTED error code from Section 23 of [5]. 5.6.6. Class ServiceLocationParseException 5.6.6.1. Synopsis public class ServiceLocationParseException extends ServiceLocationException 5.6.6.2. Description The ServiceLocationParseException class implements the PROTOCOL_PARSE_ERROR error code from Section 23 of [5]. PROTOCOL_PARSE_ERROR is also returned by DA's and SA's when unspecified internal errors occur on the server side. Guttman, Kempf, Provan Expires 31 May 1998 [Page 66] Internet Draft Service Location API 30 November 1997 5.6.7. Class ServiceLocationInvalidRegistrationException 5.6.7.1. Synopsis public class ServiceLocationInvalidRegistrationException extends ServiceLocationException 5.6.7.2. Description The ServiceLocationInvalidRegistrationException class implements the INVALID_REGISTRATION error code from Section 23 of [5]. 5.6.8. Class ServiceLocationInternalSystemException 5.6.8.1. Synopsis public class ServiceLocationInternalSystemException extends ServiceLocationException 5.6.8.2. Description The ServiceLocationInternalSystemException is thrown when internal errors are encountered on the client, i.e SA and UA, side. 5.6.9. Class ServiceLocationInternalNetException 5.6.9.1. Synopsis public class ServiceLocationInternalNetException extends ServiceLocationException 5.6.9.2. Description The ServiceLocationInternalNetException is thrown when any network error occurs after initialization. Guttman, Kempf, Provan Expires 31 May 1998 [Page 67] Internet Draft Service Location API 30 November 1997 5.6.10. Class ServiceLocationInitNetException 5.6.10.1. Synopsis public class ServiceLocationInitNetException extends ServiceLocationException 5.6.10.2. Description The ServiceLocationInitNetException is thrown when an error occurs in intializing a network connection. 5.7. Implementation Notes 5.7.1. Client Side Syntax Checking The syntax of scope names, service type names, naming authority names, and service: URL's is described in [5] and [11]. The various methods and classes taking String parameters for these entities should type check the parameters for syntax errors on the client side, and throw an IllegalArgumentException if an error occurs. In addition, character escaping should be implemented before network transmission for escapable characters in attribute id's and String values. This reduces the number of error messages transmitted. The ServiceLocationAttribute class provides methods for obtaining escaped attribute id and value strings to facilitate query construction. 5.7.2. Character Set Encoding Java provides support for most IANA character encodings [6]. In addition to the underlying Java support, however, implementations are required to provide escaping and unescaping of escapable characters in attribute values, patterns, and id's. Escaping a character requires that the character to be translated into a numerical code in the on the wire encoding. Similarly, unescaping requires the numerical code to be translated back into the Unicode character used within the Java virtual machine. Implementations are required to support "US-ASCII" as the default encoding, and, additionally, "LATIN1", "Unicode"', and "UTF8". Other encodings may be supported. Guttman, Kempf, Provan Expires 31 May 1998 [Page 68] Internet Draft Service Location API 30 November 1997 5.7.3. Language Locale Handling The Locator and Advertiser interfaces are created with a Locale parameter. The language locale with which these objects are created is used in all SLP requests issued through the object. If the Locale parameter is null, the default is used. The default locale is determined by, first, checking the net.slp.locale System property. If that is unset, then the default Java locale is used. The locale is the only SLP system property for which an API operation override is provided. 5.7.4. Setting SLP System Properties SLP system properties that are originally set in the configuration file can be overridden programmatically in API clients by simply invoking the System.getProperties() operation to get a copy of the system properties, modifying or adding the SLP property in question, then using System.setProperties() to set the properties to the modified Property object. 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. In general, individual agents should rarely be required to override these properties, since they reflect properties of the SLP network which are not of concern to individual agents. If changes are required, system administrators should modify the configuration file. 5.7.5. Implementing register() and addAttributes() Because the underlying SLP protocol has no separate message for updating a registration, it is not possible to implement the Advertiser.register() and Advertiser.addAttributes() operations disjointly without caching or performing an additional protocol message. The ``natural semantics'' are that a Advertiser.register() causes the advertisement to be replaced by the new registration, while Advertiser.addAttributes() causes attributes to be added to an existing registration, or ignored if there is no registration. However, the service registration message in SLP causes an update if the advertisement already exists, otherwise it registers the new advertisment. Only upon return does the SA learn, via the message header ``fresh'' bit, whether the advertisement was an update or a new registration. An implementation can use either one of two algorithms to implement the natural semantics for these operations: Guttman, Kempf, Provan Expires 31 May 1998 [Page 69] Internet Draft Service Location API 30 November 1997 Issue a protocol request prior to the service registration to obtain information on the current status of the advertisement. Cache registrations and use the cached information to determine the current status of the advertisement. The first solution would require issuing an SLP service request prior to the register request and, if the service is registered, issuing a SLP deregister request. The second solution would use the cached registration determine whether the advertisement is registered and to issue the deregister request, eliminating one network operation. For the Advertiser.addAttributes() operation, the first solution would require issuing an SLP attribute request prior to the register request to determine if the advertisement is registered, and only issuing the register request if so. The second solution would use the cached information to determine whether the advertisment is registered, prior to issuing the register request, again eliminating one network operation. Implementations may support these semantics, but because of the additional memory or network resource burden, are not required to do so. 5.7.6. Exceptions Each of the error codes in [5] are mapped into a subclass of ServiceLocationException, with the exception that the two authentication error codes, AUTHENTICATION_ABSENT and AUTHENTICATION_FAILED, are reported back to the client as a single exception, ServiceLocationAuthenticationException. Additional, client side exceptions that involve internal failures, network failures, or failures in initiating a network connection are reported through the ServiceLocationInternalSystemException, ServiceLocationInternalNetException, and ServiceLocationInitNetException. When parameters are checked for validity (such as not being null) or their syntax is checked, an error results in the RuntimeException subclass IllegalArgumentException being thrown. Clients of the API are reminded that IllegalArgumentException is unchecked by the compiler, and so they should be careful to include try/catch blocks for it if the relevent parameters could be erroneous. 5.7.7. Multithreading Thread-safe and thread-hot operation are relatively easy to achieve in Java. By simply making each method in the classes implementing the Locator and Advertiser interfaces synchronized, and Guttman, Kempf, Provan Expires 31 May 1998 [Page 70] Internet Draft Service Location API 30 November 1997 by synchronizing access to any shared data structures within the class the Locator and Advertiser interfaces are both thread-safe and thread-hot. Similarly, automatic registration refreshing in the SA can be achieved by having a thread running the background that periodically refreshes all registrations whose ServiceURL lifetime parameter is ServiceURL.LIFETIME_PERMANENT. When Advertiser.register() is called with such a URL, the Advertiser implementation can record the URL for future reference. 5.7.8. Return of Unscoped Services Because of a peculiarity in SLP service request semantics (see Section 5. in [5]), a service request for which a scope is specified returns both services in that scope and unscoped services. There is no way to disallow return of unscoped services. Filtering out unwanted services is unfortunately time consuming, since the UA would have to send another service request for unscoped services, then remove matching items from the first return. Implementations may try to assure that the Locator interface just returns services in the scope for which the request was made, but are not required to do so. 5.7.9. Modular Implementations While, at first glance, the API may look rather heavyweight, the design has been carefully arranged so that modular implementations which provide only SA, only UA, or only service template access capability, or any combination of the three, are possible. Because the objects returned from the ServiceLocationManager.getLocator(), ServiceLocationManager.getAdvertiser(), and ServiceLocationManager.getTemplateRegistry() operations are interfaces, and because most objects returned through those interfaces are either in the set of base data structures or are, themselves, interfaces, an implementation is free to omit a particular capability. The classes implementing the capability can be dynamically linked when needed, or for particularly low weight implementations, the ServiceLocationManager access method for the missing object can simply return null. API clients are encouraged to check for such a contingency, and to signal an exception if it occurs. In this way, the API implementation can be taylored for the particular memory requirements at hand. Guttman, Kempf, Provan Expires 31 May 1998 [Page 71] Internet Draft Service Location API 30 November 1997 5.8. Examples In this example, a printer server advertises its availability to clients. Additionally, the server advertises a service template for use by client software in validating service requests: //Get the Advertiser and TemplateRegistry. Advertiser adv = null; TemplateRegistry tr = null try { adv = ServiceLocationManager.getAdvertiser("en"); tr = ServiceLocationManager.getTemplateRegistry(); } catch( ServiceLocationException ex ) { //Deal with error. } if( adv == null ) { //Serious error as printer can't be registered // if the implementation doesn't support SA // functionality. } //Get the scopes in which we are supposed to // register. Vector scopes = adv.findScopes(); //Get the printer's attributes, from a file or // otherwise. We assume that the attributes // conform to the template, otherwise, we // could register the template here and verify // them. Vector attributes = getPrinterAttributes(); //Create the service: URL for the printer. ServiceURL printerURL = Guttman, Kempf, Provan Expires 31 May 1998 [Page 72] Internet Draft Service Location API 30 November 1997 new ServiceURL( "service:printer:lpr://printshop/color2", ServiceURL.LIFETIME_PERMANENT); try { //Register the printer all scopes. adv.register(printerURL, scopes, attributes); //If the template registry is available, // register the printer's template. if( tr != null ) { tr.registerServiceTemplate( "printer", "http://shop.arv/printer/printer-lpr.slp", "1.0", "en", "This template describes the lpr "+ "concrete printer type.", "\"lpr://\" machine \"/\" queue"); } } catch( ServiceLocationException ex ) { //Deal with error. } Suppose a client is looking for color printer. The following code might be used to issue a request for printer service: URL's: Locator loc = null; TemplateRegistry tr = null; try { loc = ServiceLocationManager.getLocator("en"); tr = ServiceLocationManager.getTemplateRegistry(); } catch( ServiceLocationException ex ) { Guttman, Kempf, Provan Expires 31 May 1998 [Page 73] Internet Draft Service Location API 30 November 1997 //Deal with error. } if( loc == null ) { //Serious error as client can't be located // if the implementation doesn't support // UA functionality. } //We want a color printer that does CMYK // and prints at least 600 dpi. Vector attributes = new Vector(); Vector values = new Vector(); values.addElement("CMYK"); attributes.addElement( new ServiceLocationAttribute("marker-type", values)); values = new Vector(); values.addElement(new Integer(600)); attributes.addElement( new ServiceLocationAttribute("resolution", values)); //Check the attributes to be sure they // match. if( tr != null ) { ServiceLocationAttributeVerifier ver = null; try { ver = tr.attributeVerifier("printer"); ver.verifyAttribute(attributes.elementAt(0)); ver.verifyAttribute(attributes.elementAt(1)); } catch( ServiceLocationException ex ) { //Deal with error. } Guttman, Kempf, Provan Expires 31 May 1998 [Page 74] Internet Draft Service Location API 30 November 1997 } //Get scopes. Vector scopes = loc.findScopes(); //Get services. Any scope will do. Vector services = null; String scope = (String)scopes.elementAt(0); try { services = loc.findServices("printer",,attributes); } catch { //Deal with error. } //Printers can now be used. 6. Internationalization Considerations 6.1. service: URL The service: URL itself must be encoded using the rules set forth in [2]. The character set encoding is limited to specific ranges within the US-ASCII character set [1]. The attribute information associated with the service: URL may be expressed in any character set, and in any language. See [11] for attribute internationalization guidelines. 6.2. Character Set Identification and Use The way of identifying the character set used is the IANA Character Set registry MIB Enum value (in C) or IANA character set name (in Java). [6] It can be assumed that US-ASCII [1] will be supported. Programs which register or request information using other character sets must be prepared for the possibility that the SLP framework is not capable Guttman, Kempf, Provan Expires 31 May 1998 [Page 75] Internet Draft Service Location API 30 November 1997 of supporting it. In this case, they should fall back to US-ASCII if possible. The service's identity is independent of the character set encoding used to register it. A service can be registered with one character set encoding, queried in another, and deregister in a third as long as all three encodings map to the same URL. Furthermore, a different character set may be used in packets transmitted to satisfy the operation. 7. Security Considerations SLP will make use of an existing host based authentication framework once it becomes available as an Internet Standard. [7] In the absence of this, it is extremely easy for anyone to register any service with Service Location. SLP does not authenticate the source of service advertisements, either at the DA or when the UA receives it. For this reason, use of SLP on open networks, such as the Internet, should be avoided. A DA may be provided on an open network with registration capabilities disabled; but this is of limited utility since a UA would not be able to distinguish it from a DA full of impersonations. For this reason, SLP should only be used in 'private' networks, as those behind firewalls where users are expected to perform in a responsible manner. SLP is neutral to the protocols clients and servers use between themselves. Strong bidirectional authentication at higher levels (ie. transport level: "The SSL Protocol, Version 3" [9] or application level: "Generic Security Service Application Program Interface" [8]) would obviate the risk of masquerading by an adversary using SLP. An adversary could delete valid service advertisements and deny UAs knowledge of existing services. Guttman, Kempf, Provan Expires 31 May 1998 [Page 76] Internet Draft Service Location API 30 November 1997 References [1] ANSI. Coded Character Set -- 7-bit American Standard code for Information Interchange. X3.4-1986, 1986. [2] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource Locators (URL): Generic Syntax and Semantics. RFC1738 as amended by RFC1808 and updated by draft-fielding-url-syntax-05.txt, May 1997. (work in progress). [3] D. Crocker and P Overell. Augmented BNF for Syntax Specifications: ABNF. draft-ietf-drums-abnf-04.txt, September 1997. (work in progress). [4] Geneva ISO. Code for the representation of names of languages. ISO 639:1988 (E/F), 1988. [5] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service Location Protocol. RFC 2165, July 1997. [6] IANA IANA Character Set Registry <URL:http://www.isi.edu/in-notes/iana/assignments/character-sets> [7] R. Atkinson Security Architecture for the Internet RFC 1825 July 1995 [8] J. Linn Generic Security Application Program Interface, Version 2 A work in progress November 1996 [9] A. Freier, P. Karlton, P. Kocher The SSL Protocol, Version 3.0 A work in progress November 1996 [10] Geneva ISO Code for the representation of names of languages ISO 639:1998 (E/F) 1998 [11] E. Guttman, C. Perkins, J. Kempf Service Templates and service: Schemes A work in progress November 1997 [12] N. Borenstein and N. Freed. MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies. RFC 1521, September 1993. Guttman, Kempf, Provan Expires 31 May 1998 [Page 77] Internet Draft Service Location API 30 November 1997 Authors' Addresses Questions about this memo can be directed to: Erik Guttman James Kempf Don Provan Sun Microsystems Sun Microsystems Novell, Inc. Bahnstr. 2 901 San Antonio Rd. 2180 Fortune Drive 74915 Waibstadt Palo Alto, CA, 94303 San Jose, CA, 94303 Germany USA USA +49 7263 911484 1 650 786 5890 1 408 577 8440 1 650 786 6445 (fax) donp@novell.com erik.guttman@sun.com james.kempf@sun.com Guttman, Kempf, Provan Expires 31 May 1998 [Page 78]