diff options
Diffstat (limited to 'doc/rfc/rfc2614.txt')
| -rw-r--r-- | doc/rfc/rfc2614.txt | 5099 |
1 files changed, 5099 insertions, 0 deletions
diff --git a/doc/rfc/rfc2614.txt b/doc/rfc/rfc2614.txt new file mode 100644 index 0000000..ef27176 --- /dev/null +++ b/doc/rfc/rfc2614.txt @@ -0,0 +1,5099 @@ + + + + + + +Network Working Group J. Kempf +Request for Comments: 2614 E. Guttman +Category: Informational Sun Microsystems + June 1999 + + + An API for Service Location + +Status of This Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Abstract + + The Service Location Protocol (SLP) provides a new way for clients to + dynamically discovery network services. With SLP, it is simple to + offer highly available services that require no user configuration or + assistance from network administrators prior to use. This document + describes standardized APIs for SLP in C and Java. The APIs are + modular and are designed to allow implementations to offer just the + feature set needed. In addition, standardized file formats for + configuration and serialized registrations are defined, allowing SLP + agents to set network and other parameters in a portable way. The + serialized file format allows legacy services to be registered with + SLP directory agents in cases where modifying the legacy service + program code is difficult or impossible, and to portably exchange a + registration database. + +Table of Contents + + 1. Introduction 4 + 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . 4 + 2. File Formats 7 + 2.1. Configuration File Format . . . . . . . . . . . . . . 8 + 2.1.1. DA configuration . . . . . . . . . . . . . . 9 + 2.1.2. Static Scope Configuration . . . . . . . . . . 9 + 2.1.3. Tracing and Logging . . . . . . . . . . . . . 11 + 2.1.4. Serialized Proxy Registrations . . . . . . . . 11 + 2.1.5. Network Configuration Properties . . . . . . . 12 + 2.1.6. SA Configuration . . . . . . . . . . . . . . . 14 + 2.1.7. UA Configuration . . . . . . . . . . . . . . . 14 + 2.1.8. Security . . . . . . . . . . . . . . . . . . 15 + 2.2. Multihomed Machines. . . . . . . . . . . . . . . . . . 16 + 2.3. Serialized Registration File . . . . . . . . . . . . . 16 + + + + +Kempf & Guttman Informational [Page 1] + +RFC 2614 Service Location API June 1999 + + + 2.4. Processing Serialized Registration and Configuration + Files . . . . . . . . . . . . . . . . . . . . . . . . 18 + 3. Binding Independent Implementation Considerations 18 + 3.1. Multithreading . . . . . . . . . . . . . . . . . . . . 18 + 3.2. Asynchronous and Incremental . . . . . . . . . . . . . 19 + 3.3. Type Checking for Service Types. . . . . . . . . . . . 19 + 3.4. Refreshing Registrations . . . . . . . . . . . . . . . 19 + 3.5. Configuration File Processing . . . . . . . . . . . . 19 + 3.6. Attribute Types . . . . . . . . . . . . . . . . . . . 20 + 3.7. Removal of Duplicates . . . . . . . . . . . . . . . . 20 + 3.8. Character Set Encoding . . . . . . . . . . . . . . . . 20 + 3.9. Error Semantics . . . . . . . . . . . . . . . . . . . 20 + 3.10. Modular Implementations . . . . . . . . . . . . . . . 24 + 3.11. Handling Special Service Types . . . . . . . . . . . . 24 + 3.12. Scope Discovery and Handling . . . . . . . . . . . . . 24 + 4. C Language Binding 25 + 4.1. Constant Types . . . . . . . . . . . . . . . . . . . . 26 + 4.1.1. URL Lifetimes. . . . . . . . . . . . . . . . . 26 + 4.1.2. Error Codes. . . . . . . . . . . . . . . . . . 26 + 4.1.3. SLPBoolean . . . . . . . . . . . . . . . . . . 27 + 4.2. Struct Types . . . . . . . . . . . . . . . . . . . . 28 + 4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . 28 + 4.2.2. SLPHandle . . . . . . . . . . . . . . . . . . 29 + 4.3. Callbacks . . . . . . . . . . . . . . . . . . . . . . 29 + 4.3.1. SLPRegReport . . . . . . . . . . . . . . . . 30 + 4.3.2. SLPSrvTypeCallback . . . . . . . . . . . . . . 30 + 4.3.3. SLPSrvURLCallback . . . . . . . . . . . . . . 31 + 4.3.4. SLPAttrCallback . . . . . . . . . . . . . . . 33 + 4.4. Opening and Closing an SLPHandle . . . . . . . . . . . 34 + 4.4.1. SLPOpen. . . . . . . . . . . . . . . . . . . . 34 + 4.4.2. SLPClose . . . . . . . . . . . . . . . . . . . 35 + 4.5. Protocol API . . . . . . . . . . . . . . . . . . . . 36 + 4.5.1. SLPReg . . . . . . . . . . . . . . . . . . . . 36 + 4.5.2. SLPDereg . . . . . . . . . . . . . . . . . . . 37 + 4.5.3. SLPDelAttrs . . . . . . . . . . . . . . . . . 38 + 4.5.4. SLPFindSrvTypes. . . . . . . . . . . . . . . . 39 + 4.5.5. SLPFindSrvs . . . . . . . . . . . . . . . . . 41 + 4.5.6. SLPFindAttrs . . . . . . . . . . . . . . . . . 42 + 4.6. Miscellaneous Functions . . . . . . . . . . . . . . . 43 + 4.6.1. SLPGetRefreshInterval . . . . . . . . . . . . 44 + 4.6.2. SLPFindScopes . . . . . . . . . . . . . . . . 44 + 4.6.3. SLPParseSrvURL . . . . . . . . . . . . . . . . 45 + 4.6.4. SLPEscape . . . . . . . . . . . . . . . . . . 46 + 4.6.5. SLPUnescape . . . . . . . . . . . . . . . . . 47 + 4.6.6. SLPFree . . . . . . . . . . . . . . . . . . . 48 + 4.6.7. SLPGetProperty . . . . . . . . . . . . . . . . 48 + 4.6.8. SLPSetProperty . . . . . . . . . . . . . . . . 49 + 4.7. Implementation Notes . . . . . . . . . . . . . . . . 49 + + + +Kempf & Guttman Informational [Page 2] + +RFC 2614 Service Location API June 1999 + + + 4.7.1. Refreshing Registrations . . . . . . . . . . . 49 + 4.7.2. Syntax for String Parameters . . . . . . . . . 49 + 4.7.3. Client Side Syntax Checking . . . . . . . . . 50 + 4.7.4. System Properties . . . . . . . . . . . . . . 50 + 4.7.5. Memory Management . . . . . . . . . . . . . . 51 + 4.7.6. Asynchronous and Incremental Return Semantics. 51 + 4.8. Example. . . . . . . . . . . . . . . . . . . . . . . . 52 + 5. Java Language Binding 56 + 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . 56 + 5.2. Exceptions and Errors . . . . . . . . . . . . . . . . 56 + 5.2.1. Class ServiceLocationException . . . . . . . . 57 + 5.3. Basic Data Structures . . . . . . . . . . . . . . . . 58 + 5.3.1. Interface ServiceLocationEnumeration . . . . . 58 + 5.3.2. Class ServiceLocationAttribute . . . . . . . 58 + 5.3.3. Class ServiceType . . . . . . . . . . . . . . 61 + 5.3.4. Class ServiceURL . . . . . . . . . . . . . . 63 + 5.4. SLP Access Interfaces . . . . . . . . . . . . . . . . 67 + 5.4.1. Interface Advertiser . . . . . . . . . . . . . 67 + 5.4.2. Interface Locator . . . . . . . . . . . . . . 69 + 5.5. The Service Location Manager . . . . . . . . . . . . . 72 + 5.5.1. Class ServiceLocationManager . . . . . . . . . 72 + 5.6. Service Template Introspection . . . . . . . . . . . . 74 + 5.6.1. Abstract Class TemplateRegistry . . . . . . . 74 + 5.6.2. Interface ServiceLocationAttributeVerifier . . 77 + 5.6.3. Interface ServiceLocationAttributeDescriptor . 79 + 5.7. Implementation Notes . . . . . . . . . . . . . . . . . 81 + 5.7.1. Refreshing Registrations . . . . . . . . . . . 81 + 5.7.2. Parsing Alternate Transports in ServiceURL . . 81 + 5.7.3. String Attribute Values . . . . . . . . . . . 82 + 5.7.4. Client Side Syntax Checking. . . . . . . . . . 82 + 5.7.5. Language Locale Handling . . . . . . . . . . . 82 + 5.7.6. Setting SLP System Properties. . . . . . . . . 83 + 5.7.7. Multithreading . . . . . . . . . . . . . . . . 83 + 5.7.8. Modular Implementations . . . . . . . . . . . 83 + 5.7.9. Asynchronous and Incremental Return Semantics. 84 + 5.8. Example. . . . . . . . . . . . . . . . . . . . . . . . 85 + 6. Internationalization Considerations 87 + 6.1. service URL. . . . . . . . . . . . . . . . . . . . . . 87 + 6.2. Character Set Encoding . . . . . . . . . . . . . . . . 87 + 6.3. Language Tagging . . . . . . . . . . . . . . . . . . 88 + 7. Security Considerations 88 + 8. Acknowledgements 88 + 9. References 89 + 10. Authors' Addresses 90 + 11. Full Copyright Statement 91 + + + + + + +Kempf & Guttman Informational [Page 3] + +RFC 2614 Service Location API June 1999 + + +1. Introduction + + The Service Location API is designed for standardized access to the + Service Location Protocol (SLP). The APIs allow client and service + programs to be be written or modified in a very simple manner to + provide dynamic service discovery and selection. Bindings in the C + and Java languages are defined in this document. In addition, + standardized formats for configuration files and for serialized + registration files are presented. These files allow SLP agents to + configure network parameters, to register legacy services that have + not been SLP enabled, and to portably exchange registration + databases. + +1.1. Goals + + The overall goal of the API is to enable source portability of + applications that use the API between different implementations of + SLP. The result should facilitate the adoption of SLP, and conversion + of clients and service programs to SLP. + + The goals of the C binding are to create a minimal but complete + access to the functionality of the SLP protocol, allowing for simple + memory management and limited code size. + + The Java API provides for modular implementations (where unneeded + features can be omitted) and an object oriented interface to the + complete set of SLP data and functionality. + + The standardized configuration file and serialized file formats + provide a simple syntax with complete functional coverage of the + protocol, but without system dependent properties and secure + information. + +1.2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [1]. + + Service Location Protocol (SLP) + + The underlying protocol allowing dynamic and scalable service + discovery. This protocol is specified in the Service Location + Protocol Version 2 [7]. + + + + + + + +Kempf & Guttman Informational [Page 4] + +RFC 2614 Service Location API June 1999 + + + SLP framework + + When a 'Service Location framework' is mentioned, it refers to + both the SLP implementation and interface implementation; i.e. + whatever provides the SLP functionality to user level programs. + This includes remote agents. + + Directory Agent (DA) + + A service that automatically gathers service advertisements + from SAs in order to provide them to UAs. + + User Agent (UA) + + This is the Service Location process or library that allows SLP + requests to be made on behalf of a client process. UAs + automatically direct requests to DAs when they exist. In their + absence, UAs make requests to SAs. + + Service Agent (SA) + + This is the Service Location process or library that allows + service software to register and deregister itself with the SLP + framework. SAs respond to UA service requests, detect DAs and + register service advertisements with them. + + SA Server + + Many operating system platforms only allow a single process to + listen on a particular port number. Since SAs are required to + listen on a multicast address for SLP service requests, + implementations of the SLP framework on such platforms that + want to support multiple SAs on one machine need to arrange for + a single process to do the listening while the advertising SAs + communicate with that process through another mechanism. The + single listening process is called an SA server. SA servers + share many characteristics with DAs, but they are not the same. + + Service Advertisement + + A URL possibly combined with service attributes. These are + made available to UAs by SAs, either directly or via a DA. + + Locale + + The language localization that applies to strings passed into + or returned from the SLP API. The Locale is expressed using a + Language Tag [6]. All attribute strings are associated with a + + + +Kempf & Guttman Informational [Page 5] + +RFC 2614 Service Location API June 1999 + + + particular locale. The locale is completely orthogonal to the + ANSI C locale. The SLP locale is mapped into the Java locale + in the Java API. + + Service Template + + A document that describes the syntax of the URL for a given + service type and a definition of all service attributes + including the meaning, defaults, and constraints on values the + attributes may take. See [8] for more information on service + templates. + + The service: URL + + A service of a particular type announces its availability with + a service: URL that includes its service access point (domain + name or IP address, and possibly its port number) and + optionally basic configuration parameters. The syntax of the + service: URL is defined in the service template. Other URL's + can be used in service advertisements if desired. + + Service Attributes + + The attributes associated with a given service. The values + that can be assigned to service attributes are defined by the + service template. + + Scope + + A string used to control the availability of service + advertisements. Every SLP Agent is configured with one or more + scope strings. Scopes are assigned by site administrators to + group services for many purposes, but chiefly as a means of + scalability. DAs store only services advertised having a scope + string matching the scopes with which they are configured. + + Naming Authority (NA) + + This is a 'suffix' to the service type string. It completely + changes the meaning of the service type. NAs are used for + private definitions of well known Service Types and + experimental Service Type extensions. The default NA is + "IANA", which must not be explicitly included. Service types + with the IANA naming authority are registered with the Internet + Assigned Numbers Authority (see [8] for more information on the + registration procedure). + + + + + +Kempf & Guttman Informational [Page 6] + +RFC 2614 Service Location API June 1999 + + +2. File Formats + + This section describes the configuration and serialized registration + file formats. Both files are defined in the UTF-8 character set [3]. + + Attribute tags and values in the serialized registration file require + SLP reserved characters to be escaped. The SLP reserved characters + are `(', `)', `,', `\', `!', `<', `=', `>', `~' and control + characters (characters with UTF codes less than 0x0020 and the + character 0x007f, which is US-ASCII DEL). The escapes are formed + exactly as for the wire protocol, i.e. a backslash followed by two + hex digits representing the character. For example, the escape for ' + ,' is '\2c'. In addition, the characters `\n', `\r', `\t', and `_' + are prohibited from attribute tags by the SLP wire syntax grammar. + [7] + + In serialized registration files, escaped strings beginning with + `\ff`, an encoding for a nonUTF-8 character, are treated as opaques. + Exactly as in the wire protocol, syntactically correct opaque + encodings consist of a string beginning with `\ff` and containing + *only* escaped characters that are transformed to bytes. Such + strings are only syntactically correct in the serialized registration + file as attribute values. In other cases, whenever an escape is + encountered and the character is not an SLP reserved character, an + error is signaled. + + Escaped characters in URLs in serialized registration files use the + URL escape convention. [2]. + + Property names and values in the configuration file have a few + reserved characters that are involved in file's lexical definition. + The characters '.' and '=' are reserved in property names and must + be escape. The characters ',', '(', and ')' are reserved in property + values and must be escaped. In addition, scope names in the + net.slp.useScopes property use the SLP wire format escape convention + for SLP reserved characters. This simplifies implementation, since + the same code can be used to unescape scope names as is used in + processing the serialized registration file or for formatting wire + messages. + + On platforms that only support US-ASCII and not UTF-8, the upper bit + of bytes incoming from the configuration and registration files + determines whether the character is US-ASCII or not US-ASCII. + According to the standard UTF-8 encoding, the upper bit is zero if + the character is US-ASCII and one if the character is multibyte and + thus not US-ASCII. Platforms without intrinsic UTF-8 support are + required to parse the multibyte character and store it in an + appropriate internal format. Support for UTF-8 is required to + + + +Kempf & Guttman Informational [Page 7] + +RFC 2614 Service Location API June 1999 + + + implement the SLP protocol (see [7]), and can therefore be used in + file processing as well. + + The location and name of the configuration file is system-dependent, + but implementations of the API are encouraged to locate it together + with other configuration files and name it consistently. + +2.1. Configuration File Format + + The configuration file format consists of a newline delimited list of + zero or more property definitions. Each property definition + corresponds to a particular configurable SLP, network, or other + parameter in one or more of the three SLP agents. The file format + grammar in ABNF [5] syntax is: + + config-file = line-list + line-list = line / line line-list + line = property-line / comment-line + comment-line = ( "#" / ";" ) 1*allchar newline + property-line = property newline + property = tag "=" value-list + tag = prop / prop "." tag + prop = 1*tagchar + value-list = value / value "," value-list + value = int / bool / + "(" value-list ")" / string + int = 1*DIGIT + bool = "true" / "false" / "TRUE" / "FALSE" + newline = CR / ( CRLF ) + string = 1*stringchar + tagchar = DIGIT / ALPHA / tother / escape + tother = %x21-%x2d / %x2f / + %x3a / %x3c-%x40 / + %x5b-%x60 / %7b-%7e + ; i.e., all characters except `.', + ; and `='. + stringchar = DIGIT / ALPHA / sother / escape + sother = %x21-%x29 / %x2a-%x2b / + %x2d-%x2f / %x3a-%x40 / + %x5b-%x60 / %7b-%7e + ; i.e., all characters except `,' + allchar = DIGIT / ALPHA / HTAB / SP + escape = "\" HEXDIG HEXDIG + ; Used for reserved characters + + With the exception of net.slp.useScopes, net.slp.DAAddresses, and + net.slp.isBroadcastOnly, all other properties can be changed through + property accessors in the C and Java APIs. The property accessors + + + +Kempf & Guttman Informational [Page 8] + +RFC 2614 Service Location API June 1999 + + + only change the property values in the running agent program and do + not affect the values in the configuration file. The + net.slp.useScopes and net.slp.DAAddresses properties are read-only + because they control the agent's view of the scopes and DAs and are + therefore critical to the function of the API scope discovery + algorithm. Attempts to modify them are unlikely to yield productive + results, and could harm the ability of the agent to find scopes and + use DAs. The net.slp.isBroadcastOnly property is read-only because + the API library needs to configure networking upon start up and + changing this property might invalidate the configuration. Whether + the local network uses broadcast or multicast is not likely to change + during the course of the program's execution. + + The properties break down into the following subsections describes an + area and its properties. + +2.1.1. DA configuration + + Important configuration properties for DAs are included in this + section. These are: + + net.slp.isDA + + A boolean indicating if the SLP server is to act as a DA. If + false, not run as a DA. Default is false. + + net.slp.DAHeartBeat + + A 32 bit integer giving the number of seconds for the + DA heartbeat. Default is 3 hours (10800 seconds). This + property corresponds to the protocol specification parameter + CONFIG_DA_BEAT [7]. Ignored if isDA is false. + + net.slp.DAAttributes + + A comma-separated list of parenthesized attribute/value list + pairs that the DA must advertise in DAAdverts. The property + must be in the SLP attribute list wire format, including + escapes for reserved characters. [7] + +2.1.2. Static Scope Configuration + + These properties allow various aspects of scope handling to be + configured. + + + + + + + +Kempf & Guttman Informational [Page 9] + +RFC 2614 Service Location API June 1999 + + + net.slp.useScopes + + A value-list of strings indicating the only scopes a UA or SA + is allowed to use when making requests or registering, or the + scopes a DA must support. If not present for the DA and SA, + then in the absence of scope information from DHCP, the default + scope "DEFAULT" is used. If not present for the UA, and there + is no scope information available from DHCP, then the user + scoping model is in force. Active and passive DA discovery + or SA discovery are used for scope discovery, and the scope + "DEFAULT" is used if no other information is available. If a + DA or SA gets another scope in a request, a SCOPE_NOT_SUPPORTED + error should be returned, unless the request was multicast, in + which case it should be dropped. If a DA gets another scope in + a registration, a SCOPE_NOT_SUPPORTED error must be returned. + Unlike other properties, this property is "read-only", so + attempts to change it after the configuration file has been + read are ignored. See Section 3.12 for the algorithm the API + uses in determining what scope information to present. + + net.slp.DAAddresses + + A value-list of IP addresses or DNS resolvable host names + giving the SLPv2 DAs to use for statically configured UAs and + SAs. Ignored by DAs (unless the DA is also an SA server). + Default is none. Unlike other properties, this property is + "read-only", so attempts to change it after the configuration + file has been read are ignored. + + The following grammar describes the property: + + + addr-list = addr / addr "," addr-list + addr = fqdn / hostnumber + fqdn = ALPHA / ALPHA *[ anum / "-" ] anum + anum = ALPHA / DIGIT + hostnumber = 1*3DIGIT 3("." 1*3DIGIT) + + + An example is: + + + sawah,mandi,sambal + + + IP addresses can be used instead of host names in networks + where DNS is not deployed, but network administrators are + reminded that using IP addresses will complicate machine + + + +Kempf & Guttman Informational [Page 10] + +RFC 2614 Service Location API June 1999 + + + renumbering, since the SLP configuration property files + in statically configured networks will have to be changed. + Similarly, if host names are used, implementors must be careful + that a name service is available before SLP starts, in other + words, SLP cannot be used to find the name service. + +2.1.3. Tracing and Logging + + This section allows tracing and logging information to be printed by + the various agents. + + net.slp.traceDATraffic + + A boolean controlling printing of messages about traffic with + DAs. Default is false. + + net.slp.traceMsg + + A boolean controlling printing of details on SLP messages. + The fields in all incoming messages and outgoing replies are + printed. Default is false. + + net.slp.traceDrop + + A boolean controlling printing details when a SLP message is + dropped for any reason. Default is false. + + net.slp.traceReg + + A boolean controlling dumps of all registered services upon + registration and deregistration. If true, the contents + of the DA or SA server are dumped after a registration or + deregistration occurs. Default is false. + +2.1.4. Serialized Proxy Registrations + + These properties control the reading and writing of serialized + registrations. + + net.slp.serializedRegURL + + A string containing a URL pointing to a document containing + serialized registrations that should be processed when the DA + or SA server starts up. Default is none. + + + + + + + +Kempf & Guttman Informational [Page 11] + +RFC 2614 Service Location API June 1999 + + +2.1.5. Network Configuration Properties + + The properties in this section allow various network configuration + properties to be set. + + net.slp.isBroadcastOnly + + A boolean indicating if broadcast should be used instead of + multicast. Like the net.slp.useScopes and net.slp.DAAddresses + properties, this property is "read-only", so attempts to change + it after the configuration file has been read are ignored. + Default is false. + + net.slp.passiveDADetection + + A boolean indicating whether passive DA detection should be + used. Default is true. + + net.slp.multicastTTL + + A positive integer less than or equal to 255, giving the + multicast TTL. Default is 255. + + net.slp.DAActiveDiscoveryInterval + + A 16 bit positive integer giving the number of seconds + between DA active discovery queries. Default is 900 seconds + (15 minutes). This property corresponds to the protocol + specification parameter CONFIG_DA_FIND [7]. If the property is + set to zero, active discovery is turned off. This is useful + when the DAs available are explicitly restricted to those + obtained from DHCP or the net.slp.DAAddresses property. + + net.slp.multicastMaximumWait + + A 32 bit integer giving the maximum amount of time to perform + multicast, in milliseconds. Default is 15000 ms (15 sec.). + This property corresponds to the CONFIG_MC_MAX parameter in the + protocol specification [7]. + + net.slp.multicastTimeouts + + A value-list of 32 bit integers used as timeouts, in + milliseconds, to implement the multicast convergence + algorithm. Each value specifies the time to wait before + sending the next request, or until nothing new has + been learned from two successive requests. Default + is: 3000,3000,3000,3000,3000. In a fast network the + + + +Kempf & Guttman Informational [Page 12] + +RFC 2614 Service Location API June 1999 + + + aggressive values of 1000,1250,1500,2000,4000 allow better + performance. This property corresponds to the CONFIG_MC_RETRY + parameter in the protocol specification [7]. Note that the + net.slp.DADiscoveryTimeouts property must be used for active DA + discovery. + + net.slp.DADiscoveryTimeouts + + A value-list of 32 bit integers used as timeouts, in + milliseconds, to implement the multicast convergence algorithm + during active DA discovery. Each value specifies the time + to wait before sending the next request, or until nothing + new has been learned from two successive requests. This + property corresponds to the protocol specification parameter + CONFIG_RETRY [7]. Default is: 2000,2000,2000,2000,3000,4000. + + net.slp.datagramTimeouts + + A value-list of 32 bit integers used as timeouts, in + milliseconds, to implement unicast datagram transmission to + DAs. The nth value gives the time to block waiting for a reply + on the nth try to contact the DA. The sum of these values is + the protocol specification property CONFIG_RETRY_MAX [7]. + + net.slp.randomWaitBound + + A 32 bit integer giving the maximum value for all random + wait parameters, in milliseconds. Default is 1000 (1 + sec.). This value corresponds to the protocol specification + parameters CONFIG_START_WAIT, CONFIG_REG_PASSIVE, and + CONFIG_REG_ACTIVE [7]. + + net.slp.MTU + + A 16 bit integer giving the network packet MTU, in bytes. + This is the maximum size of any datagram to send, but the + implementation might receive a larger datagram. The maximum + size includes IP, and UDP or TCP headers. Default is 1400. + + net.slp.interfaces + + Value-list of strings giving the IP addresses of network + interfaces on which the DA or SA should listen on port 427 for + multicast, unicast UDP, and TCP messages. Default is empty, + i.e. use the default network interface. The grammar for this + property is: + + + + + +Kempf & Guttman Informational [Page 13] + +RFC 2614 Service Location API June 1999 + + + addr-list = hostnumber / hostnumber "," addr-list + hostnumber = 1*3DIGIT 3("." 1*3DIGIT) + + + An example is: + + + 195.42.42.42,195.42.142.1,195.42.120.1 + + + The example machine has three interfaces on which the DA should + listen. + + Note that since this property only takes IP addresses, it will + need to be changed if the network is renumbered. + +2.1.6. SA Configuration + + This section contains configuration properties for the SA. These + properties are typically set programmatically by the SA, since they + are specific to each SA. + + net.slp.SAAttributes + + A comma-separated list of parenthesized attribute/value list + pairs that the SA must advertise in SAAdverts. The property + must be in the SLP attribute list wire format, including + escapes for reserved characters. [7] + +2.1.7. UA Configuration + + This section contains configuration properties for the UA. These + properties can be set either programmatically by the UA or in the + configuration file. + + net.slp.locale + + A RFC 1766 Language Tag [6] for the language locale. Setting + this property causes the property value to become the default + locale for SLP messages. Default is "en". This property is + also used for SA and DA configuration. + + net.slp.maxResults + + A 32 bit integer giving the maximum number of results to + accumulate and return for a synchronous request before the + timeout, or the maximum number of results to return through a + callback if the request results are reported asynchronously. + + + +Kempf & Guttman Informational [Page 14] + +RFC 2614 Service Location API June 1999 + + + Positive integers and -1 are legal values. If -1, indicates + that all results should be returned. Default value is -1. + + DAs and SAs always return all results that match the + request. This configuration value applies only to UAs, that + filter incoming results and only return as many values as + net.slp.maxResults indicates. + + net.slp.typeHint + + A value-list of service type names. In the absence of any + DAs, UAs perform SA discovery for finding scopes. These SA + discovery requests may contain a request for service types as + an attribute. + + The API implementation will use the service type names supplied + by this property to discover only those SAs (and their scopes) + which support the desired service type or types. For example, + if net.slp.typeHint is set to "service:imap,service:pop3" then + SA discovery requests will include the search filter: + + + (|(service-type=service:imap)(service-type=service:pop3)) + + + The API library can also use unicast to contact the discovered + SAs for subsequent requests for these service types, to + optimize network access. + +2.1.8. Security + + The property in this section allows security for all agents to be set + on or off. When the property is true, then the agent must include + security information on all SLP messages transacted by that agent. + Since security policy must be set network wide to be effective, a + single property controls security for all agents. Key management and + management of SLP SPI strings [7] are implementation and policy + dependent. + + net.slp.securityEnabled + + A boolean indicating whether the agent should enable + security for URLs, attribute lists, DAAdverts, and SAAdverts. + Each agent is responsible for interpreting the property + appropriately. Default is false. + + + + + + +Kempf & Guttman Informational [Page 15] + +RFC 2614 Service Location API June 1999 + + +2.2. Multihomed Machines + + On multihomed machines, the bandwidth and latency characteristics on + different network interfaces may differ considerably, to the point + where different configuration properties are necessary to achieve + optimal performance. The net.slp.interfaces property indicates which + network interfaces are SLP enabled. An API library implementation + may support configuration customization on a per network interface + basis by allowing the interface IP address to be appended to the + property name. In that case, the values of the property are only + used for that particular interface, the generic property (or defaults + if no generic property is set) applies to all others. + + For example, if a configuration has the following properties: + + + net.slp.interfaces=125.196.42.41,125.196.42.42,125.196.42.43 + net.slp.multicastTTL.125.196.42.42=1 + + + then the network interface on subnet 42 is restricted to a TTL of 1, + while the interfaces on the other subnets have the default multicast + radius, 255. + + The net.slp.interfaces property must only be set if there is no + routing between the interfaces. If the property is set, the DA (if + any) and SAs should advertise with the IP address or host name + appropriate to the interface on the interfaces in the list. If + packets are routed between the interfaces, then the DA and SAs should + only advertise on the default interface. The property should also be + set if broadcast is used rather than multicast on the subnets + connected to the interfaces. Note that even if unicast packets are + not routed between the interfaces, multicast may be routed through + another router. The danger in listening for multicast on multiple + interfaces when multicast packets are routed is that the DA or SA may + receive the same multicast request via more than one interface. + Since the IP address is different on each interface, the DA or SA + cannot identify the request as having already being answered via the + previous responder's list. The requesting agent will end up getting + URLs that refer to the same DA or service but have different + addresses or host names. + +2.3. Serialized Registration File + + The serialized registration file contains a group of registrations + that a DA or SA server (if one exists) registers when it starts up. + These registrations are primarily for older service programs that do + not internally support SLP and cannot be converted, and for portably + + + +Kempf & Guttman Informational [Page 16] + +RFC 2614 Service Location API June 1999 + + + exchanging registrations between SLP implementations. The character + encoding of the registrations is required to be UTF-8. + + The syntax of the serialized registration file, in ABNF format [5], + is as follows: + + + ser-file = reg-list + reg-list = reg / reg reg-list + reg = creg / ser-reg + creg = comment-line ser-reg + comment-line = ( "#" / ";" ) 1*allchar newline + ser-reg = url-props [slist] [attr-list] newline + url-props = surl "," lang "," ltime [ "," type ] newline + surl = ;The registration's URL. See + ; [8] for syntax. + lang = 1*8ALPHA [ "-" 1*8ALPHA ] + ;RFC 1766 Language Tag see [6]. + ltime = 1*5DIGIT + ; A positive 16-bit integer + ; giving the lifetime + ; of the registration. + type = ; The service type name, see [7] + ; and [8] for syntax. + slist = "scopes" "=" scope-list newline + scope-list = scope-name / scope-name "," scope-list + scope = ; See grammar of [7] for + ; scope-name syntax. + attr-list = attr-def / attr-def attr-list + attr-def = ( attr / keyword ) newline + keyword = attr-id + attr = attr-id "=" attr-val-list + attr-id = ;Attribute id, see [7] for syntax. + attr-val-list = attr-val / attr-val "," attr-val-list + attr-val = ;Attribute value, see [7] for syntax. + allchar = char / WSP + char = DIGIT / ALPHA / other + other = %x21-%x2f / %x3a-%x40 / + %x5b-%x60 / %7b-%7e + ; All printable, nonwhitespace US-ASCII + ; characters. + newline = CR / ( CRLF ) + + + The syntax for scope names, attribute tags, and attribute values + requires escapes for special characters as specified in [7]. DAs and + SA servers that process serialized registrations must handle them + exactly as if they were registered by an SA. In the url-props + + + +Kempf & Guttman Informational [Page 17] + +RFC 2614 Service Location API June 1999 + + + production, the type token is optional. If the type token is present + for a service: URL, a warning is signaled and the type name is + ignored. If the maximum lifetime is specified (65535 sec.), the + registration is taken to be permanent, and is continually refreshed + by the DA or SA server until it exits. Scopes can be included in a + registration by including an attribute definition with tag "scopes" + followed by a comma separated list of scope names immediately after + the url-props production. If the optional scope list is present, the + registrations are made in the indicated scopes; otherwise, they are + registered in the scopes with which the DA or SA server was + configured through the net.slp.useScopes property. + + If the scope list contains scopes that are not in the + net.slp.useScopes property (provided that property is set) or are not + specified by DHCP, the API library should reject the registration and + issue a warning message. + +2.4. Processing Serialized Registration and Configuration Files + + Implementations are encouraged to make processing of configuration + and serialized files as transparent as possible to clients of the + API. At the latest, errors must be caught when the relevant + configuration item is used. At the earliest, errors may be caught + when the relevant file is loaded into the executing agent. Errors + should be reported by logging to the appropriate platform logging + file, error output, or log device, and the default value substituted. + Serialized registration file entries should be caught and reported + when the file is loaded. + + Configuration file loading must be complete prior to the initiation + of the first networking connection. Serialized registration must be + complete before the DA accepts the first network request. + +3. Binding Independent Implementation Considerations + + This section discusses a number of implementation considerations + independent of language binding, with language specific notes where + applicable. + +3.1. Multithreading + + Implementations of both the C and Java APIs are required to make API + calls thread-safe. Access to data structures shared between threads + must be co-ordinated to avoid corruption or invalid access. One way + to achieve this goal is to allow only one thread at a time in the + implementing library. Performance in such an implementation suffers, + however. Therefore, where possible, implementations are encouraged + to allow multiple threads within the SLP API library. + + + +Kempf & Guttman Informational [Page 18] + +RFC 2614 Service Location API June 1999 + + +3.2. Asynchronous and Incremental + + The APIs are designed to encourage implementations supporting + asynchronous and incremental client interaction. The goal is to + allow large numbers of returned service URLs, service types, and + attributes without requiring the allocation of huge chunks of memory. + The particular design features to support this goal differ in the two + language bindings. + +3.3. Type Checking for Service Types + + Service templates [8] allow SLP registrations to be type checked for + correctness. Implementations of the API are free to make use of + service type information for type checking, but are not required to + do so. If a type error occurs, the registration should terminate + with TYPE_ERROR. + +3.4. Refreshing Registrations + + SLP advertisements carry an explicit lifetime with them. After the + lifetime expires, the DA flushes the registration from its cache. In + some cases, an application may want to have the URL continue being + registered for the entire time during which the application is + executing. The API includes provision for clients to indicate + whether they want URLs to be automatically refreshed. + Implementations of the SA API must provide this automatic refreshing + capability. Note that a client which uses this facility should + explicitly deregister the service URL before exiting, since the API + implementation may not be able to assure that the URL is deregistered + when the application exits, although it will time out in the DA + eventually. + +3.5. Configuration File Processing + + DAs, SAs and UAs processing the configuration file, and DAs and SA + servers processing the serialized registration file are required to + log any errors using whatever underlying error mechanism is + appropriate for the platform. Examples include writing error + messages to the standard output, writing to a system logging device, + or displaying the errors to a logging window. After the error is + reported, the offending property must be set to the default and + program execution continued. An agent MUST NOT fail if a file format + error occurs. + + + + + + + + +Kempf & Guttman Informational [Page 19] + +RFC 2614 Service Location API June 1999 + + +3.6. Attribute Types + + String encoded attribute values do not include explicit type + information. All UA implementations and those SA and DA + implementations that choose to support type checking should use the + type rules described in [8] in order to convert from the string + representation on the wire to an object typed appropriately. + +3.7. Removal of Duplicates + + The UA implementation SHOULD always collate results to remove + duplicates during synchronous operations and for the Java API. During + asynchronous operation in C, the UA implementation SHOULD forgo + duplicate elimination to reduce memory requirements in the library. + This allows the API library to simply take the returned attribute + value list strings, URL strings, or service type list strings and + call the callback function with it, without any additional + processing. Naturally, the burden of duplicate elimination is thrown + onto the client in this case. + +3.8. Character Set Encoding + + Character string parameters in the Java API are all represented in + Unicode internally because that is the Java-supported character set. + Characters buffer parameters in the C API are represented in UTF-8 to + maintain maximum compatibility on platforms that only support US- + ASCII and not UTF-8. API functions are still required to handle the + full range of UTF-8 characters because the SLP protocol requires it, + but the API implementation can represent the characters internally in + any convenient way. On the wire, all characters are converted to + UTF-8. Inside URLs, characters that are not allowed by URL syntax + [2] must be escaped according to the URL escape character convention. + Strings that are included in SLP messages may include SLP reserved + characters and can be escaped by clients through convenience + functions provided by the API. The character encoding used in escapes + is UTF-8. + + Due to constraints in SLP, no string parameter passed to the C or + Java API may exceed 64K bytes in length. + +3.9. Error Semantics + + All errors encountered processing SLP messages should be logged. For + synchronous calls, an error is only reported on a call if no + successful replies were received from any SLP framework entity. If + an error occurred among one of several successful replies, then the + error should be logged and the successful replies returned. For + asynchronous calls, an error occurring during correspondence with a + + + +Kempf & Guttman Informational [Page 20] + +RFC 2614 Service Location API June 1999 + + + particular remote SLP agent is reported through the first callback + (in the C API) or enumeration method invocation (in the Java API) + after the error occurs, which would normally report the results of + the correspondence. This allows the callback or client code to + determine whether the operation should be terminated or continue. In + some cases, the error returned from the SLP framework may be fatal + (SLP_PARSE_ERROR, etc.). In these cases, the API library terminates + the operation. + + Both the Java and C APIs contain language specific error code + mechanisms for returning error information. The names of the error + codes are consistent between the two implementations, however. + + The following error codes are returned from a remote agent (DA or SA + server): + + LANGUAGE_NOT_SUPPORTED + + No DA or SA has service advertisement or attribute information + in the language requested, but at least one DA or SA indicated, + via the LANGUAGE_NOT_SUPPORTED error code, that it might have + information for that service in another language. + + PARSE_ERROR + + The SLP message was rejected by a remote SLP agent. The API + returns this error only when no information was retrieved, and + at least one SA or DA indicated a protocol error. The data + supplied through the API may be malformed or a may have been + damaged in transit. + + INVALID_REGISTRATION + + The API may return this error if an attempt to register a + service was rejected by all DAs because of a malformed URL or + attributes. SLP does not return the error if at least one DA + accepted the registration. + + AUTHENTICATION_ABSENT + + If the SLP framework supports authentication, this error arises + when the UA or SA failed to send an authenticator for requests + or registrations in a protected scope. + + + + + + + + +Kempf & Guttman Informational [Page 21] + +RFC 2614 Service Location API June 1999 + + + INVALID_UPDATE + + An update for a non-existing registration was issued, or the + update includes a service type or scope different than that in + the initial registration, etc. + + The following errors result from interactions with remote agents or + can occur locally: + + AUTHENTICATION_FAILED + + If the SLP framework supports authentication, this error arises + when a authentication on an SLP message failed. + + SCOPE_NOT_SUPPORTED + + The API returns this error if the SA has been configured with + net.slp.useScopes value-list of scopes and the SA request did + not specify one or more of these allowable scopes, and no + others. It may be returned by a DA or SA if the scope included + in a request is not supported by the DA or SA. + + REFRESH_REJECTED + + The SA attempted to refresh a registration more frequently + than the minimum refresh interval. The SA should call the + appropriate API function to obtain the minimum refresh interval + to use. + + The following errors are generated through a program interacting with + the API implementation. They do not involve a remote SLP agent. + + NOT_IMPLEMENTED + + If an unimplemented feature is used, this error is returned. + + NETWORK_INIT_FAILED + + If the network cannot initialize properly, this error is + returned. + + NETWORK_TIMED_OUT + + When no reply can be obtained in the time specified by the + configured timeout interval for a unicast request, this error + is returned. + + + + + +Kempf & Guttman Informational [Page 22] + +RFC 2614 Service Location API June 1999 + + + NETWORK_ERROR + + The failure of networking during normal operations causes this + error to be returned. + + BUFFER_OVERFLOW + + An outgoing request overflowed the maximum network MTU size. + The request should be reduced in size or broken into pieces and + tried again. + + MEMORY_ALLOC_FAILED + + If the API fails to allocate memory, the operation is aborted + and returns this. + + PARAMETER_BAD + + If a parameter passed into an interface is bad, this error is + returned. + + INTERNAL_SYSTEM_ERROR + + A basic failure of the API causes this error to be returned. + This occurs when a system call or library fails. The operation + could not recover. + + HANDLE_IN_USE + + In the C API, callback functions are not permitted to + recursively call into the API on the same SLPHandle, either + directly or indirectly. If an attempt is made to do so, this + error is returned from the called API function. + + TYPE_ERROR + + If the API supports type checking of registrations against + service type templates, this error can arise if the attributes + in a registration do not match the service type template for + the service. + + Some error codes are handled differently in the Java API. These + differences are discussed in Section 5. + + The SLP protocol errors OPTION_NOT_UNDERSTOOD, VERSION_NOT_SUPPORTED, + INTERNAL_ERROR, MSG_NOT_SUPPORTED, AUTHENTICATON_UNKNOWN, and + DA_BUSY_NOW should be handled internally and not surfaced to clients + through the API. + + + +Kempf & Guttman Informational [Page 23] + +RFC 2614 Service Location API June 1999 + + +3.10. Modular Implementations + + Subset implementations that do not support the full range of + functionality are required to nevertheless support every interface in + order to maintain link compatibility between compliant API + implementations and applications. If a particular operation is not + supported, a NOT_IMPLEMENTED error should be returned. The Java API + has some additional conventions for handling subsets. Applications + that are expected to run on a wide variety of platforms should be + prepared for subset API implementations by checking returned error + codes. + +3.11. Handling Special Service Types + + The service types service:directory-agent and service:service-agent + are used internally in the SLP framework to discover DAs and SAs. + The mechanism of DA and SA discovery is not normally exposed to the + API client; however, the client may have interest in discovering DAs + and SAs independently of their role in discovering other services. + For example, a network management application may want to determine + which machines are running SLP DAs. To facilitate that, API + implementations must handle requests to find services and attributes + for these two service types so that API clients obtain the + information they expect. + + In particular, if the UA is using a DA, SrvRqst and AttrRqst for + these service types must be multicast and not unicast to the DA, as + is the case for other service types. If the requests are not + multicast, the DA will respond with an empty reply to a request for + services of type service:service-agent and with its URL only to a + request for services of type service:directory-agent. The UA would + therefore not obtain a complete picture of the available DAs and SAs. + +3.12. Scope Discovery and Handling + + Both APIs contain an operation to obtain a list of currently known + scope names. This scope information comes from a variety of places: + DHCP, the net.slp.useScopes property, unicast to DAs configured via + DHCP or the net.slp.DAAddresses property, and active and passive + discovery. + + The API is required to be implemented in a way that re-enforces the + administrative and user scoping models described in [7]. SA clients + only support the administrative scoping model. SAs must know a + priori what DAs they need to register with since there is typically + no human intervention in scope selection for SAs. UAs must support + both administrative and user scoping because an application may + require human intervention in scope selection. + + + +Kempf & Guttman Informational [Page 24] + +RFC 2614 Service Location API June 1999 + + + API implementations are required to support administrative scoping in + the following way. Scopes configured by DHCP and scopes of DAs + configured by DHCP have first priority (in that order) and must be + returned if they are available. The net.slp.useScopes property has + second priority, and scopes discovered through the net.slp.useScopes + property must be returned if this property is set and there are no + scopes available from DHCP. If scopes are not available from either + of these sources and the net.slp.DAAddresses property is set, then + the scopes available from the configured DAs must be returned. Note + that if both DAs and scopes are configured, the scopes of the + configured DAs must match the configured scope list; otherwise and + error is signaled and agent execution is terminated. If no + configured scope information is available, then an SA client has + default scope, "DEFAULT", and a UA client employs user scoping. + + User scoping is supported in the following way. Scopes discovered + from active DA discovery, and from passive DA discovery all must be + returned. If no information is available from active and passive DA + discovery, then the API library may perform SA discovery, using the + service types in the net.slp.typeHint property to limit the search to + SAs supporting particular service types. If no net.slp.typeHint + property is set, the UA may perform SA discovery without any service + type query. In the absence of any of the above sources of + information, the API must return the default scope, "DEFAULT". Note + that the API must always return some scope information. + + SLP requires that SAs must perform their operations in all scopes + currently known to them. [7]. The API enforces this constraint by + not requiring the API client to supply any scopes as parameters to + API operations. The API library must obtain all currently known + scopes and use them in SA operations. UA API clients should use a + scope obtained through one of the API operations for finding scopes. + Any other scope name may result in a SCOPE_NOT_SUPPORTED error from a + remote agent. The UA API library can optionally check the scope and + return the error without contacting a remote agent. + +4. C Language Binding + + The C language binding presents a minimal overhead implementation + 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 for the most part character + buffers. Memory management is kept simple by having the client + allocate most memory and requiring that client callback functions + copy incoming parameters into memory allocated by the client code. + Any memory returned directly from the API functions is deallocated + using the SLPFree() function. + + + +Kempf & Guttman Informational [Page 25] + +RFC 2614 Service Location API June 1999 + + + 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 UTF-8 but they may still be passed as a C string (a + null terminated sequence of bytes.) Escaped characters must be + encoded by the API client as UTF-8. In the common case of US-ASCII, + the usual one byte per character C strings work. API functions + assist in escaping and unescaping strings. + + Unless otherwise noted, parameters to API functions and callbacks are + non-NULL. Some parameters may have other restrictions. If any + parameter fails to satisfy the restrictions on its value, the + operation returns a PARAMETER_BAD error. + +4.1. Constant Types + +4.1.1. URL Lifetimes + +4.1.1.1. Synopsis + + + typedef enum { + SLP_LIFETIME_DEFAULT = 10800, + SLP_LIFETIME_MAXIMUM = 65535 + } SLPURLLifetime; + + +4.1.1.2. Description + + The SLPURLLifetime enum type contains URL lifetime values, in + seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours, + while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the + maximum size of the lifetime field in SLP messages. + +4.1.2. Error Codes + +4.1.2.1. Synopsis + + + typedef enum { + SLP_LAST_CALL = 1, + SLP_OK = 0, + SLP_LANGUAGE_NOT_SUPPORTED = -1, + SLP_PARSE_ERROR = -2, + SLP_INVALID_REGISTRATION = -3, + SLP_SCOPE_NOT_SUPPORTED = -4, + SLP_AUTHENTICATION_ABSENT = -6, + SLP_AUTHENTICATION_FAILED = -7, + + + +Kempf & Guttman Informational [Page 26] + +RFC 2614 Service Location API June 1999 + + + SLP_INVALID_UPDATE = -13, + SLP_REFRESH_REJECTED = -15, + SLP_NOT_IMPLEMENTED = -17, + SLP_BUFFER_OVERFLOW = -18, + SLP_NETWORK_TIMED_OUT = -19, + SLP_NETWORK_INIT_FAILED = -20, + SLP_MEMORY_ALLOC_FAILED = -21, + SLP_PARAMETER_BAD = -22, + SLP_NETWORK_ERROR = -23, + SLP_INTERNAL_SYSTEM_ERROR = -24, + SLP_HANDLE_IN_USE = -25, + SLP_TYPE_ERROR = -26 + } SLPError ; + + +4.1.2.2. Description + + The SLPError enum contains error codes that are returned from API + functions. + + The SLP_OK code indicates that the no error occurred during the + operation. + + The SLP_LAST_CALL code is passed to callback functions when the API + library has no more data for them and therefore no further calls will + be made to the callback on the currently outstanding operation. The + callback can use this to signal the main body of the client code that + no more data will be forthcoming on the operation, so that the main + body of the client code can break out of data collection loops. On + the last call of a callback during both a synchronous and + asynchronous call, the error code parameter has value SLP_LAST_CALL, + and the other parameters are all NULL. If no results are returned by + an API operation, then only one call is made, with the error + parameter set to SLP_LAST_CALL. + +4.1.3. SLPBoolean + +4.1.3.1. Synopsis + + + typedef enum { + SLP_FALSE = 0, + SLP_TRUE = 1 + + } SLPBoolean; + + + + + + +Kempf & Guttman Informational [Page 27] + +RFC 2614 Service Location API June 1999 + + +4.1.3.2. Description + + The SLPBoolean enum is used as a boolean flag. + +4.2. Struct Types + +4.2.1. SLPSrvURL + +4.2.1.1. Synopsis + + + typedef struct srvurl { + char *s_pcSrvType; + char *s_pcHost; + int s_iPort; + char *s_pcNetFamily; + char *s_pcSrvPart; + } SLPSrvURL; + + +4.2.1.2. Description + + The SLPSrvURL structure is filled in by the SLPParseSrvURL() function + with information parsed from a character buffer containing a service + URL. The fields correspond to different parts of the URL. Note that + the structure is in conformance with the standard Berkeley sockets + struct servent, with the exception that the pointer to an array of + characters for aliases (s_aliases field) is replaced by the pointer + to host name (s_pcHost field). + + s_pcSrvType + + A pointer to a character string containing the service + type name, including naming authority. The service type + name includes the "service:" if the URL is of the service: + scheme. [7] + + s_pcHost + + A pointer to a character string containing the host + identification information. + + s_iPort + + The port number, or zero if none. The port is only available + if the transport is IP. + + + + + +Kempf & Guttman Informational [Page 28] + +RFC 2614 Service Location API June 1999 + + + s_pcNetFamily + + A pointer to a character string containing the network address + family identifier. Possible values are "ipx" for the IPX + family, "at" for the Appletalk family, and "" (i.e. the empty + string) for the IP address family. + + s_pcSrvPart + + The remainder of the URL, after the host identification. + + The host and port should be sufficient to open a socket to the + machine hosting the service, and the remainder of the URL should + allow further differentiation of the service. + +4.2.2. SLPHandle + +4.2.2.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.3. Callbacks + + A function pointer to a callback function specific to a particular + API operation is included in the parameter list when the API function + is invoked. The callback function is called with the results of the + operation in both the synchronous and asynchronous cases. The memory + included in the callback parameters is owned by the API library, and + the client code in the callback must copy out the contents if it + wants to maintain the information longer than the duration of the + current callback call. + + In addition to parameters for reporting the results of the operation, + each callback parameter list contains an error code parameter and a + cookie parameter. The error code parameter reports the error status + of the ongoing (for asynchronous) or completed (for synchronous) + operation. The cookie parameter allows the client code that starts + the operation by invoking the API function to pass information down + to the callback without using global variables. The callback returns + an SLPBoolean to indicate whether the API library should continue + processing the operation. If the value returned from the callback is + + + +Kempf & Guttman Informational [Page 29] + +RFC 2614 Service Location API June 1999 + + + SLP_TRUE, asynchronous operations are terminated, synchronous + operations ignore the return (since the operation is already + complete). + +4.3.1. SLPRegReport + +4.3.1.1. Synopsis + + + typedef void SLPRegReport(SLPHandle hSLP, + SLPError errCode, + void *pvCookie); + + +4.3.1.2. Description + + The SLPRegReport callback type is the type of the callback function + to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. + +4.3.1.3. Parameters + + hSLP + + The SLPHandle used to initiate the operation. + + errCode + + An error code indicating if an error occurred during the + operation. + + pvCookie + + Memory passed down from the client code that called the + original API function, starting the operation. May be NULL. + +4.3.2. SLPSrvTypeCallback + +4.3.2.1. Synopsis + + typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP, + const char* pcSrvTypes, + SLPError errCode, + void *pvCookie); + + + + + + + + +Kempf & Guttman Informational [Page 30] + +RFC 2614 Service Location API June 1999 + + +4.3.2.2. Description + + The SLPSrvTypeCallback type is the type of the callback function + parameter to SLPFindSrvTypes() function. If the hSLP handle + parameter was opened asynchronously, the results returned through the + callback MAY be uncollated. If the hSLP handle parameter was opened + synchronously, then the returned results must be collated and + duplicates eliminated. + +4.3.2.3. Parameters + + hSLP + + The SLPHandle used to initiate the operation. + + pcSrvTypes + + A character buffer containing a comma separated, null + terminated list of service types. + + errCode + + An error code indicating if an error occurred during the + operation. The callback should check this error code before + processing the parameters. If the error code is other than + SLP_OK, then the API library may choose to terminate the + outstanding operation. + + pvCookie + + Memory passed down from the client code that called the + original API function, starting the operation. May be NULL. + +4.3.2.4. Returns + + The client code should return SLP_TRUE if more data is desired, + otherwise SLP_FALSE. + +4.3.3. SLPSrvURLCallback + +4.3.3.1. Synopsis + + + typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP, + const char* pcSrvURL, + unsigned short sLifetime, + SLPError errCode, + void *pvCookie); + + + +Kempf & Guttman Informational [Page 31] + +RFC 2614 Service Location API June 1999 + + +4.3.3.2. Description + + The SLPSrvURLCallback type is the type of the callback function + parameter to SLPFindSrvs() function. If the hSLP handle parameter + was opened asynchronously, the results returned through the callback + MAY be uncollated. If the hSLP handle parameter was opened + synchronously, then the returned results must be collated and + duplicates eliminated. + +4.3.3.3. Parameters + + hSLP + + The SLPHandle used to initiate the operation. + + pcSrvURL + + A character buffer containing the returned service URL. + + sLifetime + + An unsigned short giving the life time of the service + advertisement, in seconds. The value must be an unsigned + integer less than or equal to SLP_LIFETIME_MAXIMUM. + + errCode + + An error code indicating if an error occurred during the + operation. The callback should check this error code before + processing the parameters. If the error code is other than + SLP_OK, then the API library may choose to terminate the + outstanding operation. + + pvCookie + + Memory passed down from the client code that called the + original API function, starting the operation. May be NULL. + +4.3.3.4. Returns + + The client code should return SLP_TRUE if more data is desired, + otherwise SLP_FALSE. + + + + + + + + + +Kempf & Guttman Informational [Page 32] + +RFC 2614 Service Location API June 1999 + + +4.3.4. SLPAttrCallback + +4.3.4.1. Synopsis + + + typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP, + const char* pcAttrList, + SLPError errCode, + void *pvCookie); + + +4.3.4.2. Description + + The SLPAttrCallback type is the type of the callback function + parameter to SLPFindAttrs() function. + + The behavior of the callback differs depending on whether the + attribute request was by URL or by service type. If the + SLPFindAttrs() operation was originally called with a URL, the + callback is called once regardless of whether the handle was opened + asynchronously or synchronously. The pcAttrList parameter contains + the requested attributes as a comma separated list (or is empty if no + attributes matched the original tag list). + + If the SLPFindAttrs() operation was originally called with a service + type, the value of pcAttrList and calling behavior depend on whether + the handle was opened asynchronously or synchronously. If the handle + was opened asynchronously, the callback is called every time the API + library has results from a remote agent. The pcAttrList parameter + MAY be uncollated between calls. It contains a comma separated list + with the results from the agent that immediately returned results. + If the handle was opened synchronously, the results must be collated + from all returning agents and the callback is called once, with the + pcAttrList parameter set to the collated result. + +4.3.4.3. Parameters + + hSLP + + The SLPHandle used to initiate the operation. + + pcAttrList + + A character buffer containing a comma separated, null + terminated list of attribute id/value assignments, in SLP wire + format; i.e. "(attr-id=attr-value-list)" [7]. + + + + + +Kempf & Guttman Informational [Page 33] + +RFC 2614 Service Location API June 1999 + + + errCode + + An error code indicating if an error occurred during the + operation. The callback should check this error code before + processing the parameters. If the error code is other than + SLP_OK, then the API library may choose to terminate the + outstanding operation. + + pvCookie + + Memory passed down from the client code that called the + original API function, starting the operation. May be NULL. + +4.3.4.4. Returns + + The client code should return SLP_TRUE if more data is desired, + otherwise SLP_FALSE. + +4.4. Opening and Closing an SLPHandle + +4.4.1. SLPOpen + +4.4.1.1. Synopsis + + SLPError SLPOpen(const char *pcLang, SLPBoolean isAsync, SLPHandle + *phSLP); + +4.4.1.2. Description + + Returns a SLPHandle handle in the phSLP parameter for the language + locale passed in as the pcLang parameter. The client indicates if + operations on the handle are to be synchronous or asynchronous + through the isAsync parameter. The handle encapsulates the language + locale for SLP requests issued through the handle, and any other + resources required by the implementation. However, SLP properties + are not encapsulated by the handle; they are global. The return + value of the function is an SLPError code indicating the status of + the operation. Upon failure, the phSLP parameter is NULL. + + An SLPHandle can only be used for one SLP API operation at a time. + If the original operation was started asynchronously, any attempt to + start an additional operation on the handle while the original + operation is pending results in the return of an SLP_HANDLE_IN_USE + error from the API function. The SLPClose() API function terminates + any outstanding calls on the handle. If an implementation is unable + to support a asynchronous( resp. synchronous) operation, due to + memory constraints or lack of threading support, the + SLP_NOT_IMPLEMENTED flag may be returned when the isAsync flag is + + + +Kempf & Guttman Informational [Page 34] + +RFC 2614 Service Location API June 1999 + + + SLP_TRUE (resp. SLP_FALSE). + +4.4.1.3. Parameters + + pcLang + + A pointer to an array of characters containing the RFC 1766 + Language Tag [6] for the natural language locale of requests + and registrations issued on the handle. + + isAsync + + An SLPBoolean indicating whether the SLPHandle should be opened + for asynchronous operation or not. + + phSLP + + A pointer to an SLPHandle, in which the open SLPHandle is + returned. If an error occurs, the value upon return is NULL. + +4.4.2. SLPClose + +4.4.2.1. Synopsis + + + void SLPClose(SLPHandle hSLP); + + +4.4.2.2. Description + + Frees all resources associated with the handle. If the handle was + invalid, the function returns silently. Any outstanding synchronous + or asynchronous operations are cancelled so their callback functions + will not be called any further. + +4.4.2.3. Parameters + + SLPHandle + + A SLPHandle handle returned from a call to SLPOpen(). + + + + + + + + + + + +Kempf & Guttman Informational [Page 35] + +RFC 2614 Service Location API June 1999 + + +4.5. Protocol API + +4.5.1. SLPReg + +4.5.1.1. Synopsis + + + SLPError SLPReg(SLPHandle hSLP, + const char *pcSrvURL, + const unsigned short usLifetime, + const char *pcSrvType, + const char *pcAttrs + SLPBoolean fresh, + SLPRegReport callback, + void *pvCookie); + + +4.5.1.2. Description + + Registers the URL in pcSrvURL having the lifetime usLifetime with the + attribute list in pcAttrs. The pcAttrs list is a comma separated + list of attribute assignments in the wire format (including escaping + of reserved characters). The usLifetime parameter must be nonzero + and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is + SLP_TRUE, then the registration is new (the SLP protocol FRESH flag + is set) and the registration replaces any existing registrations. + The pcSrvType parameter is a service type name and can be included + for service URLs that are not in the service: scheme. If the URL is + in the service: scheme, the pcSrvType parameter is ignored. If the + fresh flag is SLP_FALSE, then an existing registration is updated. + Rules for new and updated registrations, and the format for pcAttrs + and pcScopeList can be found in [7]. Registrations and updates take + place in the language locale of the hSLP handle. + + The API library is required to perform the operation in all scopes + obtained through configuration. + +4.5.1.3. Parameters + + hSLP + + The language specific SLPHandle on which to register the + advertisement. + + pcSrvURL + + The URL to register. May not be the empty string. + + + + +Kempf & Guttman Informational [Page 36] + +RFC 2614 Service Location API June 1999 + + + usLifetime + + An unsigned short giving the life time of the service + advertisement, in seconds. The value must be an unsigned + integer less than or equal to SLP_LIFETIME_MAXIMUM and greater + than zero. + + pcSrvType + + The service type. If pURL is a service: URL, then this + parameter is ignored. + + pcAttrs + + A comma separated list of attribute assignment expressions for + the attributes of the advertisement. Use empty string, "" for + no attributes. + + fresh + + An SLPBoolean that is SLP_TRUE if the registration is new or + SLP_FALSE if a reregistration. + + callback + + A callback to report the operation completion status. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + +4.5.1.4. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.5.2. SLPDereg + +4.5.2.1. Synopsis + + + SLPError SLPDereg(SLPHandle hSLP, + const char *pcURL, + SLPRegReport callback, + void *pvCookie); + + + + + +Kempf & Guttman Informational [Page 37] + +RFC 2614 Service Location API June 1999 + + +4.5.2.2. Description + + Deregisters the advertisement for URL pcURL in all scopes where the + service is registered and all language locales. The deregistration + is not just confined to the locale of the SLPHandle, it is in all + locales. The API library is required to perform the operation in all + scopes obtained through configuration. + +4.5.2.3. Parameters + + hSLP + + The language specific SLPHandle to use for deregistering. + + pcURL + + The URL to deregister. May not be the empty string. + + callback + + A callback to report the operation completion status. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + +4.5.2.4. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.5.3. SLPDelAttrs + +4.5.3.1. Synopsis + + + SLPError SLPDelAttrs(SLPHandle hSLP, + const char *pcURL, + const char *pcAttrs, + SLPRegReport callback, + void *pvCookie); + + + + + + + + + +Kempf & Guttman Informational [Page 38] + +RFC 2614 Service Location API June 1999 + + +4.5.3.2. Description + + Delete the selected attributes in the locale of the SLPHandle. The + API library is required to perform the operation in all scopes + obtained through configuration. + +4.5.3.3. Parameters + + hSLP + + The language specific SLPHandle to use for deleting attributes. + + pcURL + + The URL of the advertisement from which the attributes should + be deleted. May not be the empty string. + + pcAttrs + + A comma separated list of attribute ids for the attributes to + deregister. See Section 9.8 in [7] for a description of the + list format. May not be the empty string. + + callback + + A callback to report the operation completion status. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + +4.5.3.4. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.5.4. SLPFindSrvTypes + +4.5.4.1. Synopsis + + + SLPError SLPFindSrvTypes(SLPHandle hSLP, + const char *pcNamingAuthority, + const char *pcScopeList, + SLPSrvTypeCallback callback, + void *pvCookie); + + + + +Kempf & Guttman Informational [Page 39] + +RFC 2614 Service Location API June 1999 + + + The SLPFindSrvType() function issues an SLP service type request for + service types in the scopes indicated by the pcScopeList. The + results are returned through the callback parameter. The service + types are independent of language locale, but only for services + registered in one of scopes and for the indicated naming authority. + + If the naming authority is "*", then results are returned for all + naming authorities. If the naming authority is the empty string, + i.e. "", then the default naming authority, "IANA", is used. "IANA" + is not a valid naming authority name, and it is a PARAMETER_BAD error + to include it explicitly. + + The service type names are returned with the naming authority intact. + If the naming authority is the default (i.e. empty string) then it + is omitted, as is the separating ".". Service type names from URLs + of the service: scheme are returned with the "service:" prefix + intact. [7] See [8] for more information on the syntax of service + type names. + +4.5.4.2. Parameters + + hSLP + + The SLPHandle on which to search for types. + + pcNamingAuthority + + The naming authority to search. Use "*" for all naming + authorities and the empty string, "", for the default naming + authority. + + pcScopeList + + A pointer to a char containing comma separated list of scope + names to search for service types. May not be the empty + string, "". + + callback + + A callback function through which the results of the operation + are reported. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + + + + + +Kempf & Guttman Informational [Page 40] + +RFC 2614 Service Location API June 1999 + + +4.5.4.3. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.5.5. SLPFindSrvs + +4.5.5.1. Synopsis + + + SLPError SLPFindSrvs(SLPHandle hSLP, + const char *pcServiceType, + const char *pcScopeList, + const char *pcSearchFilter, + SLPSrvURLCallback callback, + void *pvCookie); + + +4.5.5.2. Description + + Issue the query for services on the language specific SLPHandle and + return the results through the callback. The parameters determine + the results + +4.5.5.3. Parameters + + hSLP + + The language specific SLPHandle on which to search for + services. + + pcServiceType + + The Service Type String, including authority string if any, for + the request, such as can be discovered using SLPSrvTypes(). + This could be, for example "service:printer:lpr" or + "service:nfs". May not be the empty string. + + pcScopeList + + A pointer to a char containing comma separated list of scope + names. May not be the empty string, "". + + pcSearchFilter + + A query formulated of attribute pattern matching expressions in + the form of a LDAPv3 Search Filter, see [4]. If this filter + is empty, i.e. "", all services of the requested type in the + + + +Kempf & Guttman Informational [Page 41] + +RFC 2614 Service Location API June 1999 + + + specified scopes are returned. + + callback + + A callback function through which the results of the operation + are reported. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + +4.5.5.4. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.5.6. SLPFindAttrs + +4.5.6.1. Synopsis + + + SLPError SLPFindAttrs(SLPHandle hSLP, + const char *pcURLOrServiceType, + const char *pcScopeList, + const char *pcAttrIds, + SLPAttrCallback callback, + void *pvCookie); + + +4.5.6.2. Description + + This function returns service attributes matching the attribute ids + for the indicated service URL or service type. If pcURLOrServiceType + is a service URL, the attribute information returned is for that + particular advertisement in the language locale of the SLPHandle. + + If pcURLOrServiceType is a service type name (including naming + authority if any), then the attributes for all advertisements of that + service type are returned regardless of the language of registration. + Results are returned through the callback. + + The result is filtered with an SLP attribute request filter string + parameter, the syntax of which is described in [7]. If the filter + string is the empty string, i.e. "", all attributes are returned. + + + + + + +Kempf & Guttman Informational [Page 42] + +RFC 2614 Service Location API June 1999 + + +4.5.6.3. Parameters + + hSLP + + The language specific SLPHandle on which to search for + attributes. + + pcURLOrServiceType + + The service URL or service type. See [7] for URL and service + type syntax. May not be the empty string. + + pcScopeList + + A pointer to a char containing a comma separated list of scope + names. May not be 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 [7] for the exact format of the filter + string. + + callback + + A callback function through which the results of the operation + are reported. + + pvCookie + + Memory passed to the callback code from the client. May be + NULL. + +4.5.6.4. Returns + + If an error occurs in starting the operation, one of the SLPError + codes is returned. + +4.6. Miscellaneous Functions + +4.6.1. SLPGetRefreshInterval + +4.6.1.1. Synopsis + + + unsigned short SLPGetRefreshInterval(); + + + +Kempf & Guttman Informational [Page 43] + +RFC 2614 Service Location API June 1999 + + +4.6.1.2. Description + + Returns the maximum across all DAs of the min-refresh-interval + attribute. This value satisfies the advertised refresh interval + bounds for all DAs, and, if used by the SA, assures that no refresh + registration will be rejected. If no DA advertises a min-refresh- + interval attribute, a value of 0 is returned. + +4.6.1.3. Returns + + If no error, the maximum refresh interval value allowed by all DAs (a + positive integer). If no DA advertises a min-refresh-interval + attribute, returns 0. If an error occurs, returns an SLP error code. + +4.6.2. SLPFindScopes + +4.6.2.1. Synopsis + + + SLPError SLPFindScopes(SLPHandle hSLP, + char** ppcScopeList); + + +4.6.2.2. Description + + Sets ppcScopeList parameter to a pointer to a comma separated list + including all available scope values. The list of scopes comes from + a variety of sources: the configuration file's net.slp.useScopes + property, unicast to DAs on 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 name in the list, the default scope, + "DEFAULT". + +4.6.2.3. Parameters + + hSLP + + The SLPHandle on which to search for scopes. + + ppcScopeList + + A pointer to char pointer into which the buffer pointer is + placed upon return. The buffer is null terminated. The memory + should be freed by calling SLPFree(). + + + + + + +Kempf & Guttman Informational [Page 44] + +RFC 2614 Service Location API June 1999 + + +4.6.2.4. Returns + + If no error occurs, returns SLP_OK, otherwise, the appropriate error + code. + +4.6.3. SLPParseSrvURL + +4.6.3.1. Synopsis + + + SLPError SLPParseSrvURL(char *pcSrvURL + SLPSrvURL** ppSrvURL); + + +4.6.3.2. Description + + Parses the URL passed in as the argument into a service URL structure + and returns it in the ppSrvURL pointer. If a parse error occurs, + returns SLP_PARSE_ERROR. The input buffer pcSrvURL is destructively + modified during the parse and used to fill in the fields of the + return structure. The structure returned in ppSrvURL should be freed + with SLPFreeURL(). If the URL has no service part, the s_pcSrvPart + string is the empty string, "", i.e. not NULL. If pcSrvURL is not a + service: URL, then the s_pcSrvType field in the returned data + structure is the URL's scheme, which might not be the same as the + service type under which the URL was registered. If the transport is + IP, the s_pcTransport field is the empty string. If the transport is + not IP or there is no port number, the s_iPort field is zero. + +4.6.3.3. Parameters + + pcSrvURL + + A pointer to a character buffer containing the null terminated + URL string to parse. It is destructively modified to produce + the output structure. + + ppSrvURL + + A pointer to a pointer for the SLPSrvURL structure to receive + the parsed URL. The memory should be freed by a call to + SLPFree() when no longer needed. + +4.6.3.4. Returns + + If no error occurs, the return value is SLP_OK. Otherwise, the + appropriate error code is returned. + + + + +Kempf & Guttman Informational [Page 45] + +RFC 2614 Service Location API June 1999 + + +4.6.4. SLPEscape + +4.6.4.1. Synopsis + + + SLPError SLPEscape(const char* pcInbuf, + char** ppcOutBuf, + SLPBoolean isTag); + + +4.6.4.2. Description + + Process the input string in pcInbuf and escape any SLP reserved + characters. If the isTag parameter is SLPTrue, then look for bad tag + characters and signal an error if any are found by returning the + SLP_PARSE_ERROR code. The results are put into a buffer allocated by + the API library and returned in the ppcOutBuf parameter. This buffer + should be deallocated using SLPFree() when the memory is no longer + needed. + +4.6.4.3. Parameters + + pcInbuf + + Pointer to he input buffer to process for escape characters. + + ppcOutBuf + + Pointer to a pointer for the output buffer with the SLP + reserved characters escaped. Must be freed using SLPFree() + when the memory is no longer needed. + + isTag + + When true, the input buffer is checked for bad tag characters. + +4.6.4.4. Returns + + Return SLP_PARSE_ERROR if any characters are bad tag characters and + the isTag flag is true, otherwise SLP_OK, or the appropriate error + code if another error occurs. + + + + + + + + + + +Kempf & Guttman Informational [Page 46] + +RFC 2614 Service Location API June 1999 + + +4.6.5. SLPUnescape + +4.6.5.1. Synopsis + + + SLPError SLPUnescape(const char* pcInbuf, + char** ppcOutBuf, + SLPBoolean isTag); + + +4.6.5.2. Description + + Process the input string in pcInbuf and unescape any SLP reserved + characters. If the isTag parameter is SLPTrue, then look for bad tag + characters and signal an error if any are found with the + SLP_PARSE_ERROR code. No transformation is performed if the input + string is an opaque. The results are put into a buffer allocated by + the API library and returned in the ppcOutBuf parameter. This buffer + should be deallocated using SLPFree() when the memory is no longer + needed. + +4.6.5.3. Parameters + + pcInbuf + + Pointer to he input buffer to process for escape characters. + + ppcOutBuf + + Pointer to a pointer for the output buffer with the SLP + reserved characters escaped. Must be freed using SLPFree() + when the memory is no longer needed. + + isTag + + When true, the input buffer is checked for bad tag characters. + +4.6.5.4. Returns + + Return SLP_PARSE_ERROR if any characters are bad tag characters and + the isTag flag is true, otherwise SLP_OK, or the appropriate error + code if another error occurs. + + + + + + + + + +Kempf & Guttman Informational [Page 47] + +RFC 2614 Service Location API June 1999 + + +4.6.6. SLPFree + +4.6.6.1. Synopsis + + + void SLPFree(void* pvMem); + + +4.6.6.2. Description + + Frees memory returned from SLPParseSrvURL(), SLPFindScopes(), + SLPEscape(), and SLPUnescape(). + +4.6.6.3. Parameters + + pvMem + + A pointer to the storage allocated by the SLPParseSrvURL(), + SLPEscape(), SLPUnescape(), or SLPFindScopes() function. + Ignored if NULL. + +4.6.7. SLPGetProperty + +4.6.7.1. Synopsis + + + const char* SLPGetProperty(const char* pcName); + + +4.6.7.2. Description + + Returns the value of the corresponding SLP property name. The + returned string is owned by the library and MUST NOT be freed. + +4.6.7.3. Parameters + + pcName + + Null terminated string with the property name, from + Section 2.1. + +4.6.7.4. Returns + + If no error, returns a pointer to a character buffer containing the + property value. If the property was not set, returns the default + value. If an error occurs, returns NULL. The returned string MUST + NOT be freed. + + + + +Kempf & Guttman Informational [Page 48] + +RFC 2614 Service Location API June 1999 + + +4.6.8. SLPSetProperty + +4.6.8.1. Synopsis + + + void SLPSetProperty(const char *pcName, + const char *pcValue); + + +4.6.8.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.6.8.3. Parameters + + pcName + + Null terminated string with the property name, from + Section 2.1. + + pcValue + + Null terminated string with the property value, in UTF-8 + character encoding. + +4.7. Implementation Notes + +4.7.1. Refreshing Registrations + + Clients indicate that they want URLs to be automatically refreshed by + setting the usLifetime parameter in the SLPReg() function call to + SLP_LIFETIME_MAXIMUM. This will cause the API implementation to + refresh the URL before it times out. Although using + SLP_LIFETIME_MAXIMUM to designate automatic reregistration means that + a transient URL can't be registered for the maximum lifetime, little + hardship is likely to occur, since service URL lifetimes are measured + in seconds and the client can simply use a lifetime of + SLP_LIFETIME_MAXIMUM - 1 if a transient URL near the maximum lifetime + is desired. API implementations MUST provide this facility. + +4.7.2. Syntax for String Parameters + + Query strings, attribute registration lists, attribute deregistration + lists, scope lists, and attribute selection lists follow the syntax + described in [7] 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 + + + +Kempf & Guttman Informational [Page 49] + +RFC 2614 Service Location API June 1999 + + + clients. As a consequence, clients are responsible for formatting + request strings, including escaping and converting opaque values to + escaped byte encoded strings. Similarly, on output, clients are + required to unescape strings and convert escaped string encoded + opaques to binary. The functions SLPEscape() and SLPUnescape() can + be used for escaping SLP reserved characters, but perform no opaque + processing. + + Opaque values consist of a character buffer containing a UTF-8- + encoded string, the first characters of which are the nonUTF-8 + encoding '\ff'. Subsequent characters are the escaped values for the + original bytes in the opaque. The escape convention is relatively + simple. An escape consists of a backslash followed by the two + hexadecimal digits encoding the byte. An example is '\2c' for the + byte 0x2c. Clients handle opaque processing themselves, since the + algorithm is relatively simple and uniform. + +4.7.3. Client Side Syntax Checking + + Client side API implementations may do syntax checking of scope + names, naming authority names, and service type names, 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. + +4.7.4. System Properties + + The system properties established in the configuration file are + accessible through the SLPGetProperty() and SLPSetProperty() + functions. The SLPSetProperty() function only modifies properties in + the running process, not in the configuration file. Properties are + global to the process, affecting all threads and all handles created + with SLPOpen. Errors are checked when the property is used and, as + with parsing the configuration file, are logged. Program execution + continues without interruption by substituting the default for the + erroneous parameter. With the exception of net.slp.locale, + net.slp.typeHint, and net.slp.maxResults, clients of the API should + rarely be required to override these properties, since they reflect + properties of the SLP network that are not of concern to individual + agents. If changes are required, system administrators should modify + the configuration file. + + + + + + + +Kempf & Guttman Informational [Page 50] + +RFC 2614 Service Location API June 1999 + + +4.7.5. Memory Management + + The only API functions returning memory specifically requiring + deallocation on the part of the client are SLPParseSrvURL(), + SLPFindScopes(), SLPEscape(), and SLPUnescape(). This memory should + be freed using SLPFree() when no longer needed. Character strings + returned via the SLPGetProperty() function should NOT be freed, they + are owned by the SLP library. + + Memory passed to callbacks belongs to the library and MUST NOT be + retained by the client code. Otherwise, crashes are possible. + Clients are required to copy data out of the callback parameters. No + other use of the parameter memory in callback parameters is allowed. + +4.7.6. Asynchronous and Incremental Return Semantics + + If a handle parameter to an API function was opened asynchronously, + API function calls on the handle check the other parameters, open the + appropriate operation and return immediately. In an error occurs in + the process of starting the operation, an error code is returned. If + the handle parameter was opened synchronously, the API function call + blocks until all results are available, and returns only after the + results are reported through the callback function. The return code + indicates whether any errors occurred both starting and during the + operation. + + The callback function is called whenever the API library has results + to report. The callback code is required to check the error code + parameter before looking at the other parameters. If the error code + is not SLP_OK, the other parameters may be invalid. The API library + has the option of terminating any outstanding operation on which an + error occurs. The callback code can similarly indicate that the + operation should be terminated by passing back SLP_FALSE. Callback + functions are not permitted to recursively call into the API on the + same SLPHandle. If an attempt is made to recursively call into the + API, the API function returns SLP_HANDLE_IN_USE. Prohibiting + recursive callbacks on the same handle simplifies implementation of + thread safe code, since locks held on the handle will not be in place + during a second outcall on the handle. On the other hand, it means + that handle creation should be fairly lightweight so a client program + can easily support multiple outstanding calls. + + The total number of results received can be controlled by setting the + net.slp.maxResults parameter. + + On the last call to a callback, whether asynchronous or synchronous, + the status code passed to the callback has value SLP_LAST_CALL. There + are four reasons why the call can terminate: + + + +Kempf & Guttman Informational [Page 51] + +RFC 2614 Service Location API June 1999 + + + DA reply received + + A reply from a DA has been received and therefore nothing more + is expected. + + Multicast terminated + + The multicast convergence time has elapsed and the API library + multicast code is giving up. + + Multicast null results + + Nothing new has been received during multicast for a while and + the API library multicast code is giving up on that (as an + optimization). + + Maximum results + + The user has set the net.slp.maxResults property and that + number of replies has been collected and returned + +4.8. Example + + This example illustrates how to discover a mailbox. + + A POP3 server registers itself with the SLP framework. The + attributes it registers are "USER", a list of all users whose mail is + available through the POP3 server. + + The POP3 server code is the following: + + SLPHandle slph; + SLPRegReport errCallback = POPRegErrCallback; + + /* Create an English SLPHandle, asynchronous processing. */ + + SLPError err = SLPOpen("en", SLP_TRUE, &slph); + + if( err != SLP_OK ) { + + /* Deal with error. */ + + } + + /* Create the service: URL and attribute parameters. */ + + const char* surl = "service:pop3://mail.netsurf.de"; /* the URL */ + + + + +Kempf & Guttman Informational [Page 52] + +RFC 2614 Service Location API June 1999 + + + const char *pcAttrs = "(user=zaphod,trillian,roger,marvin)" + + /* Perform the registration. */ + + err = SLPReg(slph, + surl, + SLP_LIFETIME_DEFAULT, + ppcAttrs, + errCallback, + NULL); + + if (err != SLP_OK ) { + + /*Deal with error.*/ + + } + + + The errCallback reports any errors: + + void + POPRegErrCallback(SLPHandle hSLP, + SLPError errCode, + unsigned short usLifetime, + void* pvCookie) { + + if( errCode != SLP_OK ) { + + /* Report error through a dialog, message, etc. */ + + } + + /*Use lifetime interval to update periodically. */ + + } + + The POP3 client locates the server for the user with the following + code: + + /* + * The client calls SLPOpen(), exactly as above. + */ + + const char *pcSrvType = "service:pop3"; /* the service type */ + const char *pcScopeList = "default"; /* the scope */ + const char *pcFilter = "(user=roger)"; /* the search filter */ + SLPSrvURLCallback srvCallback = /* the callback */ + POPSrvURLCallback; + + + +Kempf & Guttman Informational [Page 53] + +RFC 2614 Service Location API June 1999 + + + err = SLPFindSrvs(slph, + pcSrvType, pcScopeList, pcFilter, + srvCallback, NULL); + + if( err != SLP_OK ) { + + /* Deal with error. */ + + } + + Within the callback, the client code can use the returned POP + service: + + SLPBoolean + POPSrvURLCallback(SLPHandle hSLP, + const char* pcSrvURL, + unsigned short sLifetime, + SLPError errCode, + void* pvCookie) { + + if( errCode != SLP_OK ) { + + /* Deal with error. */ + + } + + SLPSrvURL* pSrvURL; + + errCode = SLPParseSrvURL(pcSrvURL, &pSrvURL); + + if (err != SLP_OK ) { + + /* Deal with error. */ + + } else { + + /* get the server's address */ + + struct hostent *phe = gethostbyname(pSrvURL.s_pcHost); + + /* use hostname in pSrvURL to connect to the POP3 server + * . . . + */ + + SLPFreeSrvURL((void*)pSrvURL); /* Free the pSrvURL storage */ + } + + return SLP_FALSE; /* Done! */ + + + +Kempf & Guttman Informational [Page 54] + +RFC 2614 Service Location API June 1999 + + + } + + A client that wanted to discover all the users receiving mail at the + server uses with the following query: + + /* + * The client calls SLPOpen(), exactly as above. We assume the + * service: URL was retrieved into surl. + */ + + const char *pcScopeList = "default"; /* the scope */ + const char *pcAttrFilter = "use"; /* the attribute filter */ + SLPAttrCallback attrCallBack = /* the callback */ + POPUsersCallback + + + err = + SLPFindAttrs(slph, + surl, + pcScopeList, pcAttrFilter, + attrCallBack, NULL); + + if( err != SLP_OK ) { + + /* Deal with error. */ + + } + + The callback processes the attributes: + + SLPBoolean + POPUsersCallback(const char* pcAttrList, + SLPError errCode, + void* pvCookie) { + + if( errCode != SLP_OK ) { + + /* Deal with error. */ + + } else { + + /* Parse attributes. */ + + } + + return SLP_FALSE; /* Done! */ + + } + + + +Kempf & Guttman Informational [Page 55] + +RFC 2614 Service Location API June 1999 + + +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 modeled 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, ServiceType, and + ServiceLocationAttribute classes model the basic SLP 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 "slp". Thus, the name for a hypothetical + implementation from the University of Michigan would look like: + + edu.umich.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 non-null. 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 relevant + parameters could be erroneous. + + Standard Java practice is to encode every exceptional condition as a + separate 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 + + + +Kempf & Guttman Informational [Page 56] + +RFC 2614 Service Location API June 1999 + + + as MEMORY_ALLOC_FAILED. + +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 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 LANGUAGE_NOT_SUPPORTED = 1 + public static final short PARSE_ERROR = 2 + public static final short INVALID_REGISTRATION = 3 + public static final short SCOPE_NOT_SUPPORTED = 4 + public static final short AUTHENTICATION_ABSENT = 6 + public static final short AUTHENTICATION_FAILED = 7 + public static final short INVALID_UPDATE = 13 + public static final short REFRESH_REJECTED = 15 + public static final short NOT_IMPLEMENTED = 16 + public static final short NETWORK_INIT_FAILED 17 + public static final short NETWORK_TIMED_OUT = 18 + public static final short NETWORK_ERROR = 19 + public static final short INTERNAL_SYSTEM_ERROR = 20 + public static final short TYPE_ERROR = 21 + public static final short BUFFER_OVERFLOW = 22 + + +5.2.1.4. Instance Methods + + + public short getErrorCode() + + + Return the error code. The error code takes on one of the static + field values. + + + + + +Kempf & Guttman Informational [Page 57] + +RFC 2614 Service Location API June 1999 + + +5.3. Basic Data Structures + +5.3.1. Interface ServiceLocationEnumeration + + + public interface ServiceLocationEnumeration + extends Enumeration + + +5.3.1.1. Description + + The ServiceLocationEnumeration class is the return type for all + Locator SLP operations. The Java API library may implement this + class to block until results are available from the SLP operation, so + that the client can achieve asynchronous operation by retrieving + results from the enumeration in a separate thread. Clients use the + superclass nextElement() method if they are unconcerned with SLP + exceptions. + +5.3.1.2. Instance Methods + + + public abstract Object next() throws ServiceLocationException + + Return the next value or block until it becomes available. + + Throws: + + ServiceLocationException + + Thrown if the SLP operation encounters an error. + + NoSuchElementException + + If there are no more elements to return. + + +5.3.2. Class ServiceLocationAttribute + +5.3.2.1. Synopsis + + + public class ServiceLocationAttribute + extends Object implements Serializable + + + + + + + +Kempf & Guttman Informational [Page 58] + +RFC 2614 Service Location API June 1999 + + +5.3.2.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.2.3. Constructors + + + public ServiceLocationAttribute(String id,Vector values) + + + Construct a service location attribute. Errors in the id or values + vector result in an IllegalArgumentException. + + 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 the + parameter should be null. String values can consist of any + Unicode character. + + +5.3.2.4. Class Methods + + + public static String escapeId(String id) + + + Returns an escaped version of the id parameter, suitable for + inclusion in a query. Any reserved characters as specified in [7] + are escaped using UTF-8 encoding. If any characters in the tag are + illegal, throws IllegalArgumentException. + + Parameters: + + id + + The attribute id to escape. ServiceLocationException is thrown + if any characters are illegal for an attribute tag. + + + +Kempf & Guttman Informational [Page 59] + +RFC 2614 Service Location API June 1999 + + + public static String escapeValue(Object value) + + + Returns a String containing the escaped value parameter as a string, + suitable for inclusion in a query. If the parameter is a string, + any reserved characters as specified in [7] are escaped using UTF-8 + encoding. If the parameter is a byte array, then the escaped string + begins with the nonUTF-8 sequence `\ff` and the rest of the string + consists of the escaped bytes, which is the encoding for opaques. + If the value parameter is a Boolean or Integer, then the returned + string contains the object converted into a string. If the value + is any type other than String, Integer, Boolean or byte[], an + IllegalArgumentException is thrown. + + Parameters: + + value + + The attribute value to be converted into a string and escaped. + + +5.3.2.5. Instance Methods + + + public Vector getValues() + + + Returns a cloned vector of attribute values, or null if the attribute + is a keyword attribute. If the attribute is single-valued, then the + vector contains only one object. + + + public String getId() + + + Returns the attribute's name. + + + public boolean equals(Object o) + + + Overrides Object.equals(). Two attributes are equal if their + identifiers are equal and their value vectors contain the same number + of equal values as determined by the Object equals() method. Values + having byte[] type are equal if the contents of all byte arrays in + both attribute vectors match. Note that the SLP string matching + algorithm [7] MUST NOT be used for comparing attribute identifiers or + string values. + + + +Kempf & Guttman Informational [Page 60] + +RFC 2614 Service Location API June 1999 + + + public String toString() + + + Overrides Object.toString(). The string returned contains a + formatted representation of the attribute, giving the attribute's + id, values, and the Java type of the values. The returned string is + suitable for debugging purposes, but is not in SLP wire format. + + + public int hashCode() + + + Overrides Object.hashCode(). Hashes on the attribute's identifier. + + +5.3.3. Class ServiceType + +5.3.3.1. Synopsis + + + public class ServiceType extends Object implements Serializable + + +5.3.3.2. Description + + The ServiceType object models the SLP service type. It parses a + string based service type specifier into its various components, and + contains property accessors to return the components. URL schemes, + protocol service types, and abstract service types are all handled. + +5.3.3.3. Constructors + + + public ServiceType(String type) + + + Construct a service type object from the service type specifier. + Throws IllegalArgumentException if the type name is syntactically + incorrect. + + Parameters: + + type + + The service type name as a String. If the service type is from + a service: URL, the "service:" prefix must be intact. + + + + + +Kempf & Guttman Informational [Page 61] + +RFC 2614 Service Location API June 1999 + + +5.3.3.4. Methods + + + public boolean isServiceURL() + + + Returns true if the type name contains the "service:" prefix. + + + public boolean isAbstractType() + + + Returns true if the type name is for an abstract type. + + + public boolean isNADefault() + + Returns true if the naming authority is the default, i.e. is the + empty string. + + + public String getConcreteTypeName() + + + Returns the concrete type name in an abstract type, or the empty + string if the service type is not abstract. For example, if the type + name is "service:printing:ipp", the method returns "ipp". If the + type name is "service:ftp", the method returns "". + + + public String getPrincipleTypeName() + + + Returns the abstract type name for an abstract type, the protocol + name in a protocol type, or the URL scheme for a generic URL. For + example, in the abstract type name "service:printing:ipp", the method + returns "printing". In the protocol type name "service:ftp", the + method returns "ftp". + + + public String getAbstractTypeName() + + + If the type is an abstract type, returns the fully formatted abstract + type name including the "service:" and naming authority but without + the concrete type name or intervening colon. If not an abstract + type, returns the empty string. For example, in the abstract type + name "service:printing:ipp", the method returns "service:printing". + + + +Kempf & Guttman Informational [Page 62] + +RFC 2614 Service Location API June 1999 + + + public String getNamingAuthority() + + + Return the naming authority name, or the empty string if the naming + authority is the default. + + + public boolean equals(Object obj) + + + Overrides Object.equals(). The two objects are equal if they are + both ServiceType objects and the components of both are equal. + + + public String toString() + + + Returns the fully formatted type name, including the "service:" if + the type was originally from a service: URL. + + + public int hashCode() + + + Overrides Object.hashCode(). Hashes on the string value of the + "service" prefix, naming authority, if any, abstract and concrete + type names for abstract types, protocol type name for protocol types, + and URL scheme for generic URLs. + + +5.3.4. Class ServiceURL + +5.3.4.1. Synopsis + + + public class ServiceURL extends Object implements Serializable + + +5.3.4.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. + + + + + + +Kempf & Guttman Informational [Page 63] + +RFC 2614 Service Location API June 1999 + + +5.3.4.3. Class Variables + + + public static final int NO_PORT = 0 + + + Indicates that no port information is required or was returned for + this URL. + + + public static final int LIFETIME_NONE = 0 + + + Indicates that the URL has a zero lifetime. This value is never + returned from the API, but can be used to create a ServiceURL object + to deregister, delete attributes, or find attributes. + + + public static final int LIFETIME_DEFAULT = 10800 + + + The default URL lifetime (3 hours) in seconds. + + + public static final int LIFETIME_MAXIMUM = 65535 + + + The maximum URL lifetime (about 18 hours) in seconds. + + + public static final int LIFETIME_PERMANENT = -1 + + + Indicates that the API implementation should continuously re-register + the URL until the application exits. + + +5.3.4.4. Constructors + + + public ServiceURL(String URL,int lifetime) + + + Construct a service URL object having the specified lifetime. + + + + + + + +Kempf & Guttman Informational [Page 64] + +RFC 2614 Service Location API June 1999 + + + Parameters: + + URL + + The URL as a string. Must be either a service: URL or a valid + generic URL according to RFC 2396 [2]. + + lifetime + + The service advertisement lifetime in seconds. This value may + be between LIFETIME_NONE and LIFETIME_MAXIMUM. + + +5.3.4.5. Methods + + + public ServiceType getServiceType() + + + Returns the service type object representing the service type name of + the URL. + + + public final void setServiceType(ServiceType type) + throws ServiceLocationException + + + Set the service type name to the object. Ignored if the URL is a + service: URL. + + Parameters: + + type + + The service type object. + + + public String getTransport() + + + Get the network layer transport identifier. If the transport is IP, + an empty string, "", is returned. + + + public String getHost() + + + + + + +Kempf & Guttman Informational [Page 65] + +RFC 2614 Service Location API June 1999 + + + Returns the host identifier. For IP, this will be the machine name + or IP address. + + + public int getPort() + + + Returns the port number, if any. For non-IP transports, always + returns NO_PORT. + + + public String getURLPath() + + + Returns the URL path description, if any. + + + public int getLifetime() + + + Returns the service advertisement lifetime. This will be a positive + int between LIFETIME_NONE and LIFETIME_MAXIMUM. + + + public boolean equals(Object obj) + + + Compares the object to the ServiceURL and returns true if the two are + the same. Two ServiceURL objects are equal if their current service + types match and they have the same host, port, transport, and URL + path. + + + public String toString() + + + Returns a formatted string with the URL. Overrides Object.toString(). + The returned URL has the original service type or URL scheme, not the + current service type. + + + public int hashCode() + + + Overrides Object.hashCode(). Hashes on the current service type, + transport, host, port, and URL part. + + + + + +Kempf & Guttman Informational [Page 66] + +RFC 2614 Service Location API June 1999 + + +5.4. SLP Access Interfaces + +5.4.1. Interface Advertiser + +5.4.1.1. Synopsis + + + public interface Advertiser + + +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 attributes) + throws ServiceLocationException + + Register a new service with SLP having the given attributes. + + The API library is required to perform the operation in all + scopes obtained through configuration. + + + Parameters: + + URL + + The URL for the service. + + attributes + + A vector of ServiceLocationAttribute objects describing the + service. + + + +Kempf & Guttman Informational [Page 67] + +RFC 2614 Service Location API June 1999 + + + public abstract void deregister(ServiceURL URL) + throws ServiceLocationException + + + Deregister a service from the SLP framework. This has the effect + of deregistering the service from every language locale. The API + library is required to perform the operation in all scopes obtained + through configuration. + + Parameters: + + URL + + The URL for the service. + + + public abstract void + addAttributes(ServiceURL URL, + Vector attributes) + throws ServiceLocationException + + + Update the registration by adding the given attributes. The API + library is required to perform the operation in all scopes obtained + through configuration. + + Parameters: + + URL + + The URL for the service. + + attributes + + A Vector of ServiceLocationAttribute objects to add to the + existing registration. Use an empty vector to update the URL + alone. May not be null. + + + public abstract void + deleteAttributes(ServiceURL URL, + Vector attributeIds) + throws ServiceLocationException + + + Delete the attributes from a URL for the locale with which the + Advertiser was created. The API library is required to perform the + operation in all scopes obtained through configuration. + + + +Kempf & Guttman Informational [Page 68] + +RFC 2614 Service Location API June 1999 + + + Parameters: + + URL + + The URL for the service. + + attributeIds + + A vector of Strings indicating the ids of the attributes + to remove. The strings may be attribute ids or they + may be wildcard patterns to match ids. See [7] for the + syntax of wildcard patterns. The strings may include SLP + reserved characters, they will be escaped by the API before + transmission. May not be the empty vector or null. + + +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 ServiceLocationEnumeration + findServiceTypes(String namingAuthority, + Vector scopes) + throws ServiceLocationException + + + + + +Kempf & Guttman Informational [Page 69] + +RFC 2614 Service Location API June 1999 + + + Returns an enumeration of ServiceType objects giving known service + types for the given scopes and given naming authority. If no service + types are found, an empty enumeration is returned. + + Parameters: + + namingAuthority + + The naming authority. Use "" for the default naming authority + and "*" for all naming authorities. + + scopes + + A Vector of scope names. The vector should be selected from + the results of a findScopes() API invocation. Use "DEFAULT" + for the default scope. + + + public abstract ServiceLocationEnumeration + findServices(ServiceType type, + Vector scopes, + String searchFilter) + throws ServiceLocationException + + + Returns a vector of ServiceURL objects for services matching the + query, and having a matching type in the given scopes. If no + services are found, an empty enumeration is returned. + + Parameters: + + type + + The SLP service type of the service. + + scopes + + A Vector of scope names. The vector should be selected from + the results of a findScopes() API invocation. Use "DEFAULT" + for the default scope. + + searchFilter + + An LDAPv3 [4] string encoded query. If the filter is empty, + i.e. "", all services of the requested type in the specified + scopes are returned. SLP reserved characters must be escaped + in the query. Use ServiceLocationAttribute.escapeId() and + ServiceLocationAttribute.escapeValue() to construct the query. + + + +Kempf & Guttman Informational [Page 70] + +RFC 2614 Service Location API June 1999 + + + public abstract ServiceLocationEnumeration + 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 enumeration is returned. + + Parameters: + + URL + + The URL for which the attributes are desired. + + scopes + + A Vector of scope names. The vector 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 [7], the patterns may include wildcards to match substrings. + The strings may include SLP reserved characters, they will be + escaped by the API before transmission. + + + public abstract ServiceLocationEnumeration + findAttributes(ServiceType type, + Vector scopes, + Vector attributeIds) + throws ServiceLocationException + + + For the type and scope, return a Vector of all ServiceLocationAttribute + objects whose ids match the String patterns in the attributeIds + Vector regardless of the Locator's locale. The request is made + independent of language locale. If no attributes are found, an empty + vector is returned. + + + + + + +Kempf & Guttman Informational [Page 71] + +RFC 2614 Service Location API June 1999 + + + Parameters: + + serviceType + + The service type. + + scopes + + A Vector of scope names. The vector 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 [7], the patterns may include wildcards to + match all prefixes or suffixes. The patterns may include SLP + reserved characters, they will be escaped by the API before + transmission. + +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. + +5.5.1.3. Class Methods + + + public static int getRefreshInterval() + throws ServiceLocationException + + + + + + + +Kempf & Guttman Informational [Page 72] + +RFC 2614 Service Location API June 1999 + + + Returns the maximum across all DAs of the min-refresh-interval + attribute. This value satisfies the advertised refresh interval + bounds for all DAs, and, if used by the SA, assures that no + refresh registration will be rejected. If no DA advertises a + min-refresh-interval attribute, a value of 0 is returned. + + + public static Vector findScopes() + throws ServiceLocationException + + + Returns an Vector of strings with all available scope names. The + list of scopes comes from a variety of sources, see Section 2.1 for + the scope discovery algorithm. 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 SLP 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 SLP locale + is used if null. + + + + +Kempf & Guttman Informational [Page 73] + +RFC 2614 Service Location API June 1999 + + +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 [8]. 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 (though they may get a TYPE_ERROR if the + implementation supports type checking and there is a mismatch with + the template). + +5.6.1.3. Class Methods + + + public static TemplateRegistry getTemplateRegistry(); + + + Returns the distinguished TemplateRegistry object for performing + operations on and with service templates. Returns null if the + implementation doesn't support TemplateRegistry functionality. + +5.6.1.4. Instance Methods + + + public abstract void + registerServiceTemplate(ServiceType type, + String documentURL, + Locale locale, + String version) + throws ServiceLocationException + + + Register the service template with the template registry. + + + + + + +Kempf & Guttman Informational [Page 74] + +RFC 2614 Service Location API June 1999 + + + Parameters: + + type + + The service type. + + documentURL + + A string containing the URL of the template document. May not + be the empty string. + + locale + + A Locale object containing the language locale of the template. + + version + + The version number identifier of template document. + + + public abstract void + + + deregisterServiceTemplate(ServiceType type, + Locale locale, + String version) + throws ServiceLocationException + + + Deregister the template for the service type. + + Parameters: + + type + + The service type. + + 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. + + + + + + +Kempf & Guttman Informational [Page 75] + +RFC 2614 Service Location API June 1999 + + + public abstract + String findTemplateURL(ServiceType type, + Locale locale, + String version) + throws ServiceLocationException + + + Returns the URL for the template document. + + Parameters: + + type + + The service type. + + 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. May not be the + empty string. + + + + + + + + + +Kempf & Guttman Informational [Page 76] + +RFC 2614 Service Location API June 1999 + + +5.6.2. Interface ServiceLocationAttributeVerifier + +5.6.2.1. Synopsis + + + public interface ServiceLocationAttributeVerifier + + +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 ServiceType getServiceType() + + + Returns the SLP service type for which this is the verifier. + + + public abstract Locale getLocale() + + + Return the language locale of the template. + + + public abstract String getVersion() + + + Return the template version number identifier. + + + public abstract String getURLSyntax() + + + Return the URL syntax expression for the service: URL. + + + public abstract String getDescription() + + + + + +Kempf & Guttman Informational [Page 77] + +RFC 2614 Service Location API June 1999 + + + Return the descriptive help text for the template. + + + public abstract ServiceLocationAttributeDescriptor + getAttributeDescriptor(String attrId) + + + Return the ServiceLocationAttributeDescriptor for the attribute + having the named id. If no such attribute exists in this template, + return null. This method is primarily for GUI tools to display + attribute information. Programmatic verification of attributes + should use the verifyAttribute() method. + + + public abstract Enumeration + getAttributeDescriptors() + + + Returns an Enumeration allowing introspection on the attribute + definition in the service template. The Enumeration returns + ServiceLocationAttributeDescriptor objects for the attributes. + 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 + + + + +Kempf & Guttman Informational [Page 78] + +RFC 2614 Service Location API June 1999 + + + Verify that the Vector of ServiceLocationAttribute objects matches + the template for this service type. The vector must contain all the + required attributes, and all attributes must match their template + definitions. 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 definition. 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 Informational [Page 79] + +RFC 2614 Service Location API June 1999 + + + 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 + getRequiresExplicitMatch() + + + + +Kempf & Guttman Informational [Page 80] + +RFC 2614 Service Location API June 1999 + + + 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 getIsMultivalued() + + + Returns true if the "M" flag is set. + + + public abstract boolean getIsOptional() + + + Returns true if the "O"" flag is set. + + + public abstract boolean getIsLiteral() + + + Returns true if the "L" flag is set. + + + public abstract boolean getIsKeyword() + + + Returns true if the attribute is a keyword attribute. + + +5.7. Implementation Notes + +5.7.1. Refreshing Registrations + + A special lifetime constant, ServiceURL.LIFETIME_PERMANENT, is used + by clients to indicate that the URL should be automatically refreshed + until the application exits. The API implementation should interpret + this flag as indicating that the URL lifetime is + ServiceURL.LIFETIME_MAXIMUM, and MUST arrange for automatic refresh + to occur. + +5.7.2. Parsing Alternate Transports in ServiceURL + + The ServiceURL class is designed to handle multiple transports. The + standard API performs no additional processing on transports other + than IP except to separate out the host identifier and the URL path. + However, implementations are free to subclass ServiceURL and support + additional methods that provide more detailed parsing of alternate + transport information. For IP transport, the port number, if any, is + + + +Kempf & Guttman Informational [Page 81] + +RFC 2614 Service Location API June 1999 + + + returned from the getPort() method. For non-IP transports, the + getPort() method returns NO_PORT. + +5.7.3. String Attribute Values + + In general, translation between Java types for attribute values and + the SLP on-the-wire string is straightforward. However, there are + two corner cases. If the Java attribute value type is String and the + value of the string has an on-the-wire representation that is + inferred by SLP as an integer, the registered attribute value may not + be what the API client intended. A similar problem could result if + the Java attribute value is the string "true" or "false", in which + case the on-the-wire representation is inferred to boolean. To + handle these corner cases, the Java API prepends a space onto the + string. So, for example, if the string attribute value is "123", the + Java API transforms the value to "123 ", which will have an on-the- + wire representation that is inferred by SLP to be string. Since + appended and prepended spaces have no effect on query handling, this + procedure should cause no problem with queries. API clients need to + be aware, however, that the transformation is occurring. + +5.7.4. Client Side Syntax Checking + + The syntax of scope names, service type names, naming authority + names, and URLs is described in [7] and [8]. 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 clients to obtain + escaped attribute id and value strings to facilitate query + construction. + +5.7.5. Language Locale Handling + + The Locator and Advertiser interfaces are created with a Locale + parameter. The language locale with which these objects are created + is used in all SLP requests issued through the object. If the Locale + parameter is null, the default SLP locale is used. The default SLP + locale is determined by, first, checking the net.slp.locale System + property. If that is unset, then the default SLP locale [7] is used, + namely "en". Note that the default SLP locale may not be the same as + the default Java locale. + + + + + + +Kempf & Guttman Informational [Page 82] + +RFC 2614 Service Location API June 1999 + + +5.7.6. 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. Program execution continues without + interruption by substituting the default for the erroneous parameter. + Errors are checked when the property is used and are logged. + + The SLP configuration file cannot be read with the + java.util.Properties file reader because there are some syntactic + differences. The SLP configuration file syntax defines a different + escape convention for non-ASCII characters than the Java syntax. + However, after the file has been read, the properties are stored and + retrieved from java.util.Properties objects. + + Properties are global for a process, affecting all threads and all + Locator and Advertiser objects obtained through the + ServiceLocationManager. With the exception of the net.slp.locale, + net.slp.typeHint, and net.slp.maxResults properties, clients 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.7. Multithreading + + Thread-safe operation is 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. Alternatively, finer grained + synchronization is also possible within the classes implementing + Advertiser and Locator. + +5.7.8. 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 + + + +Kempf & Guttman Informational [Page 83] + +RFC 2614 Service Location API June 1999 + + + 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 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 concrete subclass can simply be omitted from an + implementation that only supports UA and/or SA clients, and the + TemplateRegistry.getRegistry() method can return null. In this way, + the API implementation can be tailored for the particular memory + requirements at hand. + + In addition, if an implementation only supports the minimal subset of + SLP [7], the unsupported Locator and Advertiser interface operations + can throw an exception with ServiceLocationException.NOT_IMPLEMENTED + as the error code. This supports better source portability between + low and high memory platforms. + +5.7.9. Asynchronous and Incremental Return Semantics + + The Java API contains no specific support for asynchronous operation. + Incremental return is not needed for the Advertiser because service + registrations can be broken up into pieces when large. Asynchronous + return is also not needed because clients can always issue the + Advertiser operation in a separate thread if the calling thread can't + block. + + The Locator can be implemented either synchronously or + asynchronously. Since the return type for Locator calls is + ServiceLocationEnumeration, a Java API implementation that supports + asynchronous semantics can implement ServiceLocationEnumeration to + dole results out as they come in, blocking when no results are + available. If the client code needs to support other processing + while the results are trickling in, the call into the enumeration to + retrieve the results can be done in a separate thread. + + Unlike the C case, collation semantics for return of attributes when + an attribute request by service type is made require that the API + collate returned values so that only one attribute having a collation + of all returned values appear to the API client. In practice, this + may limit the amount of asynchronous processing possible with the + findAttributes() method. This requirement is imposed because memory + management is much easier in Java and so implementing collation as + part of the API should not be as difficult as in C, and it saves the + client from having to do the collation. + + + + + + + +Kempf & Guttman Informational [Page 84] + +RFC 2614 Service Location API June 1999 + + +5.8. Example + + In this example, a printer server advertises its availability to + clients. Additionally, the server advertises a service template for + use by client software in validating service requests: + + + //Get the Advertiser and TemplateRegistry. + + Advertiser adv = null; + TemplateRegistry tr = null + + try { + + adv = ServiceLocationManager.getAdvertiser("en"); + + tr = 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 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_MAXIMUM); + + try { + + //Register the printer. + + adv.register(printerURL, attributes); + + + +Kempf & Guttman Informational [Page 85] + +RFC 2614 Service Location API June 1999 + + + //If the template registry is available, + // register the printer's template. + + if( tr != null ) { + tr.registerServiceTemplate( + new ServiceType("service:printer:lpr"), + "http://shop.arv/printer/printer-lpr.slp", + new Locale("en",""), + "1.0"); + + } + + } catch( ServiceLocationException ex ) { } //Deal with error. + + + Suppose a client is looking for color printer. The following code is + 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(); + + Enumeration services; + + try { + + + +Kempf & Guttman Informational [Page 86] + +RFC 2614 Service Location API June 1999 + + + services = + loc.findServices(new ServiceType("service:printer"),scopes,query); + + } catch { } //Deal with error. + + if (services.hasMoreElements() ) { + + //Printers can now be used. + ServiceURL surl = (ServiceURL) services.next(); + + Socket sock = new Socket(surl.getHost, surl.getPort()); + + // Use the Socket... + + } + + +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 UTF-8 character set [3]. + + The attribute information associated with the service URL must be + expressed in UTF-8. See [8] for attribute internationalization + guidelines. + +6.2. Character Set Encoding + + Configuration and serialized registration files are encoded in the + UTF-8 character set [3]. This is fully compatible with US-ASCII + character values. C platforms that do not support UTF-8 are required + to check the top bit of input bytes to determine whether the incoming + character is multibyte. If it is, the character should be dealt with + accordingly. This should require no additional implementation + effort, since the SLP wire protocol requires that strings are encoded + as UTF-8. C platforms without UTF-8 support need to supply their own + support, if only in the form of multibyte string handling. + + At the API level, the character encoding is specified to be Unicode + for Java and UTF-8 for C. Unicode is the default in Java. For C, the + standard US-ASCII 8 bits per character, null terminated C strings are + a subset of the UTF-8 character set, and so work in the API. Because + the C API is very simple, the API library needs to do a minimum of + processing on UTF-8 strings. The strings primarily just need to be + reflected into the outgoing SLP messages, and reflected out of the + + + +Kempf & Guttman Informational [Page 87] + +RFC 2614 Service Location API June 1999 + + + API from incoming SLP messages. + +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 preferred + over those which don't. Dialects that do not match will not prevent + string matching or comparisons from occurring. + +7. Security Considerations + + Security is handled within the API library and is not exposed to API + clients except in the form of exceptions. The + net.slp.securityEnabled, property determines whether an SA client's + messages are signed, but a UA client should be prepared for an + authentication exception at any time, because it may contact a DA + with authenticated advertisements. + + 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 DAAdverts, SAAdverts, Service URLs and + Service Attributes to be verified using digital cryptography. For + this reason, all SLP agents should be configured to use SLP SPIs. + See [7] for a description of how this mechanism works. + +8. Acknowledgements + + The authors would like to thank Don Provan for his pioneering work + during the initial stages of API definition. + + + + + + + + + + + + + + +Kempf & Guttman Informational [Page 88] + +RFC 2614 Service Location API June 1999 + + +9. References + + [1] Bradner, S., "Key Words for Use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [2] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform + Resource Identifiers (URI): Generic Syntax", RFC 2396, + August 1998. + + [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646", + RFC 2279, January 1998. + + [4] Howes, T., "The String Representation of LDAP Search Filters", + RFC 2254 December 1997. + + [5] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [6] Alvestrand, H., "Tags for the Identification of Languages", + RFC 1766, March 1995. + + [7] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service + Location Protocol, Version 2", RFC 2608, June 1999. + + [8] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and + Service: Schemes", RFC 2609, June 1999. + + + + + + + + + + + + + + + + + + + + + + + + + +Kempf & Guttman Informational [Page 89] + +RFC 2614 Service Location API June 1999 + + +10. Authors' Addresses + + Questions about this memo can be directed to: + + James Kempf + Sun Microsystems + 901 San Antonio Rd. + Palo Alto, CA, 94303 + USA + + Phone: +1 650 786 5890 + Fax: +1 650 786 6445 + EMail: james.kempf@sun.com + + + Erik Guttman + Sun Microsystems + Bahnstr. 2 + 74915 Waibstadt + Germany + + Phone: +49 7263 911 701 + EMail: erik.guttman@sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Kempf & Guttman Informational [Page 90] + +RFC 2614 Service Location API June 1999 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Kempf & Guttman Informational [Page 91] + |