Service Location Working Group James Kempf INTERNET DRAFT Erik Guttman Sun Microsystems Don Provan 13 March 1998 Novell, Inc. An API for Service Location draft-ietf-svrloc-api-04.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@srvloc.org 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), ftp.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 assistance from 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, standardized file formats for configuration and serialized registrations are defined, allowing SLP agents to set network and other parameters in a portable way. The serialized file format allows legacy services to be registered with SLP directory agents in cases where modifying the legacy service Kempf, Guttman, Provan Expires 13 September 1998 [Page i] Internet Draft Service Location API 13 March 1998 program code is difficult or impossible, and to portably exchange a registration database. Kempf, Guttman, Provan Expires 13 September 1998 [Page ii] Internet Draft Service Location API 13 March 1998 Contents Status of This Memo i Abstract i 1. Introduction 1 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 2. File Formats 4 2.1. Configuration File Format . . . . . . . . . . . . . . . . 4 2.1.1. DA configuration . . . . . . . . . . . . . . . . 5 2.1.2. Static Scope Configuration . . . . . . . . . . . 5 2.1.3. Tracing and Logging . . . . . . . . . . . . . . . 7 2.1.4. Serialized Proxy Registrations . . . . . . . . . 7 2.1.5. Networking Configuration Parameters . . . . . . . 7 2.1.6. UA Configuration . . . . . . . . . . . . . . . . 9 2.1.7. Security . . . . . . . . . . . . . . . . . . . . 9 2.2. Serialized Registration File . . . . . . . . . . . . . . 9 2.3. Proccessing Serialized Registration and Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . 11 3. Binding Independent Implementation Considerations 11 3.1. Multithreading . . . . . . . . . . . . . . . . . . . . . 11 3.2. Type Checking for Service Types . . . . . . . . . . . . . 11 3.3. Refreshing Registrations . . . . . . . . . . . . . . . . 12 3.4. Configuration File Processing . . . . . . . . . . . . . . 12 3.5. Attribute Types . . . . . . . . . . . . . . . . . . . . . 12 3.6. Removal of Duplicates . . . . . . . . . . . . . . . . . . 12 3.6.1. Character Set Encoding . . . . . . . . . . . . . 13 3.7. Error Semantics . . . . . . . . . . . . . . . . . . . . . 13 4. C Language Binding 15 4.1. Constant Types . . . . . . . . . . . . . . . . . . . . . 16 4.1.1. URL Lifetimes . . . . . . . . . . . . . . . . . . 16 4.1.2. Error Codes . . . . . . . . . . . . . . . . . . . 16 4.2. Struct Types . . . . . . . . . . . . . . . . . . . . . . 17 4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . . . 17 4.2.2. SLPSrvAccessPt . . . . . . . . . . . . . . . . . 18 4.2.3. SLPHandle . . . . . . . . . . . . . . . . . . . . 19 4.2.4. SLPOpaque . . . . . . . . . . . . . . . . . . . . 19 4.3. Opening and Closing the SLP Library . . . . . . . . . . . 19 4.3.1. SLPOpen . . . . . . . . . . . . . . . . . . . . . 19 4.3.2. SLPClose . . . . . . . . . . . . . . . . . . . . 20 4.4. Protocol API . . . . . . . . . . . . . . . . . . . . . . 20 Kempf, Guttman, Provan Expires 13 September 1998 [Page iii] Internet Draft Service Location API 13 March 1998 4.4.1. SLPReg . . . . . . . . . . . . . . . . . . . . . 20 4.4.2. SLPDereg . . . . . . . . . . . . . . . . . . . . 22 4.4.3. SLPDelAttrs . . . . . . . . . . . . . . . . . . . 22 4.4.4. SLPFindSrvTypes . . . . . . . . . . . . . . . . . 23 4.4.5. SLPFindSrvs . . . . . . . . . . . . . . . . . . . 25 4.4.6. SLPFindAttrs . . . . . . . . . . . . . . . . . . 26 4.5. Miscellaneous Functions . . . . . . . . . . . . . . . . . 28 4.6. SLPFindScopes . . . . . . . . . . . . . . . . . . . . . . 28 4.7. SLPParseSrvURL . . . . . . . . . . . . . . . . . . . . . 29 4.8. SLPFree . . . . . . . . . . . . . . . . . . . . . . . . . 30 4.8.1. SLPOpaqueToEscaped . . . . . . . . . . . . . . . 30 4.8.2. SLPEscapedToOpaque . . . . . . . . . . . . . . . 31 4.8.3. SLPEscape . . . . . . . . . . . . . . . . . . . . 32 4.8.4. SLPUnescape . . . . . . . . . . . . . . . . . . . 33 4.8.5. SLPGetProperty . . . . . . . . . . . . . . . . . 34 4.8.6. SLPSetProperty . . . . . . . . . . . . . . . . . 34 4.9. Implementation Notes . . . . . . . . . . . . . . . . . . 35 4.9.1. Syntax for String Parameters . . . . . . . . . . 35 4.9.2. Client Side Syntax Checking . . . . . . . . . . . 35 4.9.3. System Properties . . . . . . . . . . . . . . . . 36 4.9.4. Memory Management . . . . . . . . . . . . . . . . 36 4.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 36 4.10.1. Discovering one's mailbox . . . . . . . . . . . . 36 5. Java Language Binding 38 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 38 5.2. Exceptions and Errors . . . . . . . . . . . . . . . . . . 39 5.2.1. Class ServiceLocationException . . . . . . . . . 39 5.3. Basic Data Structures . . . . . . . . . . . . . . . . . . 40 5.3.1. Class ServiceLocationAttribute . . . . . . . . . 40 5.3.2. Class ServiceURL . . . . . . . . . . . . . . . . 42 5.4. SLP Access Interfaces . . . . . . . . . . . . . . . . . . 45 5.4.1. Interface Advertiser . . . . . . . . . . . . . . 45 5.4.2. Interface Locator . . . . . . . . . . . . . . . . 48 5.5. The Service Location Manager . . . . . . . . . . . . . . 51 5.5.1. Class ServiceLocationManager . . . . . . . . . . 51 5.6. Service Template Introspection . . . . . . . . . . . . . 53 5.6.1. Abstract Class TemplateRegistry . . . . . . . . . 53 5.6.2. Interface ServiceLocationAttributeVerifier . . . 55 5.6.3. Interface ServiceLocationAttributeDescriptor . . 58 5.7. Implementation Notes . . . . . . . . . . . . . . . . . . 60 5.7.1. Client Side Syntax Checking . . . . . . . . . . . 60 5.7.2. Language Locale Handling . . . . . . . . . . . . 60 5.7.3. Setting SLP System Properties . . . . . . . . . . 61 5.7.4. Implementing register() and addAttributes() . . . 61 5.7.5. Multithreading . . . . . . . . . . . . . . . . . 61 5.7.6. Scope . . . . . . . . . . . . . . . . . . . . . . 62 5.7.7. Modular Implementations . . . . . . . . . . . . . 62 5.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 62 Kempf, Guttman, Provan Expires 13 September 1998 [Page iv] Internet Draft Service Location API 13 March 1998 6. Internationalization Considerations 65 6.1. service URL . . . . . . . . . . . . . . . . . . . . . . . 65 6.2. Character Set Encoding . . . . . . . . . . . . . . . . . 65 6.3. Language Tagging . . . . . . . . . . . . . . . . . . . . 65 7. Security Considerations 66 1. Introduction The Service Location API is designed for standardized access the Service Location Protocol (SLP). The APIs allow client and service programs to be be written or modified in a very simple manner to provide dynamic service discovery and selection. Bindings in the C and Java languages are defined in this document. In addition, standardized formats for configuration files and for serialized registration files are presented. These files allow SLP agents to configure network parameters, to register legacy services that have not been SLP enabled, and to portably exchange registration databases. 1.1. Goals The overall goal of the API is to enable source portability of applications that use the API between different implementations of SLP. The result should facilitate the adoption of SLP, and conversion of clients and service programs to SLP. The goals of the C binding are to create a minimal but complete access to the functionality of the SLP protocol, allowing for simple memory management and limited code size. The Java API provides for modular implementations (where unneeded features can be omitted) and an object oriented interface to the complete set of SLP data and functionality. The standardized configuration file and serialized file formats provide a simple syntax with complete functional coverage of the protocol, but without including secure information such as private keys. Kempf, Guttman, Provan Expires 13 September 1998 [Page 1] Internet Draft Service Location API 13 March 1998 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 Version 2 [14]. 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 that automatically gathers service advertisements from SAs in order to provide them to UAs. User Agent (UA) This is the Service Location process or library that allows SLP requests to be made on behalf of a client process. UAs automatically direct requests to DAs when they exist. In their absence, UAs make requests directly to SAs. Service Agent (SA) This is the Service Location process or library that allows service software to register and deregister itself with the SLP framework. SAs MUST respond to UA service requests, detect DAs and register service advertisements with them. SA Server Many operating system platforms only allow a single process to listen on a particular port number. Since SAs are required to listen on a multicast address for SLP service requests, implementaions of the SLP framework on such platforms that want to support multiple SAs on one machine need to arrange for a single process to do the listening while the advertising SAs communicate with that process through another mechanism. The single listening process is called an SA server. SA servers share many characteristics with DAs, but they are not the same. Service Advertisement A URL possibly combined with service attributes. These are made available to UAs by SAs, either directly or via a DA. Kempf, Guttman, Provan Expires 13 September 1998 [Page 2] Internet Draft Service Location API 13 March 1998 Locale The language localization that applies to strings passed into or returned from the SLP API. The Locale is expressed using a Language Tag [13]. All attribute strings are associated with a particular locale. Service Template A document that describes the syntax of the URL for a given service type and a definition of all service attributes including the meaning, defaults, and constraints on values the attributes may take. See [15] for more information on service templates. The service: URL A service of a particular type announces its availability with a service: URL that includes its service access point (domain name or ip address, and possibly its port number) and optionally basic configuration parameters. The syntax of the service: URL is defined in the service template. Other URL's can be used in service advertisements if desired. Service Attributes The attributes associated with a given service. The values that can be assigned to service attributes are defined by the service template. Scope A string used to control the availability of service advertisements. Every SLP Agent is configured with one or more scope strings. Scopes are assigned by site administrators to group services for many purposes, but chiefly as a means of scalability. DAs store only services advertised having a scope string matching the scopes with which they are configured. UAs MUST specify a scope string in requests if the UA is configured with scope strings. Naming Authority (NA) This is a 'suffix' to the service type string. It completely changes the meaning of the service type. NAs are used for private definitions of well known Service Types and experimental Service Type extensions. The default NA is "IANA", which MUST NOT be explicitely included. Service types with the IANA naming authority are registered with the Internet Kempf, Guttman, Provan Expires 13 September 1998 [Page 3] Internet Draft Service Location API 13 March 1998 Assigned Numbers Authority (see [15] for more information on the registration procedure). 2. File Formats This section describes the configuration and serialized registration file formats. Both files are defined in the UTF8 character set [10]. String values in the configuration file allow escaped characters to be included. These include reserved characters (like newlines) or multibyte UTF8 characters, enabling characters outside of the ASCII range to be included in an ASCII format file, if full UTF8 support is not available in the platform's file system. An example of a character encoded this way is 'e accent aigu' character, which is 0x00e9 in Unicode, 0xc3a9 in UTF8, or `\c3\a9' escaped. Escaped characters are transformed back into (potentially multibyte) characters as the configuration file is read. Escaped strings beginning with `\255`, an encoding for a nonUTF8 character, are treated as opaques, and both escaped and nonescaped characters are converted to arrays of bytes. Such strings are only of interest in the serialized registration file as attribute values. In other cases, whenever an encoding for a nonUTF8 character is encountered, an error is signalled. 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 [12] 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 = prop | prop "." property prop = 1*char value = integer / boolean / vector / string integer = 1*DIGIT Kempf, Guttman, Provan Expires 13 September 1998 [Page 4] Internet Draft Service Location API 13 March 1998 boolean = "true" / "false" / "TRUE" / "FALSE" newline = CR / ( CRLF ) vector = "[" value-list "]" value-list = value / value "," value-list string = 1*allchar char = DIGIT / ALPHA / other other = %x21-%x2f / %x3a-%x40 / %x5b-%x60 / %7b-%7e allchar = char / HT / SP / escape escape = "\" HEXDIG HEXDIG ; Used for reserved characters 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 DAs are included in this section. These are: net.slp.isDA A boolean indicating if the SLP server is to act as a DA. If false, not run as a DA. Default is false. net.slp.DAHeartBeat A 64 bit integer giving the number of milliseconds for the DA heartbeat. Default is 3 hours (10800 seconds). Ignored if isDA is false. net.slp.isDAStateful A boolean indicating if the DA starts statefully and saves state when it exits. The DA restores service advertisements made before it went off line by reading a non-volatile store. Ignored if isDA is false. Default is false. 2.1.2. Static Scope Configuration These parameters allow various aspects of scope handling to be configured. Kempf, Guttman, Provan Expires 13 September 1998 [Page 5] Internet Draft Service Location API 13 March 1998 net.slp.useScopes A vector of strings indicating the only scopes a UA or SA is allowed to use when making requests or registring, or the scopes a DA must support. If absent, then there are no restrictions on scopes for UAs and SAs, and DAs are unscoped. If another scope is used by a UA or SA, a SCOPE_NOT_SUPPORTED error may be returned. Default is unscoped. Unlike other parameters, this parameter is ``read-only'', so attempts to change it after the configuration file has been read are ignored. Information obtained by DHCP superceedes this parameter. net.slp.DAAddresses A vector of IP addresses or DNS-resolvable names giving the DAs to use f4) or statically configured UAs and SAs, along with their scopes. Ignored if isDA is true. Default is none. Scopes from the net.slp.useScopes parameter and addresses and scopes obtained via DHCP take precedence over these. The following grammer describes the property: addresses = line-list addresses = "[" addr-list "]" addr-list = addr / addr "," addr-list addr = addrrep [ "[" scope-list "]" ] addrrep = ipv4-addr / ipv6-addr / fqdn ipv4-addr = 1*3DIGIT 3( "." 1*3DIGIT ) ipv6-addr = 64HEXDIGIT fqdn = ALPHA / ALPHA *[ anum / "-" ] anum anum = ALPHA / DIGIT scope-list = scope / scope "," scope-list scope = string ; See grammar of Section 2.1 ; and [14]. 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, da2 has scope1 and scope2, da3 has only scope3. Kempf, Guttman, Provan Expires 13 September 1998 [Page 6] Internet Draft Service Location API 13 March 1998 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 DAs. Default is false. net.slp.traceMsg A boolean controlling printing of details on SLP messages. The fields in all incoming messages and outgoing replies are printed. Default is false. net.slp.traceDrop A boolean controlling printing details when a SLP message is dropped for any reason. Default is false. net.slp.traceReg A boolean controlling dumps of all registered services upon registration and deregistration. If true, the contents of the DA or SA server are dumped after a registration or deregistration occurs. Default is false. 2.1.4. Serialized Proxy Registrations These properties control the reading and writing of serialized registrations. net.slp.serializedRegURL A string containing a URL pointing to a document containing serialized registrations that should be processed when the DA or SA server starts up. Default is none. 2.1.5. Networking Configuration Parameters The properties in this section allow various network configuration parameters to be set. Kempf, Guttman, Provan Expires 13 September 1998 [Page 7] Internet Draft Service Location API 13 March 1998 net.slp.isBroadcastOnly A boolean indicating if 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.maxWait A 32 bit integer giving the timeout in milliseconds on all requests. Default is 10000 ms. net.slp.multicastTimeouts A vector of 16 bit integers used as timeouts, in milliseconds, to implement the multicast convergence alorithm. Each value specifies the time to wait before sending the next request, or until nothing new has been learned from a subsequent request. Ignored if isDA is true. Default is: [3000,3000,3000,3000,3000]. In a fast network the agressive values of [1000,1250,1500] allow better performance. net.slp.passiveDADetection A boolean indicating whether passive DA detection should be used. Default is true. net.slp.DADiscoveryTimeout A 16 bit integer indicating the timeout for multicast convergence, in milliseconds, for active DA discovery. Default is [2000,2000,2000]. net.slp.MTU A 16 bit integer giving the network packet MTU, in bytes. This is the maximum size of any datagram to send, but the implementation might receive a larger datagram. Default is 1400. 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 default network interface. Kempf, Guttman, Provan Expires 13 September 1998 [Page 8] Internet Draft Service Location API 13 March 1998 2.1.6. UA Configuration This section contains configuration parameters for the UA. net.slp.locale A RFC 1766 Language Tag [13] for the language locale. Setting this property causes the property value to become the default locale for SLP messages. Default is "en". 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. Default value is -1. DAs and SAs always return all results that match the request. This configuration value applies only to UAs, that filter incoming results and only return as many values as net.slp.maximumResults indicates. 2.1.7. Security The properties in this section allow security parameters to be configured. Key management is implementation dependent. net.slp.URLSignature A boolean indicating whether the SA should sign URLs. URLs are signed if true. Default is false. net.slp.attributeSignature A boolean indicating whether the SA should sign attributes. Attributes are signed if true. Default is false. 2.2. Serialized Registration File The serialized registration file contains a group of registrations that a DA or SA server (if one exists) registers when it starts up. These registrations are primarily for older service programs that do not internally support SLP and cannot be converted, and for portably exchanging registrations between SLP implementations. The character format of the registrations is required to be UTF8. Kempf, Guttman, Provan Expires 13 September 1998 [Page 9] Internet Draft Service Location API 13 March 1998 The syntax of the serialized registration file, in ABNF format [12], is as follows: ser-file = reg-list reg-list = reg / reg reg-list reg = creg / ser-reg creg = comment-line ser-reg comment-line = ( "#" / ";" ) 1*allchar newline ser-reg = url-props attr-list newline url-props = service-url sep lang [ exprop ] exprop = sep slist [ sep lifetime [ sep type ] ] sep = *WSP "," *WSP service-url = ;The registration's URL. See ; [15] for syntax. language = 2*3ALPHA [ "-" 1*ALPHA ] ;RFC 1766 Language Tag see [13]. lifetime = integer ; A positive 16-bit integer or -1 ; for permanent giving the lifetime ; of the registration. type string ; The service type name, see [14] ; and [15] for syntax. slist scope / scope sep slist scope = string ; See grammar of Section 2.1 ; and [14]. attr-list = attr-def / attr-def attr-list attr-def = attr / keyword keyword = attr-id attr = attr-id assgn-op attr-val-list newline assgn-op = *WSP "=" *WSP attr = ;Attribute id, see [14] for syntax. attr-val-list = attr-val / attr-val sep attr-val-list attr-val = ;Attribute value, see [14] for syntax. char = DIGIT / ALPHA / other ;'other' defined in section 2.1. allchar = char / WSP The syntax for attributes and attribute values requires escapes for special characters as specified in [14], in addition to nonASCII characters. DAs and SA servers that process serialized registrations MUST handle them exactly as if they were registered by an SA. If the optional scope list is present, the registations are made in the indicated scopes; otherwise, they are registered in the scopes with which the DA or SA server was configured through the net.slp.useScopes property. If any conflicts occur between the scope Kempf, Guttman, Provan Expires 13 September 1998 [Page 10] Internet Draft Service Location API 13 March 1998 list and the net.slp.useScopes property, an error message is issued. If the optional lifetime parameter is omitted, the registations are valid for the lifetime of the executing DA or SA server process. If the URL is not a service: URL and the optional service type is missing, the service type is taken as the URL's scheme. If the service type is present and the URL is a service: URL, it is ignored and a warning message is printed. 2.3. Proccessing Serialized Registration and Configuration Files Implementations are encouraged to make processing of configuration and serialized files as transparent as possible to clients of the API. At the latest, errors MUST be caught when the relevent configuration 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. Serialized registration file entries SHOULD be caught and reported when the file is loaded. Configuration file loading MUST be complete prior to the initiation of the first networking connection. Serialized registration MUST be complete before the DA accepts the first network request. 3. Binding Independent Implementation Considerations This section discusses a number of implementation considerations independent of language binding, with language specific notes where applicable. 3.1. Multithreading Implementations of both the C and Java APIs are required to make API calls thread-safe. Access to data structures shared between threads must be co-ordinated to avoid corruption or invalid access. One way to achieve this goal is to allow only one thread at a time in the implementing library. Performance in such an implementation suffers, however. Therefore, where possible, implementations are encouraged to allow multiple threads within the SLP API library. 3.2. Type Checking for Service Types Service templates [15] allow SLP registrations to be type checked for correctness. Implementations of the API are free to make use of Kempf, Guttman, Provan Expires 13 September 1998 [Page 11] Internet Draft Service Location API 13 March 1998 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 its 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. The APIs provide constants that can be used as URL life times for specifying that the registration should be permanent. 3.4. Configuration File Processing DAs, SAs and UAs processing the configuration file, and DAs and SA servers processing the serialized registration file are required to log any errors using whatever underlying error mechanism is appropriate for the platform. Examples include 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. An agent MUST NOT fail if a file format error occurs. 3.5. Attribute Types String encoded attribute values do not include explicit type information. All UA implementations and those SA and DA implementations that choose to support type checking should use the type rules described in [15] in order to convert from the string representation on the wire to an object typed appropriately. 3.6. Removal of Duplicates The UA implementation should always collate results to remove duplicates. This is especially important in the case of the SLP find attributes request for a service type and the find service type request when there are no DAs. The request is multicast to all SAs, and the results no doubt include duplicate values. Kempf, Guttman, Provan Expires 13 September 1998 [Page 12] Internet Draft Service Location API 13 March 1998 3.6.1. Character Set Encoding Characters in both C and Java are all represented in Unicode internally. On the wire, all characters are converted to UTF8. Inside URLs, characters that are not allowed by URL syntax [2] must be escaped according to the URL escape character convention. Strings that are included in SLP messages may include reserved characters and are escaped by convenience functions by the API. The character code used to encode the characters is UTF8. 3.7. Error Semantics All errors encountered processing SLP messages SHOULD be logged. An error is only returned to an API client if no successful replies were received from any SLP framework entity. If an error occured among one or several successful replies, then the error should be logged and the successful replies returned. Both the Java and C APIs contain language specific error code mechanisms for returning error information. The names of the error codes are consistent between the two implementations, however. The following error codes are returned from a remote agent (DA or SA): LANGUAGE_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. PARSE_ERROR The SLP message was rejected by a remote SLP agent. The API returns this error only when no information was retrieved, and at least one SA or DA indicated a protocol error. The data supplied through the API may be malformed or a may have been damaged in transit. INVALID_REGISTRATION The API may return this error if an attempt to register a service was rejected by all DAs because of a malformed URL or attributes. SLP does not return the error if at least one DA accepted the registration. Kempf, Guttman, Provan Expires 13 September 1998 [Page 13] Internet Draft Service Location API 13 March 1998 AUTHENTICATION_INVALID If the SLP framework supports authentication, this error arises when a remote DA fails to accept a registration. INTERNAL_ERROR A remote DA has failed for a reason other than a message sent to it by the UA or SA. INVALID_UPDATE An update for a nonexisting registration was issued. The following errors result from interactions with remote agents. AUTHENTICATION_FAILED If the SLP framework supports authentication, this error arises when a authentication on an SLP message received from a remote SLP agent failed. SCOPE_NOT_SUPPORTED The API returns this error if the UA or SA has been configured with net.slp.useScopes vector of scopes and the UA or SA request did not specify one or more of these allowable scopes, and no others. It may also be returned by a DA if the scope included in a request is not supported by a DA. The following errors are generated through a program interacting with the API implementation. They do not involve a remote SLP agent. NOT_IMPLEMENTED If an unimplemented feature is used, this error is returned. BUFFER_OVERFLOW This error is returned when the buffer passed down by the API client is too small to hold the results returned. NETWORK_INIT_FAILED If the network cannot initialize properly, this error is returned. Kempf, Guttman, Provan Expires 13 September 1998 [Page 14] Internet Draft Service Location API 13 March 1998 NETWORK_TIMED_OUT When no reply can be obtained in the time specified by the configured timeout interval, this error is returned. NETWORK_ERROR The failure of networking during normal operations causes this error to be returned. MEMORY_ALLOC_FAILED If the API fails to allocate memory, the operation is aborted and returns this. PARAMETER_BAD If a parameter passed into an interface is bad, this error is returned. INTERNAL_SYSTEM_ERROR A basic failure of the API causes this error to be returned. This occurs when a system call or library fails. The operation could not recover. The error code OK indicates that no error occured. Some error codes are handled differently in the Java API. These differences are discussed in Section 5. The errors OPTION_NOT_UNDERSTOOD, VER_NOT_SUPPORTED, and DA_BUSY_NOW should be handled internally and not surfaced to clients through the API. 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 structs. 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 makes user-supplied memory impossible. Kempf, Guttman, Provan Expires 13 September 1998 [Page 15] Internet Draft Service Location API 13 March 1998 To conform with standard C practice, all character strings passed to and returned through the API are null terminated, even though the SLP protocol does not use null terminated strings. Strings passed as parameters are Unicode but they may still be passed as a C string (a null terminated sequence of bytes.) Escaped characters are encoded as UTF8. The return value from each function is a long (a signed 32 bit integer). 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 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_NONE value should be used when creating a SLPSrvURL for SLPDereg() or SLPDelAttrs(), since, in all cases, the lifetime of the URL is irrelevant. The SLP_LIFETIME_PERMANENT parameter should be used with SLPReg() to register a URL for the lifetime of the SA process. 4.1.2. Error Codes 4.1.2.1. Synopsis Kempf, Guttman, Provan Expires 13 September 1998 [Page 16] Internet Draft Service Location API 13 March 1998 typedef enum { SLP_OK = 0, SLP_LANGUAGE_NOT_SUPPORTED = -1, SLP_PARSE_ERROR = -2, SLP_INVALID_REGISTRATION = -3, SLP_SCOPE_NOT_SUPPORTED = -4, SLP_AUTHENTICATION_INVALID = -6, SLP_AUTHENTICATION_FAILED = -7, SLP_INTERNAL_ERROR = -8, SLP_INVALID_UPDATE = -9; SLP_NOT_IMPLEMENTED = -17, SLP_BUFFER_OVERFLOW = -18, SLP_NETWORK_TIMED_OUT = -19, SLP_NETWORK_INIT_FAILED = -20, SLP_MEMORY_ALLOC_FAILED = -21, SLP_PARAMETER_BAD = -22, SLP_NETWORK_ERROR = -23, SLP_INTERNAL_SYSTEM_ERROR = -24 } SLPError ; 4.1.2.2. Description The SLPError enum contains error codes that are returned from API functions. 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 0 to 65535, or -1 to indicate permanent registration. If a nonnegative Kempf, Guttman, Provan Expires 13 September 1998 [Page 17] Internet Draft Service Location API 13 March 1998 integer, the s_lifetime field indicates the number of seconds that the advertisment should remain valid. The s_pcURL field may point to a character string containing either a standard URL or a service: URL. 4.2.2. SLPSrvAccessPt 4.2.2.1. Synopsis typedef struct srvaccesspt { char *s_pcSrvType; char *s_pcHost; int s_iPort; char *s_pcSrvPart; } SLPSrvAccessPt; 4.2.2.2. Description The SLPSrvAccessPt structure is filled in by the SLPParseSrvURL() function with information parsed from the URL. The fields correspond to different parts of the URL, as follows: s_pcSrvType A pointer to a character string containing the service type name, including naming authority. s_pcHost A pointer to a character string containing the host name or Internet address. s_iPort The port number, or zero if none. s_pcSrvPart The remainder of the URL, after the host and port part. The host and port should be sufficient to open a socket to the machine hosting the service, and the remainder of the URL should allow further differentiation of the service. Kempf, Guttman, Provan Expires 13 September 1998 [Page 18] Internet Draft Service Location API 13 March 1998 4.2.3. SLPHandle 4.2.3.1. Synopsis typedef void* SLPHandle; The SLPHandle type is returned by SLPOpen() and is a parameter to all SLP functions. It serves as a handle for all resources allocated on behalf of the process by the SLP library. The type is opaque, since the exact nature differs depending on the implementation. 4.2.4. SLPOpaque 4.2.4.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 the SLP Library 4.3.1. SLPOpen 4.3.1.1. Synopsis long SLPOpen(const char *pcLang, SLPHandle *phSLP); 4.3.1.2. Description Returns a SLPHandle handle in the phSLP parameter for the language locale passed in as the pcLang parameter. The handle encapsulates the language locale for SLP requests issued through the handle, and any other resources required by the implementation. SLP properties are not encapsulated by the handle, they are global. The return value of the function is zero for success, or an SLPError code if a failure occurs. Upon failure, the phSLP parameter is NULL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 19] Internet Draft Service Location API 13 March 1998 4.3.1.3. Parameters pcLang A pointer to an array of characters containing the RFC 1766 Language Tag [13] 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(SLPHandle hSLP); 4.3.2.2. Description Frees all resources associated with the handle. If the handle was invalid, the function returns silently. 4.3.2.3. Parameters SLPHandle A SLPHandle handle returned from a call to SLPOpen(). 4.4. Protocol API 4.4.1. SLPReg 4.4.1.1. Synopsis long SLPReg(SLPHandle hSLP, SLPSrvURL *pURL, const char* pcSrvType, const char *pcScopeList, const char *pcAttrs const char cNew); Kempf, Guttman, Provan Expires 13 September 1998 [Page 20] Internet Draft Service Location API 13 March 1998 4.4.1.2. Description Registers the URL in the pURL struct with the attribute list in pcAttr. The registration is done in scopes that are part of pcScopeList, a comma separated list of scopes. If the cNew flag is nonzero, then the registration is new (the SLP protocol FRESH flag is set) and the registration replaces any existing registrations. If the cNew flag is nonzero, then a new registration is created. If the cNew flag is zero, then an existing registration is updated. Rules for new and updated registrations can be found in [14]. Registrations and updates take place in the language locale of the hSLP handle. The pcScope parameter supplies a comma delimited list of scopes for the registration. This parameter MUST NOT be NULL or the empty string, "". The scopes in the scope list SHOULD be one or more of the scopes obtainable from SLPFindScopes(). If an unsupported scope is specified, a SLP_SCOPE_NOT_SUPPORTED error MAY be returned. If the net.slp.useScopes parameter has been configured, then the pcScope parameter MUST be a supported scope. 4.4.1.3. Parameters hSLP The language specific SLPHandle on which to register the advertisement. May not be NULL. pURL The URL to register. May not be NULL or the empty string. pcSrvType The service type. If pURL is a service: URL, then this parameter is ignored. May not be null. pcScopeList The comma separated list of scopes applying to the registration. May not be NULL. pcAttrs A comma separated list of attribute assignment expressions for the attributes of the advertisement. See [14] for a description of the list format. May not be NULL. Use empty string, "" for no attributes. Kempf, Guttman, Provan Expires 13 September 1998 [Page 21] Internet Draft Service Location API 13 March 1998 4.4.1.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.2. SLPDereg 4.4.2.1. Synopsys long SLPDereg(SLPHandle hSLP, SLPSrvURL *pURL); 4.4.2.2. Description Deregisters the advertisment for URL pURL in all scopes where the service is registered and all language locales, not just the locale of the SLPHandle. 4.4.2.3. Parameters hSLP The language specific SLPHandle to use for deregistering. May not be NULL. pURL The URL to deregister. May not be NULL. 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. SLPDelAttrs 4.4.3.1. Synopsys long SLPDelAttrs(SLPHandle hSLP, SLPSrvURL *pURL, const char *pcAttrs); Kempf, Guttman, Provan Expires 13 September 1998 [Page 22] Internet Draft Service Location API 13 March 1998 4.4.3.2. Description Delete the selected attributes in the locale of the SLPHandle. 4.4.3.3. Parameters hSLP The language specific SLPHandle to use for deleting attributes. May not be NULL. pURL The URL of the advertisement from which the attributes should be deleted. May not be NULL. pcAttrs A comma separated list of attribute ids for the attributes to deregister. See Section 9.8 in [14] for a description of the list format. May not be NULL. 4.4.3.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.4. SLPFindSrvTypes 4.4.4.1. Synopsis long SLPFindSrvTypes(SLPHandle hSLP, const char *pcNamingAuthority, const char *pcScopeList, char *pcSrvTypes, long lSize); The SLPFindSrvType() function issues an SLP service type request for service types in the scopes indicated by the pcScopeList 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 Kempf, Guttman, Provan Expires 13 September 1998 [Page 23] Internet Draft Service Location API 13 March 1998 types are returned independent of language locale, but only for services registered in one of scopes and for the indicated naming authority. If the net.slp.useScopes parameter has been configured, one or more of the configured scopes MUST be used. A SLP_SCOPE_NOT_SUPPORTED error MAY be returned otherwise. Otherwise, the client MAY use "DEFAULT" for the default scope. 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. "IANA" is not a valid naming authority name, and is ignored if included. The service type names are returned with the naming authority included, i.e. as: service-type "." naming-authority unless the naming authority is the default, in which case, just the service type name is returned. 4.4.4.2. Parameters hSLP The SLPHandle 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 comma separated list of scope names to search for service types. May not be NULL or the empty string, "". pcSrvTypes A pointer to an array of char in which the returned service types are placed. The string is formatted as a comma separated list of names. May not be NULL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 24] Internet Draft Service Location API 13 March 1998 lSize The number of array items in the ppcSrvTypes array. 4.4.4.3. Returns If no error occurs, the return value is the number of characters in the pcSrvTypes array. 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_BUFFER_OVERFLOW, but the array contents are usable. 4.4.5. SLPFindSrvs 4.4.5.1. Synopsis long SLPFindSrvs(SLPHandle hSLP, const char *pcServiceType, const char *pcScope, const char *pcSearchFilter, SLPSrvURL *pSrvURL, long lSize); 4.4.5.2. Description Issue the query for services on the language specific SLPHandle and return the results in pSrvURL. The parameters determine the results 4.4.5.3. Parameters hSLP The language specific SLPHandle on which to search for services. May not be NULL. pcServiceType The Service Type String for the request, such as can be discovered using SLPSrvTypes(). This could be, for example "service:printer:lpr" or "service:nfs". May not be NULL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 25] Internet Draft Service Location API 13 March 1998 pcScope A pointer to a char containing comma separated list of scope names. May not be NULL or the empty string, "". pcSearchFilter A query formulated of attribute pattern matching expressions in the form of a LDAPv3 Search Filter, see [11]. If this filter is empty, ie. "", all services of the requested type in the specified scopes are returned. May not be NULL. pSrvURL A pointer to an array of SLPSrvURL structs in which the returned URLs 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.5.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_BUFFER_OVERFLOW, but the array contents are usable. 4.4.6. SLPFindAttrs 4.4.6.1. Synopsis long SLPFindAttrs(SLPHandle hSLP, const char *pcURL, const char *pcScope, const char *pcAttrIds, char *pcAttrs, long lSize); Kempf, Guttman, Provan Expires 13 September 1998 [Page 26] Internet Draft Service Location API 13 March 1998 4.4.6.2. Description This function returns service attributes matching the attribute ids for the indicated full or partial URL. If pcURL is a complete URL, the attribute information returned is for that particular service in the language locale of the SLPHandle. If pcURL is a partial URL, then all attributes for the service type are returned regardless of the language of registration. The result is filtered with an SLP attribute request filter string parameter, the syntax of which is described in [14]. If the filter string is the empty string, i.e. "", all attributes are returned. 4.4.6.3. Parameters hSLP The language specific SLPHandle on which to search for attributes. May not be NULL. pcURL The full or partial URL. See [14] for partial URL syntax. May not be NULL. pcScope A pointer to a char containing comma separated list of scope names. May not be NULL or the empty string, "". pcAttrIds The filter string indicating which attribute values to return. Use empty string, "", to indicate all values. Wildcards matching all attribute ids having a particular prefix or suffix are also possible. See [14] 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. lSize The number of array items in the pcAttrs array. Kempf, Guttman, Provan Expires 13 September 1998 [Page 27] Internet Draft Service Location API 13 March 1998 4.4.6.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_BUFFER_OVERFLOW. 4.5. Miscellaneous Functions 4.6. SLPFindScopes 4.6.0.5. Synopsis long SLPFindScopes(SLPHandle hSLP, char** ppcScopes, long lSize); 4.6.0.6. Description Returns an array of strings with all available scope values. The list of scopes comes from a variety of sources: the configuration file's net.slp.useScopes property and the net.slp.DAAddresses property, DHCP, or through the DA discovery process. If there is any order to the scopes, preferred scopes are listed before less desirable scopes. There is always at least one string in the array, the default scope, "DEFAULT". 4.6.0.7. Parameters hSLP The SLPHandle 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. lSize The number of array items in the ppcScopes array. Kempf, Guttman, Provan Expires 13 September 1998 [Page 28] Internet Draft Service Location API 13 March 1998 4.6.0.8. Returns If no error occurs, the return value is the number of 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_BUFFER_OVERFLOW, but the array contents are usable. 4.7. SLPParseSrvURL 4.7.0.9. Synopsis long SLPParseSrvURL(SLPSrvURL* pSrvURL, SLPSrvAccessPt* pSrvAccessPt); 4.7.0.10. Description Parses the URL passed in as the argument into the service access point structure. If a parse error occurs, returns SLP_PROTOCOL_PARSE_ERROR. The character strings returned in the pSrvAccessPt structure should be freed with SLPFree(). If the URL has no service part, the s_pcSrvPart string should be the empty string, "", i.e. not NULL. If the s_pcURL field is not a service: URL, then the s_pcSrvType field in the returned data structure is the URL's scheme, which might not be the same as the service type under which the URL was registered. This function may be left unsupported by small-memory configurations. 4.7.0.11. Parameters pSrvURL A pointer to the SLPSrvURL structure containing the URL to parse. May not be NULL. pSrvAccessPt A pointer to the SLPSrvAccessPt structure to received the parsed URL. May not be NULL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 29] Internet Draft Service Location API 13 March 1998 4.7.0.12. Returns If no error occurs, the return value is the SLP_OK. Otherwise, if an error occurs, one of the SLPError codes is returned. If no memory is available to allocate the character strings, returns SLP_COULD_NOT_ALLOCATE_MEMORY. If a parse error occurs, returns SLP_PROTOCOL_PARSE_ERROR. 4.8. SLPFree 4.8.0.13. Synopsis void SLPFree(char* pcStorage); 4.8.0.14. Description Frees the storage pcStorage allocated by the SLP API. The only storage that needs freeing are the char* returned from SLPFindScopes(), the s_pcURL field char* returned as part of the SLPSrvURL structs returned from SLPFindSrvs(), and the strings returned in the SLPSrvAccessPt struct. 4.8.0.15. Parameters pcStorage A pointer to the storage allocated through the SLP API. Ignored if NULL. 4.8.1. SLPOpaqueToEscaped 4.8.1.1. Synopsis long SLPOpaqueToEscaped(const SLPOpaque opaque, const long lOSize, char *pcBuf, long lSize); Kempf, Guttman, Provan Expires 13 September 1998 [Page 30] Internet Draft Service Location API 13 March 1998 4.8.1.2. Description This converts a buffer into an escaped sequence of bytes. The escape sequence is always three times as long as the opaque buffer to encode, plus five, as each byte is encoded as "\" HEXDIGIT HEXDIGIT, with the first escaped sequence being `\255`. NonUTF8 bytes and reserved characters are converted into escapes, other bytes become UTF8 characters. 4.8.1.3. Parameters opaque The binary buffer to convert. lOSize The number of bytes in the opaque. pcBuf A client supplied buffer into which the null terminated escaped value is put. May not be NULL. lSize The number of array elements in the pcBuf array. Must be (3 * lOSize) + 5. 4.8.1.4. Returns Returns the number of characters in pcBuf or SLP_BUFFER_OVERFLOW error if the buffer overflows. 4.8.2. SLPEscapedToOpaque 4.8.2.1. Synopsis long SLPEscapedToOpaque(const char *pcEscaped, SLPOpaque opaque, long lSize); Kempf, Guttman, Provan Expires 13 September 1998 [Page 31] Internet Draft Service Location API 13 March 1998 4.8.2.2. Description Convert an escaped string encoding of a SLPOpaque into binary format. The buffer in SLPOpaque must be at least one third the length of the string pointed to by pcEscaped. 4.8.2.3. Parameters pcEscaped The escaped 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. Must be at least the length of the string pointed to by pcEscaped divided by 3. 4.8.3. SLPEscape 4.8.3.1. Synopsis long SLPEscape(const char *pcEscapee char *pcBuf, long lSize); 4.8.3.2. Description Escape any reserved characters in pcEscapee into the escape format described in [14]. The reserved characters are encoded as UTF8. 4.8.3.3. Parameters pcEscapee Null terminated string to escape. May not be NULL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 32] Internet Draft Service Location API 13 March 1998 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.8.3.4. Returns If no error, returns the number of bytes in pcBuf. If an error ocurs, returns SLP_BUFFER_OVERFLOW error if the buffer overflows. 4.8.4. SLPUnescape 4.8.4.1. Synopsis long SLPUnescape(const char* pcUnescapee char* pcBuf, long lSize); 4.8.4.2. Description Unescape any escapable characters in pcUnescapee out of the escape format described in [14]. 4.8.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. Kempf, Guttman, Provan Expires 13 September 1998 [Page 33] Internet Draft Service Location API 13 March 1998 4.8.4.4. Returns If no error, returns the number of bytes in pcBuf. If an error ocurs, returns SLP_BUFFER_OVERFLOW error if the buffer overflows. 4.8.5. SLPGetProperty 4.8.5.1. Synopsis const char* SLPGetProperty(const char* pcName); 4.8.5.2. Description Returns the value of the corresponding SLP property name, or NULL if none. 4.8.5.3. Parameters pcName Null terminated string with the property name, from Section 2.1. May not be NULL. 4.8.5.4. Returns If no error, returns a pointer to the property value. If the property was not set, returns the empty string, "". If an error occurs, returns NULL. The returned string should NOT be freed. 4.8.6. SLPSetProperty 4.8.6.1. Synopsis void SLPSetProperty(const char *pcName, const char *pcValue); Kempf, Guttman, Provan Expires 13 September 1998 [Page 34] Internet Draft Service Location API 13 March 1998 4.8.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. 4.8.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.9. Implementation Notes 4.9.1. Syntax for String Parameters Query strings, attribute registration lists, attribute deregistration lists, and attribute selection lists follow the syntax described in [14] for the appropriate requests. The API directly reflects the strings passed in from clients into protocol requests, and directly reflects out strings returned from protocol replies to clients. As a consequence, clients are responsible for formatting request strings, including escaping and converting opaque values to escaped byte encoded strings. Similarly, on output, clients are required to unescape strings and convert escaped string encoded opaques to binary. Utility functions are included to help in the process. 4.9.2. 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 must be returned. If any parameter is NULL and is required to be nonNULL, SLP_PARAMETER_BAD is returned. Kempf, Guttman, Provan Expires 13 September 1998 [Page 35] Internet Draft Service Location API 13 March 1998 4.9.3. System Properties The system properties established in the configuration file are accessable through the SLPGetProperty() and SLPSetProperty() functions. The SLPSetProperty() function only modifies properties in the running process, not in the configuration file. 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 that are not of concern to individual agents. If changes are required, system administrators should modify the configuration file. 4.9.4. Memory Management Character strings returned via the SLPFindSrvs(), SLPFindScopes(), and SLPParseSrvURL() 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.10. Examples 4.10.1. Discovering one's mailbox A POP3 server might register itself with the SLP framework. The attributes it registers are "USER", a comma delimited list of all users whose mail is available through the POP3 server. The POP3 server code could be the following: SLPHandle slph; long err = SLPOpen("en", &slph) /* Create an English SLPHandle */ if( sh == NULL ) ; /* Deal with error. */ /* Create the service: URL and attribute parameters. */ SLPSrvURL surl = { "service:pop3://mail.netsurf.de", /* the URL */ SLP_LIFETIME_DEFAULT }; /* default lifetime */ Kempf, Guttman, Provan Expires 13 September 1998 [Page 36] Internet Draft Service Location API 13 March 1998 const char *pcScopeList = "default,engineering"; const char *pcAttrs = "(user=sally,sue,sandra,zsuzsa)" err = SLPReg(sh,&surl,pcScopeList,pcAttrs); if (err < 0 ) ; /*Deal with error.*/ The POP3 client may locate the server for the user: /* * The client calls SLPOpen(), exactly as above. */ const char *pcSrvType = "service:pop3"; /* the service type */ const char *pcScopeList = "default"; /* the scope */ const char *pcFilter = "(user=sue)"; /* the search filter */ SLPSrvURL surl; err = SLPFindSrvs(sh,pcSrvType,pcScopeList,pcFilter,&surl,1); if( err < 0 ) { /* Deal with error. */ } else { SLPSrvAccessPt pSrvAccessPt; err = SLPParseSrvURL(&surl, &pSrvAccessPt); if (err < 0) { /* Deal with error. */ } else { /* get the server's address */ struct hostent *phe = gethostbyname(pSrvAccessPt.s_pcHost); /* use hostname in pSrvAccessPt to connect to the POP3 server * . . . */ SLPFree(pSrvAccessPt.s_pcSrvType); /* Free the pSrvAccessPt storage */ SLPFree(pSrvAccessPt.s_pcHost); SLPFree(pSrvAccessPt.s_pcSrvPart); } Kempf, Guttman, Provan Expires 13 September 1998 [Page 37] Internet Draft Service Location API 13 March 1998 SLPFree(surl.s_pcURL); /* Free the surl storage */ A client that wanted to discover all the users receiving mail at the server could do so with the following query: /* * The client calls SLPOpen(), exactly as above. We assume the * service: URL was retrieved into surl. */ const char *pcScopeList = "default"; /* the scope */ const char *pcAttrFilter = "use"; /* the attribute filter */ char pcAttrVals[MAXBUF]; /* the return buffer */ err = SLPFindSrvs(sh,surl.s_pcURL,pcScopeList,pcAttrFilter,pcAttrVals,MAXBUF); if( err < 0 ) { /* Deal with error. */ } else { /* parse the returned attribute values */ } 5. Java Language Binding 5.1. Introduction The Java API is designed to model the various SLP entities in classes and objects. APIs are provided for SA, UA, and service type template access capabilities. The ServiceLocationManager class contains methods that return instances of objects implementing SA and UA capability. Each of these is modelled in an interface. The Locator interface provides UA capability and the Advertiser interface provides SA capability. The TemplateRegistry abstract class 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. A concrete subclass instance of TemplateRegistry is returned by a class method. 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 suffix "net.slp". Thus, the name for a Kempf, Guttman, Provan Expires 13 September 1998 [Page 38] Internet Draft Service Location API 13 March 1998 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. 5.2. Exceptions and Errors Most parameters to API methods are required to be nonnull. The API description indicates if a null parameter is acceptable, or if other restrictions constrain a parameter. 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, derived from RuntimeException, is unchecked by the compiler. Clients should thus be careful to include try/catch blocks for it if the relevent parameters could be erroneous. Standard Java practice is to encode every exceptional condition as a seperate subclass of Exception. Because of the relatively high cost in code size of Exception subclasses, the API contains only a single Exception subclass with different conditions being determined by an integer error code property. A subset, appropriate to Java, of the error codes described in Section 3 are available as constants on the ServiceLocationException class. The subset excludes error codes such as MEMORY_ALLOC_FAILED and BUFFER_OVERFLOW, which are not appropriate for Java. 5.2.1. Class ServiceLocationException 5.2.1.1. Synopsis public class ServiceLocationException extends Exception 5.2.1.2. Description The ServiceLocationException class is thrown by all methods when exceptional conditions occur in the SLP framework. The error Kempf, Guttman, Provan Expires 13 September 1998 [Page 39] Internet Draft Service Location API 13 March 1998 code property determines the exact nature of the condition, and an optional message may provide more information. 5.2.1.3. Fields public static final short OK; public static final short LANGUAGE_NOT_SUPPORTED; public static final short PARSE_ERROR; public static final short INVALID_REGISTRATION; public static final short SCOPE_NOT_SUPPORTED; public static final short AUTHENTICATION_INVALID; public static final short AUTHENTICATION_ABSENT; public static final short INTERNAL_ERROR; public static final short INVALID_UPDATE; public static final short NOT_IMPLEMENTED; public static final short NETWORK_INIT_FAILED; public static final short NETWORK_TIMED_OUT; public static final short NETWORK_ERROR; public static final short INTERNAL_SYSTEM_ERROR; 5.2.1.4. Instance Methods public short getErrorCode() Return the error code. The error code takes on one of the static field values. 5.3. Basic Data Structures 5.3.1. Class ServiceLocationAttribute 5.3.1.1. Synopsis public final class ServiceLocationAttribute extends Object implements Serializable Kempf, Guttman, Provan Expires 13 September 1998 [Page 40] Internet Draft Service Location API 13 March 1998 5.3.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.3.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, id is the empty string, or the Vector contents has a type mismatch. 5.3.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. Kempf, Guttman, Provan Expires 13 September 1998 [Page 41] Internet Draft Service Location API 13 March 1998 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. Any reserved characters as specified in [14] are escaped using UTF8 encoding. public final Vector getEscapedValues() Returns a Vector containing the escaped values as Strings, suitable for inclusion in a query. Any reserved characters as specified in [14] are escaped using UTF8 encoding. If the values are byte arrays, then the escaped strings begin with the nonUTF8 sequence `\255` and nonUTF8 bytes and bytes encoding reserved characters are escaped, while bytes corresponding to UTF8 characters become characters. public boolean equals(Object o) Overrides Object.equals(). public String toString() Overrides Object.toString(). 5.3.2. Class ServiceURL 5.3.2.1. Synopsis public class ServiceURL extends Object implements Serializable Kempf, Guttman, Provan Expires 13 September 1998 [Page 42] Internet Draft Service Location API 13 March 1998 5.3.2.2. Description The ServiceURL object models the advertised SLP service URL. It can be either a service: URL or a regular URL. These objects are returned from service lookup requests, and describe the registered services. This class should be a subclass of java.net.URL but can't since that class is final. 5.3.2.3. Class Variables public static final int NO_PORT Indicates that no port information is required or was returned for this URL. public static final short LIFETIME_NONE Indicates that the URL has a zero lifetime. public static final short LIFETIME_DEFAULT The default URL lifetime. public static final short LIFETIME_PERMANENT The service should last as long as the registering application continues in execution. 5.3.2.4. Constructors public ServiceURL(String URL,short lifetime) Construct a service URL object having the specified lifetime. Parameters: Kempf, Guttman, Provan Expires 13 September 1998 [Page 43] Internet Draft Service Location API 13 March 1998 URL The URL as a string. Must be either a service: URL or a valid regular URL. lifetime The service advertisement lifetime in seconds. This value may be 0x0001 to 0xFFFF, or one of the special life time field values. 5.3.2.5. Methods public final String getServiceType() Returns the service type name. If the URL was a regular URL, then the service type is the scheme name, unless otherwise set. public final String getNamingAuthority() Returns the naming authority for the ServiceURL. An empty string means the default. If the URL was a regular URL, then the service type name is the default unless otherwise set. public final void setServiceType(String type,String namingAuthority) throws ServiceLocationException Set the service type name and naming authority. Ignored if the URL is a service: URL. Parameters: type The service type name. namingAuthority The naming authority name. public final String getHost() Kempf, Guttman, Provan Expires 13 September 1998 [Page 44] Internet Draft Service Location API 13 March 1998 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 short getLifetime() Returns the service advertisement lifetime. public final boolean equals(Object obj) Compares the object to the ServiceURL and returns true if the two are the same. Lifetimes are not compared. Overrides Object.equals(). public final String toString() Returns formatted string with the URL. Overrides Object.toString(). 5.4. SLP Access Interfaces 5.4.1. Interface Advertiser 5.4.1.1. Synopsis public interface Advertiser Kempf, Guttman, Provan Expires 13 September 1998 [Page 45] Internet Draft Service Location API 13 March 1998 5.4.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.4.1.3. Instance Methods public abstract Locale getLocale() Return the language locale with which this object was created. public abstract void register(ServiceURL URL, Vector scopes, Vector attributes) throws ServiceLocationException Register a new service with SLP. Parameters: URL The URL for the service. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. attributes A vector of ServiceLocationAttribute objects describing the service. public abstract void deregister(ServiceURL URL) throws ServiceLocationException Kempf, Guttman, Provan Expires 13 September 1998 [Page 46] Internet Draft Service Location API 13 March 1998 Deregister a service from the SLP framework. This has the effect of deregistering the service from every language locale and scope under which it was registered. Parameters: URL The URL for the service. public abstract void addAttributes(ServiceURL URL, Vector scopes, Vector attributes) throws ServiceLocationException Update the registration by adding the given attributes. Parameters: URL The URL for the service. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. attributes A Vector of ServiceLocationAttribute objects to add to the existing registration. public abstract void deleteAttributes(ServiceURL URL, Vector attributeIds) throws ServiceLocationException Delete the attributes from a URL in all scopes for the locale with which the Advertiser was created. Parameters: Kempf, Guttman, Provan Expires 13 September 1998 [Page 47] Internet Draft Service Location API 13 March 1998 URL The URL for the service. attributeIds A vector of Strings indicating the ids of the attributes to remove. Use null to indicate all attributes. 5.4.2. Interface Locator 5.4.2.1. Synopsis public interface Locator 5.4.2.2. Description The Locator is the UA interface, allowing clients to query the SLP framework about existing service types, services instances, and about the attributes of an existing service instance or service type. Queries for services and attributes are made in the locale with which the Locator was created, queries for service types are independent of locale. 5.4.2.3. Instance Methods public abstract Locale getLocale() Return the language locale with which this object was created. public abstract Vector findServiceTypes(String namingAuthority, Vector scopes) throws ServiceLocationException Returns a Vector Strings giving known service types for the supplied scopes 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: Kempf, Guttman, Provan Expires 13 September 1998 [Page 48] Internet Draft Service Location API 13 March 1998 service-type "." naming-authority Parameters: namingAuthority The naming authority. Use "" for the default naming authority and "*" for all naming authorities. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. public abstract Vector findServices(String serviceType, String namingAuthority, Vector scopes, String searchFilter) 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. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. serviceType The service type of the service requested. Kempf, Guttman, Provan Expires 13 September 1998 [Page 49] Internet Draft Service Location API 13 March 1998 searchFilter An LDAPv3 [11] string encoded query. If the filter is empty, ie. "", all services of the requested type in the specified scopes are returned. public abstract Vector findAttributes(ServiceURL URL, Vector scopes, Vector attributeIds) throws ServiceLocationException For the URL and scope, return a Vector of ServiceLocationAttribute objects whose ids 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 URL for which the attributes are desired. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. attributeIds A Vector of String patterns identifying the desired attributes. An empty vector means return all attributes. As described in [14], the patterns may include wildcards to match all prefixes or suffixes. The patterns may include reserved characters. public abstract Vector findAttributes(String serviceType, String namingAuthority, Vector scopes, Vector attributeIds) throws ServiceLocationException Kempf, Guttman, Provan Expires 13 September 1998 [Page 50] Internet Draft Service Location API 13 March 1998 For the type and scope, return a Vector of all ServiceLocationAttribute objects whose ids 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. namingAuthority The naming authority for the type. Use the empty string, "", for default. scopes A Vector of scope names. Scope Strings SHOULD be selected from the results of a findScopes() API invocation. Use "DEFAULT" for the default scope. attributeIds A Vector of String patterns identifying the desired attributes. An empty vector means return all attributes. As described in [14], the patterns may include wildcards to match all prefixes or suffixes. The patterns may include reserved characters. 5.5. The Service Location Manager 5.5.1. Class ServiceLocationManager 5.5.1.1. Synopsis public class ServiceLocationManager extends Object 5.5.1.2. Description The ServiceLocationManager manages access to the service location framework. Clients obtain the Locator and Advertiser objects for UA and SA, and a Vector of known scope names from the ServiceLocationManager. Kempf, Guttman, Provan Expires 13 September 1998 [Page 51] Internet Draft Service Location API 13 March 1998 5.5.1.3. Class Methods public abstract Vector findScopes() Returns an Vector of strings with all available scope names. The list of scopes comes from a variety of sources: the configuration file's net.slp.useScopes property and the net.slp.DAAddresses property, DHCP, or through the DA discovery process. If there is any order to the scopes, preferred scopes are listed before less desirable scopes. There is always at least one string in the Vector, the default scope, "DEFAULT". public static Locator getLocator(Locale locale) 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 used if null. 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. Parameters: locale The language locale of the Advertiser. The default locale is used if null. Kempf, Guttman, Provan Expires 13 September 1998 [Page 52] Internet Draft Service Location API 13 March 1998 5.6. Service Template Introspection 5.6.1. Abstract Class TemplateRegistry 5.6.1.1. Synopsis public abstract class TemplateRegistry 5.6.1.2. Description Subclasses of the TemplateRegistry abstract class provide access to service location templates [15]. Classes implementing TemplateRegistry perform a variety of functions. They manage the registration and access of service type template documents. They create attribute verifiers from service templates, for verification of attributes and introspection on template documents. Note that clients of the Advertiser are not required to verify attributes before registering. 5.6.1.3. Class Methods public static TemplateRegistry getTemplateRegistry(); Returns the distinguished TemplateRegistry object for performing operations on and with service templates. 5.6.1.4. Instance Methods public abstract void registerServiceTemplate(String serviceType, String documentURL, Locale locale, String version) throws ServiceLocationException Register the service template with the template registry. Parameters: Kempf, Guttman, Provan Expires 13 September 1998 [Page 53] Internet Draft Service Location API 13 March 1998 serviceType The service type name, including naming authority. documentURL The URL of the template document. locale A Locale object containing the language locale of the template. version The version number of template document. public abstract void deregisterServiceTemplate(String serviceType, Locale locale, String version) throws ServiceLocationException Deregister the template for the service type. Parameters: serviceType The service type name, including naming authority. locale A Locale object containing the language locale of the template. version A String containing the version number. Use null to indicate the latest version. public abstract String findTemplateURL(String serviceType, Locale locale, String version) throws ServiceLocationException Kempf, Guttman, Provan Expires 13 September 1998 [Page 54] Internet Draft Service Location API 13 March 1998 Returns the URL for the template document. Parameters: serviceType A String containing the name of the service type, including naming authority. locale A Locale object containing the language locale of the template. version A String containing the version number. Use null to indicate the latest version. public abstract ServiceLocationAttributeVerifier attributeVerifier(String documentURL) throws ServiceLocationException Reads the template document URL and returns an attribute verifier for the service type. The attribute verifier can be used for verifying that registration attributes match the template, and for introspection on the template definition. Parameters: documentURL A String containing the template document's URL. 5.6.2. Interface ServiceLocationAttributeVerifier 5.6.2.1. Synopsis public interface ServiceLocationAttributeVerifier Kempf, Guttman, Provan Expires 13 September 1998 [Page 55] Internet Draft Service Location API 13 March 1998 5.6.2.2. Description The ServiceLocationAttributeVerifier provides access to service 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.6.2.3. Instance Methods public abstract String getServiceType() 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 RFC 1766 [13] Language Tag locale of the template. description A natural language description of the service in the language of the language locale. url-syntax An ABNF [12] description for the of the service type's URL. Kempf, Guttman, Provan Expires 13 September 1998 [Page 56] Internet Draft Service Location API 13 March 1998 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 has the actual values of the template attributes. public abstract Hashtable getAttributeDescriptors() Returns a Hashtable allowing introspection on the attribute definition in the service template. The Hashtable has the attribute ids 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. public abstract void verifyAttribute( ServiceLocationAttribute attribute) throws ServiceLocationException Verify that the attribute matches the template definition. If the attribute doesn't match, ServiceLocationException is thrown with the error code as ServiceLocationException.PARSE_ERROR. Parameters: attribute The ServiceLocationAttribute object to be verified. public abstract void verifyRegistration( Vector attributeVector) throws ServiceLocationException 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 Kempf, Guttman, Provan Expires 13 September 1998 [Page 57] Internet Draft Service Location API 13 March 1998 definitions. If the attributes don't match, ServiceLocationException is thrown with the error code as ServiceLocationException.PARSE_ERROR Parameters: attributeVector A Vector of ServiceLocationAttribute objects for the registration. 5.6.3. Interface ServiceLocationAttributeDescriptor 5.6.3.1. Synopsis public interface ServiceLocationAttributeDescriptor 5.6.3.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 template. This information is primarily for GUI tools. Programmatic attribute verification should be done through the ServiceLocationAttributeVerifier. 5.6.3.3. Instance Methods public abstract String getId() Return a String containing the attribute's id. public abstract String getValueType() Return a String containing the fully package-qualified Java type of the attribute. SLP types are translated into Java types as follows: Kempf, Guttman, Provan Expires 13 September 1998 [Page 58] Internet Draft Service Location API 13 March 1998 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. 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. public abstract boolean getIsMultivalued() Returns true if the "M" flag is set. Kempf, Guttman, Provan Expires 13 September 1998 [Page 59] Internet Draft Service Location API 13 March 1998 public abstract boolean getIsOptional() Returns true if the "O"" flag is set. public abstract boolean getRequiredAttribute() Returns true if the "X"" flag is set, indicating that the attribute SHOULD be included in an any Locator.findServices() request search filter. 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.7. Implementation Notes 5.7.1. Client Side Syntax Checking The syntax of scope names, service type names, naming authority names, and URLs is described in [14] and [15]. 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 ids 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. 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 Kempf, Guttman, Provan Expires 13 September 1998 [Page 60] Internet Draft Service Location API 13 March 1998 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 net.slp.locale is the only SLP system property that a client of the API would routinely override. 5.7.3. 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 that are not of concern to individual agents. If changes are required, system administrators should modify the configuration file. 5.7.4. Implementing register() and addAttributes() Advertiser.register() indicates a new registration has taken place, replacing previous registrations for the same URL and locale. The SLPv2 'FRESH' flag is set in the header of the registration message, when it is forwarded to DAs to reflect this behavior. Advertiser.addAttributes(), on the other hand, does not replace the previous registration, but rather adds to it as described in Section 5.4.1. The SLPv2 'FRESH' flag is NOT set in the header of the registration message, when it is forwarded to DAs. 5.7.5. Multithreading Thread-safe operation are relatively easy to achieve in Java. By simply making each method in the classes implementing the Locator and Advertiser interfaces synchronized, and by synchronizing access to any shared data structures within the class the Locator and Advertiser interfaces are made safe. Kempf, Guttman, Provan Expires 13 September 1998 [Page 61] Internet Draft Service Location API 13 March 1998 5.7.6. Scope All services advertised in SLPv2 are advertised with a scope. A UA must issue requests with a scope. If the client doesn't care what scope to use, then the scope name "DEFAULT" should be used. 5.7.7. Modular Implementations While, at first glance, the API may look rather heavyweight, the design has been carefully arranged so that modular implementations that 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() and ServiceLocationManager.getAdvertiser() operations are interfaces, and because the objects returned through those interfaces are in the set of base data structures, an implementation is free to omit either UA or SA capability by simply returning null from the instance creation operation if the classes implementing the missing function is cannot be dynamically linked. API clients are encouraged to check for such a contingency, and to signal an exception if it occurs. Similarly, the TemplateRegistry class can simply be omitted from an implementation that only supports UA and/or SA clients. In this way, the API implementation can be taylored for the particular memory requirements at hand. In addition, if an implementation only supports the minimal subset of SLP [14], the unsupported Locator and Advertiser interface operations can throw an exception with ServiceLocationException.NOT_IMPLEMENTED as the error code. This supports better source portablity between low and high memory platforms. 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"); Kempf, Guttman, Provan Expires 13 September 1998 [Page 62] Internet Draft Service Location API 13 March 1998 tr = TemplateRegistry.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 = ServiceLocationManager.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 = new ServiceURL( "service:printer:lpr://printshop/color2", ServiceURL.LIFETIME_PERMANENT); try { //Register the printer in all scopes. adv.register(printerURL, scopes, attributes); //If the template registry is available, // register the printer's template. if( tr != null ) { tr.registerServiceTemplate( "service:printer", "http://shop.arv/printer/printer-lpr.slp", new Locale("en",""), "1.0"); Kempf, Guttman, Provan Expires 13 September 1998 [Page 63] Internet Draft Service Location API 13 March 1998 } } 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 advertisements: Locator loc = null; TemplateRegistry tr = null; try { loc = ServiceLocationManager.getLocator("en"); } catch( ServiceLocationException ex ) { } //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. String query = "(& (marker-type=CMYK) (resolution=600))"; //Get scopes. Vector scopes = ServiceLocationManager.findScopes(); try { services = loc.findServices("service:printer","",scopes,query); } catch { } //Deal with error. if (services.size() > 0) { //Printers can now be used. ServiceURL surl = (ServiceURL) services.elementAt(0); Socket sock = new Socket(surl.getHost, surl.getPort()); // Use the Socket... Kempf, Guttman, Provan Expires 13 September 1998 [Page 64] Internet Draft Service Location API 13 March 1998 } 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 UTF8 character set [10]. The attribute information associated with the service URL may be expressed in any character set, and in any language. See [15] for attribute internationalization guidelines. 6.2. Character Set Encoding Configuration and serialized registration files are encoded in the UTF8 character set [10]. This is fully compatible with ASCII character values. As it may be impossible to pass multibyte UTF8 characters through the local platform's C file interface interface, an escaping convention has been provided: UTF8 bytes are directly encoded in an escape sequence where each byte is rendered as "\" HEXDIGIT HEXDIGIT. At the API level, the character encoding is specified to be Unicode. Unicode is the default in Java. C implementations need to supply Unicode support in a platform specific manner. 6.3. Language Tagging All SLP requests and registrations are tagged to indicate in which language the strings included are encoded. This allows multiple languages to be supported. It also presents the possibility that error conditions result when a request is made in a language that is not supported. In this case, an error is only returned when there is data available, but not obtainable in the language requested. The dialect portion of the Language Tag is used on 'best effort' basis for matching strings by SLP. Dialects that match are prefered over those which don't. Dialects that do not match will not prevent string matching or comparisons to occur. Kempf, Guttman, Provan Expires 13 September 1998 [Page 65] Internet Draft Service Location API 13 March 1998 7. Security Considerations SLP makes use of an existing host based authentication framework once it becomes available as an Internet Standard. [5] An adversary could delete valid service advertisements, provide false service information and deny UAs knowledge of existing services unless the mechanisms in SLP for authenticating SLP messages are used. These mechanisms allow DA Adverts, Service URLs and Service Attributes to be verified using digital cryptography. For this reason, all SLP agents SHOULD be configured to use protected scopes and DA Advertisement verifying cryptographic keys. See [14] for a description of how these mechanisms work. Kempf, Guttman, Provan Expires 13 September 1998 [Page 66] Internet Draft Service Location API 13 March 1998 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] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service Location Protocol. RFC 2165, July 1997. [4] IANA IANA Character Set Registry [5] R. Atkinson Security Architecture for the Internet RFC 1825 July 1995 [6] J. Linn Generic Security Application Program Interface, Version 2 A work in progress November 1996 [7] A. Freier, P. Karlton, P. Kocher The SSL Protocol, Version 3.0 A work in progress November 1996 [8] Geneva ISO Code for the representation of names of languages ISO 639:1998 (E/F) 1998 [9] 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. [10] F. Yerfeau UTF-8, a transformation format of ISO 10646. RFC 2279 January 1998. [11] T. Howes The String Representation of LDAP Search Filters RFC 2254 December 1997. [12] D. Crocker and P Overell. Augmented BNF for Syntax Specifications: ABNF. RFC 2234 November 1997. [13] H. Alvestrand. Tags for the Identification of Languages. RFC 1766 March 1995. [14] E. Guttman, C. Perkins, J. Veizades, and M. Day. Service Location Protocol. draft-ietf-svrloc-protocol-v2-04.txt A work in progress March 1998. Kempf, Guttman, Provan Expires 13 September 1998 [Page 67] Internet Draft Service Location API 13 March 1998 [15] E. Guttman, C. Perkins, J. Kempf Service Templates and service: Schemes draft-ietf-svrloc-service-scheme-09.txt A work in progress March 1998. [16] N. Borenstein and N. Freed. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. RFC 2045 September 1996. Kempf, Guttman, Provan Expires 13 September 1998 [Page 68] Internet Draft Service Location API 13 March 1998 Authors' Addresses Questions about this memo can be directed to: James Kempf Erik Guttman Don Provan Sun Microsystems Sun Microsystems Novell, Inc. 901 San Antonio Rd. Bahnstr. 2 2180 Fortune Drive Palo Alto, CA, 94303 74915 Waibstadt San Jose, CA, 94303 USA Germany USA +1 650 786 5890 +49 7263 911 701 +1 408 577 8440 +1 650 786 6445 (fax) james.kempf@sun.com erik.guttman@sun.com donp@novell.com Kempf, Guttman, Provan Expires 13 September 1998 [Page 69]