idnits 2.17.1 draft-ietf-svrloc-api-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 6 instances of too long lines in the document, the longest one being 14 characters in excess of 72. == There are 35 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 230: '... framework. SAs MUST respond to UA se...' RFC 2119 keyword, line 297: '... "IANA", which MUST NOT be explicite...' RFC 2119 keyword, line 411: '... error SHOULD be returned. If...' RFC 2119 keyword, line 412: '..._SUPPORTED error MUST be returned, sin...' RFC 2119 keyword, line 540: '...imeouts property MUST be used for acti...' (41 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1101 has weird spacing: '... int s_iP...' == Line 1430 has weird spacing: '...PHandle hSLP...' == Line 1436 has weird spacing: '...Boolean fresh...' == Line 1518 has weird spacing: '...PHandle hSLP,...' == Line 1566 has weird spacing: '...PHandle hSLP...' == (4 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: '1' is defined on line 3666, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 3674, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 3677, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 3683, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' == Outdated reference: A later version (-09) exists of draft-fielding-url-syntax-05 -- Possible downref: Normative reference to a draft: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 1825 (ref. '5') (Obsoleted by RFC 2401) -- Possible downref: Non-RFC (?) normative reference: ref. '6' ** Obsolete normative reference: RFC 2279 (ref. '7') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2254 (ref. '8') (Obsoleted by RFC 4510, RFC 4515) ** Obsolete normative reference: RFC 2234 (ref. '9') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 1766 (ref. '10') (Obsoleted by RFC 3066, RFC 3282) == Outdated reference: A later version (-15) exists of draft-ietf-svrloc-protocol-v2-04 == Outdated reference: A later version (-14) exists of draft-ietf-svrloc-service-scheme-09 Summary: 15 errors (**), 0 flaws (~~), 15 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Service Location Working Group James Kempf 2 INTERNET DRAFT Erik Guttman 3 30 May 1998 Sun Microsystems 5 An API for Service Location 6 draft-ietf-svrloc-api-05.txt 8 Status of This Memo 10 This document is a submission by the Service Location Working Group 11 of the Internet Engineering Task Force (IETF). Comments should be 12 submitted to the srvloc@srvloc.org mailing list. 14 Distribution of this memo is unlimited. 16 This document is an Internet-Draft. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, 18 and its working groups. Note that other groups may also distribute 19 working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at 23 any time. It is inappropriate to use Internet- Drafts as reference 24 material or to cite them other than as ``work in progress.'' 26 To view the entire list of current Internet-Drafts, please check 27 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 28 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern 29 Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific 30 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 32 Distribution of this memo is unlimited. 34 Abstract 36 The Service Location Protocol (SLP) provides a new way for clients to 37 dynamically discovery network services. With SLP, it is simple to 38 offer highly available services that require no user configuration or 39 assistance from network administrators prior to use. This document 40 describes standardized API's for SLP in C and Java. The API's are 41 modular and are designed to allow implementions to offer just the 42 feature set needed. In addition, standardized file formats for 43 configuration and serialized registrations are defined, allowing SLP 44 agents to set network and other parameters in a portable way. The 45 serialized file format allows legacy services to be registered with 46 SLP directory agents in cases where modifying the legacy service 47 program code is difficult or impossible, and to portably exchange a 48 registration database. 50 Contents 52 Status of This Memo i 54 Abstract i 56 1. Introduction 1 57 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 1 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. File Formats 4 61 2.1. Configuration File Format . . . . . . . . . . . . . . . . 5 62 2.1.1. DA configuration . . . . . . . . . . . . . . . . 6 63 2.1.2. Static Scope Configuration . . . . . . . . . . . 6 64 2.1.3. Tracing and Logging . . . . . . . . . . . . . . . 7 65 2.1.4. Serialized Proxy Registrations . . . . . . . . . 8 66 2.1.5. Networking Configuration Parameters . . . . . . . 8 67 2.1.6. UA Configuration . . . . . . . . . . . . . . . . 10 68 2.1.7. Security . . . . . . . . . . . . . . . . . . . . 10 69 2.2. Serialized Registration File . . . . . . . . . . . . . . 11 70 2.3. Proccessing Serialized Registration and Configuration 71 Files . . . . . . . . . . . . . . . . . . . . . . . . 12 73 3. Binding Independent Implementation Considerations 13 74 3.1. Multithreading . . . . . . . . . . . . . . . . . . . . . 13 75 3.2. Asynchronous and Incremental . . . . . . . . . . . . . . 13 76 3.3. Type Checking for Service Types . . . . . . . . . . . . . 13 77 3.4. Refreshing Registrations . . . . . . . . . . . . . . . . 13 78 3.5. Configuration File Processing . . . . . . . . . . . . . . 14 79 3.6. Attribute Types . . . . . . . . . . . . . . . . . . . . . 14 80 3.7. Removal of Duplicates . . . . . . . . . . . . . . . . . . 14 81 3.8. Character Set Encoding . . . . . . . . . . . . . . . . . 14 82 3.9. Error Semantics . . . . . . . . . . . . . . . . . . . . . 15 83 3.10. Modular Implementations . . . . . . . . . . . . . . . . . 18 84 3.11. Scope Discovery and Handling . . . . . . . . . . . . . . 18 86 4. C Language Binding 19 87 4.1. Constant Types . . . . . . . . . . . . . . . . . . . . . 19 88 4.1.1. URL Lifetimes . . . . . . . . . . . . . . . . . . 19 89 4.1.2. Error Codes . . . . . . . . . . . . . . . . . . . 20 90 4.1.3. SLPBoolean . . . . . . . . . . . . . . . . . . . 21 91 4.2. Struct Types . . . . . . . . . . . . . . . . . . . . . . 21 92 4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . . . 21 93 4.2.2. SLPHandle . . . . . . . . . . . . . . . . . . . . 22 94 4.3. Callbacks . . . . . . . . . . . . . . . . . . . . . . . . 22 95 4.3.1. SLPRegReport . . . . . . . . . . . . . . . . . . 23 96 4.3.2. SLPSrvTypeCallback . . . . . . . . . . . . . . . 24 97 4.3.3. SLPSrvURLCallback . . . . . . . . . . . . . . . . 25 98 4.3.4. SLPAttrCallback . . . . . . . . . . . . . . . . . 26 99 4.4. Opening and Closing the SLP Library . . . . . . . . . . . 27 100 4.4.1. SLPOpen . . . . . . . . . . . . . . . . . . . . . 27 101 4.4.2. SLPClose . . . . . . . . . . . . . . . . . . . . 28 102 4.5. Protocol API . . . . . . . . . . . . . . . . . . . . . . 29 103 4.5.1. SLPReg . . . . . . . . . . . . . . . . . . . . . 29 104 4.5.2. SLPDereg . . . . . . . . . . . . . . . . . . . . 31 105 4.5.3. SLPDelAttrs . . . . . . . . . . . . . . . . . . . 32 106 4.5.4. SLPFindSrvTypes . . . . . . . . . . . . . . . . . 33 107 4.5.5. SLPFindSrvs . . . . . . . . . . . . . . . . . . . 34 108 4.5.6. SLPFindAttrs . . . . . . . . . . . . . . . . . . 36 109 4.6. Miscellaneous Functions . . . . . . . . . . . . . . . . . 37 110 4.7. SLPFindScopes . . . . . . . . . . . . . . . . . . . . . . 37 111 4.8. SLPParseSrvURL . . . . . . . . . . . . . . . . . . . . . 38 112 4.9. SLPFree . . . . . . . . . . . . . . . . . . . . . . . . . 39 113 4.10. SLPEscape . . . . . . . . . . . . . . . . . . . . . . . . 40 114 4.11. SLPUnescape . . . . . . . . . . . . . . . . . . . . . . . 41 115 4.12. SLPGetProperty . . . . . . . . . . . . . . . . . . . . . 42 116 4.13. SLPSetProperty . . . . . . . . . . . . . . . . . . . . . 42 117 4.14. Implementation Notes . . . . . . . . . . . . . . . . . . 43 118 4.14.1. Refreshing Registrations . . . . . . . . . . . . 43 119 4.14.2. Syntax for String Parameters . . . . . . . . . . 43 120 4.14.3. Client Side Syntax Checking . . . . . . . . . . . 44 121 4.14.4. System Properties . . . . . . . . . . . . . . . . 44 122 4.14.5. Memory Management . . . . . . . . . . . . . . . . 44 123 4.14.6. Asychronous and Incremental Return Semantics . . 45 124 4.15. Examples . . . . . . . . . . . . . . . . . . . . . . . . 45 125 4.15.1. Discovering one's mailbox . . . . . . . . . . . . 45 127 5. Java Language Binding 49 128 5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 49 129 5.2. Exceptions and Errors . . . . . . . . . . . . . . . . . . 49 130 5.2.1. Class ServiceLocationException . . . . . . . . . 50 131 5.3. Basic Data Structures . . . . . . . . . . . . . . . . . . 51 132 5.3.1. Interface ServiceLocationEnumeration . . . . . . 51 133 5.3.2. Class ServiceLocationAttribute . . . . . . . . . 51 134 5.3.3. Class ServiceType . . . . . . . . . . . . . . . . 54 135 5.3.4. Class ServiceURL . . . . . . . . . . . . . . . . 56 136 5.4. SLP Access Interfaces . . . . . . . . . . . . . . . . . . 59 137 5.4.1. Interface Advertiser . . . . . . . . . . . . . . 59 138 5.4.2. Interface Locator . . . . . . . . . . . . . . . . 62 139 5.5. The Service Location Manager . . . . . . . . . . . . . . 65 140 5.5.1. Class ServiceLocationManager . . . . . . . . . . 65 141 5.6. Service Template Introspection . . . . . . . . . . . . . 67 142 5.6.1. Abstract Class TemplateRegistry . . . . . . . . . 67 143 5.6.2. Interface ServiceLocationAttributeVerifier . . . 69 144 5.6.3. Interface ServiceLocationAttributeDescriptor . . 72 146 5.7. Implementation Notes . . . . . . . . . . . . . . . . . . 75 147 5.7.1. Refreshing Registrations . . . . . . . . . . . . 75 148 5.7.2. Parsing Alternate Transports in ServiceURL . . . 75 149 5.7.3. Client Side Syntax Checking . . . . . . . . . . . 75 150 5.7.4. Language Locale Handling . . . . . . . . . . . . 75 151 5.7.5. Setting SLP System Properties . . . . . . . . . . 76 152 5.7.6. Multithreading . . . . . . . . . . . . . . . . . 76 153 5.7.7. Modular Implementations . . . . . . . . . . . . . 76 154 5.7.8. Asynchronous and Incremental Return Semantics . . 77 155 5.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 77 157 6. Internationalization Considerations 80 158 6.1. service URL . . . . . . . . . . . . . . . . . . . . . . . 80 159 6.2. Character Set Encoding . . . . . . . . . . . . . . . . . 80 160 6.3. Language Tagging . . . . . . . . . . . . . . . . . . . . 80 162 7. Security Considerations 81 164 8. Acknowledgements 81 166 1. Introduction 168 The Service Location API is designed for standardized access the 169 Service Location Protocol (SLP). The APIs allow client and service 170 programs to be be written or modified in a very simple manner to 171 provide dynamic service discovery and selection. Bindings in the 172 C and Java languages are defined in this document. In addition, 173 standardized formats for configuration files and for serialized 174 registration files are presented. These files allow SLP agents 175 to configure network parameters, to register legacy services that 176 have not been SLP enabled, and to portably exchange registration 177 databases. 179 1.1. Goals 181 The overall goal of the API is to enable source portability of 182 applications that use the API between different implementations of 183 SLP. The result should facilitate the adoption of SLP, and conversion 184 of clients and service programs to SLP. 186 The goals of the C binding are to create a minimal but complete 187 access to the functionality of the SLP protocol, allowing for simple 188 memory management and limited code size. 190 The Java API provides for modular implementations (where unneeded 191 features can be omitted) and an object oriented interface to the 192 complete set of SLP data and functionality. 194 The standardized configuration file and serialized file formats 195 provide a simple syntax with complete functional coverage of the 196 protocol, but without including secure information such as private 197 keys. 199 1.2. Terminology 201 Service Location Protocol (SLP) 203 The underlying protocol allowing dynamic and scalable service 204 discovery. This protocol is specified in the Service Location 205 Protocol Version 2 [11]. 207 SLP framework 209 When a 'Service Location framework' is mentioned, it refers to 210 both the SLP implementation and interface implementation; ie. 211 whatever provides the SLP functionality to user level programs. 212 This includes remote agents. 214 Directory Agent (DA) 216 A service that automatically gathers service advertisements 217 from SAs in order to provide them to UAs. 219 User Agent (UA) 221 This is the Service Location process or library that allows 222 SLP requests to be made on behalf of a client process. UAs 223 automatically direct requests to DAs when they exist. In their 224 absence, UAs make requests to SAs. 226 Service Agent (SA) 228 This is the Service Location process or library that allows 229 service software to register and deregister itself with the SLP 230 framework. SAs MUST respond to UA service requests, detect DAs 231 and register service advertisements with them. 233 SA Server 235 Many operating system platforms only allow a single process to 236 listen on a particular port number. Since SAs are required 237 to listen on a multicast address for SLP service requests, 238 implementaions of the SLP framework on such platforms that want 239 to support multiple SAs on one machine need to arrange for a 240 single process to do the listening while the advertising SAs 241 communicate with that process through another mechanism. The 242 single listening process is called an SA server. SA servers 243 share many characteristics with DAs, but they are not the same. 245 Service Advertisement 247 A URL possibly combined with service attributes. These are 248 made available to UAs by SAs, either directly or via a DA. 250 Locale 252 The language localization that applies to strings passed into 253 or returned from the SLP API. The Locale is expressed using a 254 Language Tag [10]. All attribute strings are associated with a 255 particular locale. The locale is completely orthogonal to the 256 ANSI C locale. The SLP locale is mapped into the Java locale 257 in the Java API. 259 Service Template 261 A document that describes the syntax of the URL for a given 262 service type and a definition of all service attributes 263 including the meaning, defaults, and constraints on values the 264 attributes may take. See [12] for more information on service 265 templates. 267 The service: URL 269 A service of a particular type announces its availability 270 with a service: URL that includes its service access point 271 (domain name or ip address, and possibly its port number) and 272 optionally basic configuration parameters. The syntax of the 273 service: URL is defined in the service template. Other URL's 274 can be used in service advertisements if desired. 276 Service Attributes 278 The attributes associated with a given service. The values 279 that can be assigned to service attributes are defined by the 280 service template. 282 Scope 284 A string used to control the availability of service 285 advertisements. Every SLP Agent is configured with one or more 286 scope strings. Scopes are assigned by site administrators to 287 group services for many purposes, but chiefly as a means of 288 scalability. DAs store only services advertised having a scope 289 string matching the scopes with which they are configured. 291 Naming Authority (NA) 293 This is a 'suffix' to the service type string. It completely 294 changes the meaning of the service type. NAs are used 295 for private definitions of well known Service Types and 296 experimental Service Type extensions. The default NA is 297 "IANA", which MUST NOT be explicitely included. Service types 298 with the IANA naming authority are registered with the Internet 299 Assigned Numbers Authority (see [12] for more information on 300 the registration procedure). 302 2. File Formats 304 This section describes the configuration and serialized registration 305 file formats. Both files are defined in the UTF8 character set [7]. 307 String values in the configuration file require SLP reserved 308 characters to be escaped. The SLP reserved characters are `(', `)', 309 `,', `\', `!', `<', `=', `>', `~' and control characters such as 310 newline. The escapes are formed exactly as for the wire protocol, 311 i.e. a backslash followed by two hex digits representing the 312 character. For example, the escape for ',' is '\2c'. 314 Escaped strings beginning with `\ff`, an encoding for a nonUTF8 315 character, are treated as opaques. Exactly as in the wire protocol, 316 syntactically correct opaque encodings consist of a string beginning 317 with `\ff` and containing *only* escaped characters that are 318 transformed to bytes. Such strings are only syntactically correct 319 in the serialized registration file as attribute values. In other 320 cases, whenever an escape is encountered and the character is not an 321 SLP reserved character, an error is signalled. 323 On platforms that only support the ASCII subset of UTF8, the upper 324 bit of bytes incoming from the configuration and registration files 325 determines whether the character is ASCII or nonASCII. According to 326 the standard UTF8 encoding, the upper bit is zero if the character 327 is ASCII and one if the character is multibyte and thus nonASCII. 328 Platforms without intrinsic UTF8 support are required to parse the 329 multibyte character and store it in an appropriate internal format. 330 Support for UTF8 is required to implement the SLP protocol (see [11]) 331 and can be reused during configuration file parsing. 333 The location and name of the configuration file is system-dependent, 334 but implementations of the API are encouraged to locate it together 335 with other configuration files and name it consistently. 337 2.1. Configuration File Format 339 The configuration file format consists of a newline delimited list 340 of zero or more property definitions. Each property definition 341 corresponds to a particular configurable SLP, network, or other 342 parameter in one or more of the three SLP agents. The file format 343 grammer in ABNF [9] syntax is: 345 config-file = line-list 346 line-list = line / line line-list 347 line = property-line / comment-line 348 comment-line = ( "#" / ";" ) 1*allchar newline 349 property-line = property newline 350 property = tag "=" value-list 351 tag = prop / prop "." property 352 prop = 1*char 353 value-list = value / value "," value-list 354 value = int / bool / value-list / string 355 int = 1*DIGIT 356 bool = "true" / "false" / "TRUE" / "FALSE" 357 newline = CR / ( CRLF ) 358 string = 1*allchar 359 char = DIGIT / ALPHA / other 360 other = %x21-%x2f / %x3a-%x40 / 361 %x5b-%x60 / %7b-%7e 362 allchar = char / HT / SP / escape 363 escape = "\" HEXDIG HEXDIG 364 ; Used for SLP reserved characters 366 With the exception of the net.slp.useScopes and the 367 net.slp.DAAddresses properties, all other properties can be 368 changed through property accessors in the C and Java APIs. The 369 property accessors only change the property values in the running 370 agent program and do not affect the values in the configuration 371 file. The net.slp.useScopes and net.slp.DAAddresses properties are 372 read-only because they control the agent's view of the scopes and DAs 373 and are therefore critical to the function of the API scope discovery 374 algorithm. Attempts to modify them are unlikely to yield productive 375 results, and could harm the ability of the agent to find scopes and 376 use DAs. 378 The properties break down into seven general areas. Each of the 379 following subsections describes an area and its properties. 381 2.1.1. DA configuration 383 Important configuration parameters for DAs are included in this 384 section. These are: 386 net.slp.isDA 388 A boolean indicating if the SLP server is to act as a DA. If 389 false, not run as a DA. Default is false. 391 net.slp.DAHeartBeat 393 A 32 bit integer giving the number of seconds for the 394 DA heartbeat. Default is 3 hours (10800 seconds). This 395 property corresponds to the protocol specification parameter 396 CONFIG_DA_BEAT [11]. Ignored if isDA is false. 398 2.1.2. Static Scope Configuration 400 These parameters allow various aspects of scope handling to be 401 configured. 403 net.slp.useScopes 405 A value-list of strings indicating the only scopes a UA or 406 SA is allowed to use when making requests or registring, 407 or the scopes a DA must support. If not present, then in 408 the absence of scope information from other sources (DHCP, 409 active and passive discovery), the default is "DEFAULT". 410 If another scope is used by a UA, a SCOPE_NOT_SUPPORTED 411 error SHOULD be returned. If another scope is used by a 412 SA, a SCOPE_NOT_SUPPORTED error MUST be returned, since 413 SAs are required to register in all scopes with which they 414 are configured. Unlike other parameters, this parameter is 415 ``read-only'', so attempts to change it after the configuration 416 file has been read are ignored. See Section 3.11 for the 417 algorithm the API uses in determining what scope information to 418 present. 420 net.slp.DAAddresses 422 A value-list of IP addresses or DNS-resolvable names giving 423 the DAs to use for statically configured UAs and SAs, along 424 with their scopes. If isDA is true, registrations and 425 deregistrations in the appropriate scopes are forwarded these 426 DAs. Default is none. Scopes from the net.slp.useScopes 427 parameter and addresses and scopes obtained via DHCP take 428 precedence over these. Unlike other parameters, this 429 parameter is ``read-only'', so attempts to change it after the 430 configuration file has been read are ignored. If scope and DA 431 information is available from other sources, the information 432 from this list is used as a supplement. 434 The following grammer describes the property: 436 addr-list = addr / addr "," addr-list 437 addr = addrrep "(" scope-list ")" 438 addrrep = ipv4-addr / ipv6-addr / fqdn 439 ipv4-addr = 1*3DIGIT 3( "." 1*3DIGIT ) 440 ipv6-addr = 64HEXDIGIT 441 fqdn = ALPHA / ALPHA *[ anum / "-" ] anum 442 anum = ALPHA / DIGIT 443 scope-list = scope / scope "," scope-list 444 scope = string 445 ; See grammar of Section 2.1 446 ; and [11]. 448 Scoped DAs are listed with a comma delimited list inside 449 brackets following the DA address. For example: 451 (da1.fr.org(default),da2.fr.org(scope1,scope2),da3.fr.org(default,scope3)) 453 Here da1 has scope default, da2 has scope1 and scope2, da3 has 454 default and scope3. 456 2.1.3. Tracing and Logging 458 This section allows tracing and logging information to be printed by 459 the various agents. 461 net.slp.traceDATraffic 463 A boolean controlling printing of messges about traffic with 464 DAs. Default is false. 466 net.slp.traceMsg 468 A boolean controlling printing of details on SLP messages. 469 The fields in all incoming messages and outgoing replies are 470 printed. Default is false. 472 net.slp.traceDrop 474 A boolean controlling printing details when a SLP message is 475 dropped for any reason. Default is false. 477 net.slp.traceReg 479 A boolean controlling dumps of all registered services upon 480 registration and deregistration. If true, the contents 481 of the DA or SA server are dumped after a registration or 482 deregistration occurs. Default is false. 484 2.1.4. Serialized Proxy Registrations 486 These properties control the reading and writing of serialized 487 registrations. 489 net.slp.serializedRegURL 491 A string containing a URL pointing to a document containing 492 serialized registrations that should be processed when the DA 493 or SA server starts up. Default is none. 495 2.1.5. Networking Configuration Parameters 497 The properties in this section allow various network configuration 498 parameters to be set. 500 net.slp.isBroadcastOnly 502 A boolean indicating if broadcast should be used instead of 503 multicast. Default is false. 505 net.slp.passiveDADetection 507 A boolean indicating whether passive DA detection should be 508 used. Default is true. 510 net.slp.multicastTTL 512 A positive integer less than or equal to 32, giving the 513 multicast TTL. Default is 32. 515 net.slp.DAActiveDiscoveryInterval 517 A 32 bit integer giving the number of seconds between DA active 518 discovery queries. Default is 900 seconds (15 minutes). This 519 property corresponds to the protocol specification parameter 520 CONFIG_DA_FIND [11]. 522 net.slp.multicastMaximumWait 524 A 32 bit integer giving the maximum amount of time to perform 525 multicast, in milliseconds. Default is 15000 ms (15 sec.). 526 This property corresponds to the CONFIG_MC_MAX parameter in the 527 protocol specification [11]. 529 net.slp.multicastTimeouts 531 A value-list of 32 bit integers used as timeouts, in 532 milliseconds, to implement the multicast convergence algorithm. 533 Each value specifies the time to wait before sending the 534 next request, or until nothing new has been learned from 535 two successive requests. Ignored if isDA is true. Default 536 is: 3000,3000,3000,3000,3000. In a fast network the 537 agressive values of 1000,1250,1500,2000,4000 allow better 538 performance. This property corresponds to the CONFIG_MC_RETRY 539 parameter in the protocol specification [11]. Note that the 540 net.slp.DADiscoveryTimeouts property MUST be used for active DA 541 discovery. 543 net.slp.DADiscoveryTimeouts 545 A value-list of 32 bit integers used as timeouts, in 546 milliseconds, to implement the multicast convergence 547 algorithm during active DA discovery. Each value specifies 548 the time to wait before sending the next request, or 549 until nothing new has been learned from two successive 550 requests. This property corresponds to the protocol 551 specification parameter CONFIG_DA_RETRY [11]. Default is: 552 2000,2000,2000,2000,3000,4000. 554 net.slp.datagramTimeouts 556 A value-list of 32 bit integers used as timeouts, in 557 milliseconds, to implement unicast datagram transmission to 558 DAs. The nth value gives the time to block waiting for a reply 559 on the nth try to contact the DA. The sum of these values is 560 the protocol specification property CONFIG_DA_MAX [11]. 562 net.slp.randomWaitBound 564 A 32 bit integer giving the maximum value for all random 565 wait parameters, in milliseconds. Default is 1000 (1 566 sec.). This value corresponds to the protocol specification 567 parameters CONFIG_START_WAIT, CONFIG_REG_PASSIVE, and 568 CONFIG_REG_ACTIVE [11]. 570 net.slp.MTU 572 A 16 bit integer giving the network packet MTU, in bytes. 573 This is the maximum size of any datagram to send, but the 574 implementation might receive a larger datagram. Default is 575 1400. 577 net.slp.multicastInterfaces 579 Value-list of strings giving the names of network interfaces 580 on which a DA or SA should listen for multicast. Default is 581 empty, i.e. just listen on the default network interface. 583 2.1.6. UA Configuration 585 This section contains configuration parameters for the UA. 587 net.slp.locale 589 A RFC 1766 Language Tag [10] for the language locale. Setting 590 this property causes the property value to become the default 591 locale for SLP messages. Default is "en". 593 net.slp.maxResults 595 A 32 bit integer giving the maximum number of results to 596 accumulate and return for a synchronous request before the 597 timeout, or the maximum number of results to return through a 598 callback if the request results are reported asychronously. 599 Positive integers and -1 are legal values. If -1, indicates 600 that all results should be returned. Default value is -1. 602 DAs and SAs always return all results that match the 603 request. This configuration value applies only to UAs, that 604 filter incoming results and only return as many values as 605 net.slp.maxResults indicates. 607 2.1.7. Security 609 The properties in this section allow security parameters to be 610 configured. Key management is implementation dependent. 612 net.slp.URLSignature 614 A boolean indicating whether the SA should sign URLs. URLs are 615 signed if true. Default is false. Applies to SAAdverts as 616 well. 618 net.slp.attributeSignature 620 A boolean indicating whether the SA should sign attributes. 621 Attributes are signed if true. Default is false. 623 net.slp.DAAdvertSignature 625 A boolean indicating whether the DA should sign DAAdverts. 626 DAAdverts are signed if true. Default is false. 628 2.2. Serialized Registration File 630 The serialized registration file contains a group of registrations 631 that a DA or SA server (if one exists) registers when it starts up. 632 These registrations are primarily for older service programs that do 633 not internally support SLP and cannot be converted, and for portably 634 exchanging registrations between SLP implementations. The character 635 format of the registrations is required to be UTF8. 637 The syntax of the serialized registration file, in ABNF format [9], 638 is as follows: 640 ser-file = reg-list 641 reg-list = reg / reg reg-list 642 reg = creg / ser-reg 643 creg = comment-line ser-reg 644 comment-line = ( "#" / ";" ) 1*allchar newline 645 ser-reg = url-props [slist] attr-list newline 646 url-props = surl sep lang sep ltime sep [ type ] 647 sep = *WSP "," *WSP 648 surl = ;The registration's URL. See 649 ; [12] for syntax. 650 lang = 2*3ALPHA [ "-" 1*ALPHA ] 651 ;RFC 1766 Language Tag see [10]. 652 ltime = 1*DIGIT 653 ; A positive 16-bit integer 654 ; giving the lifetime 655 ; of the registration. 656 type = string 657 ; The service type name, see [11] 658 ; and [12] for syntax. 660 slist = attr 661 ; Attribute definition with id "scopes" 662 ; and value list containing scope names. 663 ; See grammar of Section 2.1 664 ; and [11]. 665 attr-list = attr-def / attr-def attr-list 666 attr-def = attr / keyword 667 keyword = attr-id 668 attr = attr-id assgn-op attr-val-list newline 669 assgn-op = *WSP "=" *WSP 670 attr-id = ;Attribute id, see [11] for syntax. 671 attr-val-list = attr-val / attr-val sep attr-val-list 672 attr-val = ;Attribute value, see [11] for syntax. 673 char = DIGIT / ALPHA / other 674 ;'other' defined in section 2.1. 675 allchar = char / WSP 677 The syntax for attributes and attribute values requires escapes for 678 special characters as specified in [11], in addition to nonASCII 679 characters. DAs and SA servers that process serialized registrations 680 MUST handle them exactly as if they were registered by an SA. In the 681 urlprops production, the type token is optional. If the type token 682 is present for a service: URL, a warning is signalled and type name 683 is ignored. Scopes can be included in a registration by including 684 an attribute definition with tag "scopes" followed by a comma 685 separated list of scope names immediately after the URL registration. 686 If the optional scope list is present, the registations are made 687 in the indicated scopes; otherwise, they are registered in the 688 scopes with which the DA or SA server was configured through the 689 net.slp.useScopes property. 691 If the scope list contains scopes that are not in the 692 net.slp.useScopes property (provided that property is set) or 693 are not specified by DHCP, the API library is required to abort the 694 program. 696 2.3. Proccessing Serialized Registration and Configuration Files 698 Implementations are encouraged to make processing of configuration 699 and serialized files as transparent as possible to clients of 700 the API. At the latest, errors MUST be caught when the relevent 701 configuration item is used. At the earliest, errors MAY be caught 702 when the relevent file is loaded into the executing agent. Errors 703 SHOULD be reported by logging to the appropriate platform logging 704 file, error output, or log device, and the default value substituted. 705 Serialized registration file entries SHOULD be caught and reported 706 when the file is loaded. 708 Configuration file loading MUST be complete prior to the initiation 709 of the first networking connection. Serialized registration MUST be 710 complete before the DA accepts the first network request. 712 3. Binding Independent Implementation Considerations 714 This section discusses a number of implementation considerations 715 independent of language binding, with language specific notes where 716 applicable. 718 3.1. Multithreading 720 Implementations of both the C and Java APIs are required to make API 721 calls thread-safe. Access to data structures shared between threads 722 must be co-ordinated to avoid corruption or invalid access. One way 723 to achieve this goal is to allow only one thread at a time in the 724 implementing library. Performance in such an implementation suffers, 725 however. Therefore, where possible, implementations are encouraged 726 to allow multiple threads within the SLP API library. 728 3.2. Asynchronous and Incremental 730 The APIs are designed to encourage implementations supporting 731 asychronous and incremental client interaction. The goal is to allow 732 large numbers of returned service URLs, service types, and attributes 733 without requiring the allocation of huge chunks of memory. The 734 particular design features to support this goal differ in the two 735 language bindings. 737 3.3. Type Checking for Service Types 739 Service templates [12] allow SLP registrations to be type checked 740 for correctness. Implementations of the API are free to make use of 741 service type information for type checking, but are not required to 742 do so. If a type error occurs, the registration should terminate 743 with TYPE_ERROR. 745 3.4. Refreshing Registrations 747 SLP advertisements carry an explicit lifetime with them. After the 748 lifetime expires, the DA flushes the registration from its cache. 749 Implementations of the SA API are encouraged to provide an automatic 750 refreshing capability, so that service advertiser applications can 751 simply register their services for as long as they continue running. 753 The SA API is required to deregister any such advertisements as soon 754 as the calling application exits. 756 3.5. Configuration File Processing 758 DAs, SAs and UAs processing the configuration file, and DAs and SA 759 servers processing the serialized registration file are required 760 to log any errors using whatever underlying error mechanism is 761 appropriate for the platform. Examples include include writing error 762 messages to the standard output, writing to a system logging device, 763 or displaying the errors to a logging window. After the error is 764 reported, the offending parameter must be set to the default and 765 program execution continued. An agent MUST NOT fail if a file format 766 error occurs. 768 3.6. Attribute Types 770 String encoded attribute values do not include explicit type 771 information. All UA implementations and those SA and DA 772 implementations that choose to support type checking should use the 773 type rules described in [12] in order to convert from the string 774 representation on the wire to an object typed appropriately. 776 3.7. Removal of Duplicates 778 The UA implementation SHOULD always collate results to remove 779 duplicates during synchronous operations and for the Java API. During 780 asychronous operation in C, the UA implementation SHOULD forgo 781 duplicate elimination to reduce memory requirements in the library. 782 This allows the API library to simply take the returned attribute 783 value list strings, URL strings, or service type list strings 784 and call the callback function with it, without any additional 785 processing. Naturally, the burden of duplicate elimination is thrown 786 onto the client in this case. 788 3.8. Character Set Encoding 790 Character string parameters in the Java API are all represented in 791 Unicode internally because that is the Java-supported character set. 792 Characters buffer parameters in the C API are represented in UTF8 to 793 maintain maximum compatibility on platforms that only support the 794 ASCII subset of UTF8. API functions are still required to handle the 795 full range of UTF8 characters because the SLP protocol requires it, 796 but the API implementation can represent the characters internally 797 in any convenient way. On the wire, all characters are converted to 798 UTF8. Inside URLs, characters that are not allowed by URL syntax [2] 799 must be escaped according to the URL escape character convention. 800 Strings that are included in SLP messages may include SLP reserved 801 characters and are escaped by convenience functions by the API. The 802 character code used to encode the escaped characters is UTF8. 804 The maximum length of any string parameter in C or Java is 64K bytes. 806 3.9. Error Semantics 808 All errors encountered processing SLP messages SHOULD be logged. 809 For synchronous calls, an error is only reported on a call if no 810 successful replies were received from any SLP framework entity. If 811 an error occured among one or several successful replies, then the 812 error should be logged and the successful replies returned. For 813 asychronous calls, an error occuring during correspondence with a 814 particular remote SLP agent is reported through the first callback 815 (in the C API) or enumeration method invocation (in the Java API) 816 after the error occurs, which would normally report the results of 817 the correspondence. This allows the callback or client code to 818 determine whether the operation should be terminated or continue. In 819 some cases, the error returned from the SLP framework may be fatal 820 (SLP_PARSE_ERROR, etc.). In these cases, the API library terminates 821 the operation. 823 Both the Java and C APIs contain language specific error code 824 mechanisms for returning error information. The names of the error 825 codes are consistent between the two implementations, however. 827 The following error codes are returned from a remote agent (DA or SA 828 server): 830 LANGUAGE_NOT_SUPPORTED 832 No DA or SA has service advertisement information in the 833 language requested, but at least one DA or SA indicated, via 834 the LANGUAGE_NOT_SUPPORTED error code, that it might have 835 information for that service in another language. 837 PARSE_ERROR 839 The SLP message was rejected by a remote SLP agent. The API 840 returns this error only when no information was retrieved, and 841 at least one SA or DA indicated a protocol error. The data 842 supplied through the API may be malformed or a may have been 843 damaged in transit. 845 INVALID_REGISTRATION 847 The API may return this error if an attempt to register a 848 service was rejected by all DAs because of a malformed URL or 849 attributes. SLP does not return the error if at least one DA 850 accepted the registration. 852 AUTHENTICATION_ABSENT 854 If the SLP framework supports authentication, this error arises 855 when the UA or SA failed to send an authenticator for requests 856 or registrations in a protected scope. 858 INVALID_UPDATE 860 An update for a nonexisting registration was issued. 862 The following errors result from interactions with remote agents or 863 can occur locally: 865 AUTHENTICATION_FAILED 867 If the SLP framework supports authentication, this error arises 868 when a authentication on an SLP message received from a remote 869 SLP agent failed. 871 SCOPE_NOT_SUPPORTED 873 The API returns this error if the UA or SA has been configured 874 with net.slp.useScopes value-list of scopes and the UA or SA 875 request did not specify one or more of these allowable scopes, 876 and no others. It may also be returned by a DA if the scope 877 included in a request is not supported by a DA. 879 The following errors are generated through a program interacting with 880 the API implementation. They do not involve a remote SLP agent. 882 NOT_IMPLEMENTED 884 If an unimplemented feature is used, this error is returned. 886 NETWORK_INIT_FAILED 888 If the network cannot initialize properly, this error is 889 returned. 891 NETWORK_TIMED_OUT 893 When no reply can be obtained in the time specified by the 894 configured timeout interval, this error is returned. 896 NETWORK_ERROR 898 The failure of networking during normal operations causes this 899 error to be returned. 901 BUFFER_OVERFLOW 903 An outgoing request overflowed the maximum network MTU size. 904 The request should be reduced in size or broken into pieces and 905 tried again. 907 MEMORY_ALLOC_FAILED 909 If the API fails to allocate memory, the operation is aborted 910 and returns this. 912 PARAMETER_BAD 914 If a parameter passed into an interface is bad, this error is 915 returned. 917 INTERNAL_SYSTEM_ERROR 919 A basic failure of the API causes this error to be returned. 920 This occurs when a system call or library fails. The operation 921 could not recover. 923 HANDLE_IN_USE 925 In the C API, callback functions are not permitted to 926 recursively call into the API on the same SLPHandle, either 927 directly or indirectly. If an attempt is made to do so, this 928 error is returned from the called API function. 930 TYPE_ERROR 932 If the API supports type checking of registrations against 933 service type templates, this error can arise if the attributes 934 in a registration do not match the service type template for 935 the service. 937 Some error codes are handled differently in the Java API. These 938 differences are discussed in Section 5. 940 The errors OPTION_NOT_UNDERSTOOD, VER_NOT_SUPPORTED, INTERNAL_ERROR, 941 RQST_NOT_SUPPORTED, AUTHENTICATON_ALGO_UNKNOWN, and DA_BUSY_NOW 942 should be handled internally and not surfaced to clients through the 943 API. 945 3.10. Modular Implementations 947 Subset implementations that do not support the full range of 948 functionality are required to nevertheless support every interface 949 in order to maintain link compatiblity between compliant API 950 implementations and applications. If a particular operation is not 951 supported, a NOT_IMPLEMENTED error should be returned. The Java API 952 has some additional conventions for handling subsets. Applications 953 that are expected to run on a wide variety of platforms should be 954 prepared for subset API implementations by checking returned error 955 codes. 957 3.11. Scope Discovery and Handling 959 Both APIs contain an operation to obtain a list of currently known 960 scope names. This scope information comes from a variety of places: 961 DHCP, the net.slp.useScopes and net.slp.DAAddresses properties, and 962 active and passive discovery. 964 API implementations are required to process presented scope 965 information in the following way. Scopes returned by DHCP have 966 first priority and MUST be returned if they are available. The 967 net.slp.useScopes property has second priority, and scopes discovered 968 through the net.slp.useScopes property MUST be returned if this 969 property is set and there are no scopes available from DHCP. If 970 neither of these sources provide information on scopes, then scopes 971 obtained from the net.slp.DAAddresses property, from active DA 972 discovery, and from passive DA discovery all MUST be returned. If 973 no information is available from any of these sources, then the 974 API library MAY perform SA discovery, using the service type hint 975 passed in through the API to limit the search to SAs supporting a 976 particular service type. In the absence of any of the above sources 977 of information, the API MUST return the default scope, ``DEFAULT''. 978 Note that the API MUST always return some scope information. 980 SLP requires that SAs MUST perform their operations in all scopes 981 currently known to them. [11]. The API enforces this constraint 982 by checking the list of scopes presented in the call to SA 983 operations, and signals a SCOPE_NOT_SUPPORTED error if any scopes 984 are missing. UAs SHOULD use a scope obtained through one of the API 985 operations for finding scopes. Any other scope name MAY result in a 986 SCOPE_NOT_SUPPORTED error from a remote agent. 988 Scopes are used in larger networks for administrators to control 989 service access. Care must be taken by programmers using the API not 990 to expose the ability to create or view arbitrary scopes in cases 991 where the host has been preconfigured with a scope list. 993 4. C Language Binding 995 The C language binding presents a minimal overhead implemention 996 that maps directly into the protocol. There is one C language 997 function per protocol request, with the exception of the SLPDereg() 998 and SLPDelAttrs() functions, which map into different uses of the 999 SLP deregister request. Parameters are for the most part character 1000 buffers. Memory management is kept simple by having the API library 1001 allocate memory and requiring that client callback functions copy 1002 incoming parameters into memory allocated by the client code. Memory 1003 returned directly from the API functions is deallocted using the 1004 SLPFree() function. 1006 To conform with standard C practice, all character strings passed to 1007 and returned through the API are null terminated, even though the 1008 SLP protocol does not use null terminated strings. Strings passed 1009 as parameters are UTF8 but they may still be passed as a C string 1010 (a null terminated sequence of bytes.) Escaped characters must be 1011 encoded as UTF8. In the common case of the ASCII subset of UTF8, the 1012 usual one byte per character C strings work. API functions assist in 1013 escaping and unescaping strings. 1015 4.1. Constant Types 1017 4.1.1. URL Lifetimes 1019 4.1.1.1. Synopsis 1021 typedef enum { 1022 SLP_LIFETIME_DEFAULT = 10800, 1023 SLP_LIFETIME_MAXIMUM = 65535 1024 } SLPURLLifetime; 1026 4.1.1.2. Description 1028 The SLPURLLifetime enum type contains URL lifetime values, in 1029 seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours, 1030 while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the 1031 maximum size of the lifetime field in SLP messages. 1033 4.1.2. Error Codes 1035 4.1.2.1. Synopsis 1037 typedef enum { 1038 SLP_LAST_CALL = 1, 1039 SLP_OK = 0, 1040 SLP_LANGUAGE_NOT_SUPPORTED = -1, 1041 SLP_PARSE_ERROR = -2, 1042 SLP_INVALID_REGISTRATION = -3, 1043 SLP_SCOPE_NOT_SUPPORTED = -4, 1044 SLP_AUTHENTICATION_ABSENT = -6, 1045 SLP_AUTHENTICATION_FAILED = -7, 1046 SLP_INVALID_UPDATE = -9; 1047 SLP_NOT_IMPLEMENTED = -17, 1048 SLP_BUFFER_OVERFLOW = -18, 1049 SLP_NETWORK_TIMED_OUT = -19, 1050 SLP_NETWORK_INIT_FAILED = -20, 1051 SLP_MEMORY_ALLOC_FAILED = -21, 1052 SLP_PARAMETER_BAD = -22, 1053 SLP_NETWORK_ERROR = -23, 1054 SLP_INTERNAL_SYSTEM_ERROR = -24, 1055 SLP_HANDLE_IN_USE = -25, 1056 SLP_TYPE_ERROR = -26 1058 } SLPError ; 1060 4.1.2.2. Description 1062 The SLPError enum contains error codes that are returned from API 1063 functions. 1065 The SLP_OK code indicates that the no error occured during the 1066 operation. The SLP_LAST_CALL code is passed to callback functions 1067 when the API library has no more data for them and threfore 1068 no further calls will be made to the callback on the currently 1069 outstanding operation. The callback can use this to signal the main 1070 body of the client code that no more data will be forthcoming on the 1071 operation, so that the main body of the client code can break out of 1072 data collection loops. On the last call of a callback during both 1073 a synchronous and asynchronous call, the error code parameter has 1074 value SLP_LAST_CALL, and the other parameters are all null. If no 1075 results are returned by an API operation, then only call with the 1076 error parameter set to SLP_LAST_CALL is made. 1078 4.1.3. SLPBoolean 1080 4.1.3.1. Synopsys 1082 typedef enum { 1083 SLP_FALSE = 0, 1084 SLP_TRUE = 1 1086 } SLPBoolean; 1088 4.1.3.2. Description 1090 The SLPBoolean enum is used as a boolean flag. 1092 4.2. Struct Types 1094 4.2.1. SLPSrvURL 1096 4.2.1.1. Synopsis 1098 typedef struct srvurl { 1099 char *s_pcSrvType; 1100 char *s_pcHost; 1101 int s_iPort; 1102 char *s_pcNetFamily; 1103 char *s_pcSrvPart; 1104 } SLPSrvURL; 1106 4.2.1.2. Description 1108 The SLPSrvURL structure is filled in by the SLPParseSrvURL() function 1109 with information parsed from a character buffer containing URL. 1110 The fields correspond to different parts of the URL. Note that 1111 the structure is conformant with the standard Berkeley sockets 1112 struct servent, with the exception that the pointer to an array of 1113 characters for aliases (s_aliases field) is replaced by the pointer 1114 to host name (s_pcHost field). 1116 s_pcSrvType 1118 A pointer to a character string containing the service type 1119 name, including naming authority. 1121 s_pcHost 1123 A pointer to a character string containing the host 1124 identification information. 1126 s_iPort 1128 The port number, or zero if none. The port is only available 1129 if the transport is IP. 1131 s_pcNetFamily 1133 A pointer to a character string containing the network address 1134 family identifier. Possible values are ``ipx'' for the IPX 1135 family, ``at'' for the Appletalk family, and ``'' (i.e. the 1136 empty string) for the IP address family. 1138 s_pcSrvPart 1140 The remainder of the URL, after the host identification. 1142 The host and port should be sufficient to open a socket to the 1143 machine hosting the service, and the remainder of the URL should 1144 allow further differentiation of the service. 1146 4.2.2. SLPHandle 1148 4.2.2.1. Synopsis 1150 typedef void* SLPHandle; 1152 The SLPHandle type is returned by SLPOpen() and is a parameter to all 1153 SLP functions. It serves as a handle for all resources allocated on 1154 behalf of the process by the SLP library. The type is opaque, since 1155 the exact nature differs depending on the implementation. 1157 4.3. Callbacks 1159 A function pointer to a callback function specific to a particular 1160 API operation is included in the parameter list when the API function 1161 function is invoked. The callback function is called with the 1162 results of the operation in both the synchronous and asychronous 1163 cases. The memory included in the callback parameters is owned by 1164 the API library, and the client code in the callback MUST copy out 1165 the contents if it wants to maintain the information longer than the 1166 duration of the current callback call. 1168 In addition to parameters for reporting the results of the operation, 1169 each callback parameter list contains an error code parameter and a 1170 cookie parameter. The error code parameter reports the error status 1171 of the ongoing (for asychronous) or completed (for synchronous) 1172 operation. The cookie parameter allows the client code that starts 1173 the operation by invoking the API function to pass information down 1174 to the callback without using global variables. The callback returns 1175 an SLPBoolean to indicate whether the API library should continue 1176 processing the operation. Asychronous operations are terminated, 1177 synchronous operations ignore the return (since the operation is 1178 already complete). 1180 4.3.1. SLPRegReport 1182 4.3.1.1. Synopsis 1184 typedef void SLPRegReport(SLPHandle hSLP, 1185 SLPError errCode, 1186 void *pvCookie); 1188 4.3.1.2. Description 1190 The SLPRegReport callback type is the type of the callback function 1191 to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. 1193 4.3.1.3. Parameters 1195 hSLP 1197 The SLPHandle used to initiate the operation. 1199 errCode 1201 An error code indicating if an error occured during the 1202 operation. 1204 pvCookie 1206 Memory passed down from the client code that called the 1207 original API function, starting the operation. May be NULL. 1209 4.3.2. SLPSrvTypeCallback 1211 4.3.2.1. Synopsis 1213 typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP, 1214 const char* pcSrvTypes, 1215 SLPError errCode, 1216 void *pvCookie); 1218 4.3.2.2. Description 1220 The SLPSrvTypeCallback type is the type of the callback function 1221 parameter to SLPFindSrvTypes() function. The client should return a 1222 SLPBoolean value indicating whether it is interested in seeing more 1223 data on this operation. 1225 4.3.2.3. Parameters 1227 hSLP 1229 The SLPHandle used to initiate the operation. 1231 pcSrvTypes 1233 A character buffer containing a comma separated, null 1234 terminated list of service types. 1236 errCode 1238 An error code indicating if an error occured during the 1239 operation. The callback should check this error code before 1240 processing the parameters. If the error code is other than 1241 SLP_OK, then the API library may choose to terminate the 1242 outstanding operation. 1244 pvCookie 1246 Memory passed down from the client code that called the 1247 original API function, starting the operation. May be NULL. 1249 4.3.2.4. Returns 1251 The client code should return SLP_TRUE if more data is desired, 1252 otherwise SLP_FALSE. 1254 4.3.3. SLPSrvURLCallback 1256 4.3.3.1. Synopsis 1258 typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP, 1259 const char* pcSrvURL, 1260 unsigned short sLifetime, 1261 SLPError errCode, 1262 void *pvCookie); 1264 4.3.3.2. Description 1266 The SLPSrvURLCallback type is the type of the callback function 1267 parameter to SLPFindSrvs() function. The client should return a 1268 SLPBoolean value indicating whether it is interested in seeing more 1269 data on this operation. 1271 4.3.3.3. Parameters 1273 hSLP 1275 The SLPHandle used to initiate the operation. 1277 pcSrvURL 1279 A character buffer containing the returned service URL. 1281 sLifetime 1283 An unsigned short giving the life time of the service 1284 advertisement, in seconds. The value must be an unsigned 1285 integer less than or equal to SLP_LIFETIME_MAXIMUM. 1287 errCode 1289 An error code indicating if an error occured during the 1290 operation. The callback should check this error code before 1291 processing the parameters. If the error code is other than 1292 SLP_OK, then the API library may choose to terminate the 1293 outstanding operation. 1295 pvCookie 1297 Memory passed down from the client code that called the 1298 original API function, starting the operation. May be NULL. 1300 4.3.3.4. Returns 1302 The client code should return SLP_TRUE if more data is desired, 1303 otherwise SLP_FALSE. 1305 4.3.4. SLPAttrCallback 1307 4.3.4.1. Synopsis 1309 typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP, 1310 const char* pcAttrList, 1311 SLPError errCode, 1312 void *pvCookie); 1314 4.3.4.2. Description 1316 The SLPAttrCallback type is the type of the callback function 1317 parameter to SLPFindAttrs() function. The client should return a 1318 SLPBoolean value indicating whether it is interested in seeing more 1319 data on this operation. 1321 When the SLPFindAttrs() operation was originally called with a URL, 1322 the callback is called once regardless of whether the handle was 1323 opened asychronously or synchronously. The pcAttrList parameter 1324 contains the requested attributes as a comma separated list (or is 1325 empty if no attributes matched the original tag list). When the 1326 SLPFindAttrs() operation was originally called with a service type, 1327 the value of pcAttrList and calling behavior depend on whether the 1328 handle was opened asychronously or synchronously. If the handle 1329 was opened asychronously, the callback is called every time the API 1330 library has results from a remote agent. The pcAttrList parameter 1331 is uncollated between calls, and contains a comma separated list 1332 containing the results from the agent that immediately returned 1333 results. If the handle was opened synchronously, the results are 1334 collated from all returning agents and the callback is called once, 1335 with the pcAttrList parameter set to the collated result. 1337 4.3.4.3. Parameters 1339 hSLP 1341 The SLPHandle used to initiate the operation. 1343 pcAttrList 1345 A character buffer containing a comma separated, null 1346 terminated list of attribute id/value assignments, in SLP wire 1347 format; i.e. "(attr-id=attr-value-list)" [11]. 1349 errCode 1351 An error code indicating if an error occured during the 1352 operation. The callback should check this error code before 1353 processing the parameters. If the error code is other than 1354 SLP_OK, then the API library may choose to terminate the 1355 outstanding operation. 1357 pvCookie 1359 Memory passed down from the client code that called the 1360 original API function, starting the operation. May be NULL. 1362 4.3.4.4. Returns 1364 The client code should return SLP_TRUE if more data is desired, 1365 otherwise SLP_FALSE. 1367 4.4. Opening and Closing the SLP Library 1369 4.4.1. SLPOpen 1371 4.4.1.1. Synopsis 1373 SLPError SLPOpen(const char *pcLang, SLPBoolean isAsync, SLPHandle *phSLP); 1375 4.4.1.2. Description 1377 Returns a SLPHandle handle in the phSLP parameter for the language 1378 locale passed in as the pcLang parameter. The client indicates if 1379 operations on the handle are to be synchronous or asychronous through 1380 the isAsync parameter. The handle encapsulates the language locale 1381 for SLP requests issued through the handle, and any other resources 1382 required by the implementation. SLP properties are not encapsulated 1383 by the handle, they are global. The return value of the function 1384 is an SLPError code indicating the status of the operation. Upon 1385 failure, the phSLP parameter is NULL. 1387 An SLPHandle can only be used for one SLP API operation at a time. 1388 If the original operation was started asychronously, any attempt 1389 to start an additional operation on the handle while the original 1390 operation is pending results in the return of an SLP_HANDLE_IN_USE 1391 error from the API function. The SLPClose() API function terminates 1392 any outstanding calls on the handle. If an implementation is unable 1393 to support either asychronous or synchronous operation, due to memory 1394 constraints or lack of threading support, the SLP_NOT_IMPLEMENTED 1395 flag may be returned when the isAsync flag has the appropriate value. 1397 4.4.1.3. Parameters 1399 pcLang 1401 A pointer to an array of characters containing the RFC 1766 1402 Language Tag [10] for the natural language locale of requests 1403 and registrations issued on the handle. May not be NULL. 1405 4.4.2. SLPClose 1407 4.4.2.1. Synopsis 1409 void SLPClose(SLPHandle hSLP); 1411 4.4.2.2. Description 1413 Frees all resources associated with the handle. If the handle was 1414 invalid, the function returns silently. Any outstanding synchronous 1415 or asychronous operations are cancelled so their callback functions 1416 will not be called any further. 1418 4.4.2.3. Parameters 1420 SLPHandle 1422 A SLPHandle handle returned from a call to SLPOpen(). 1424 4.5. Protocol API 1426 4.5.1. SLPReg 1428 4.5.1.1. Synopsis 1430 SLPError SLPReg(SLPHandle hSLP, 1431 const char *pcSrvURL, 1432 const unsigned short usLifetime, 1433 const char *pcSrvType, 1434 const char *pcScopeList, 1435 const char *pcAttrs 1436 SLPBoolean fresh, 1437 SLPRegReport callback, 1438 void *pvCookie); 1440 4.5.1.2. Description 1442 Registers the URL in pcSrvURL having the lifetime sLifetime with the 1443 attribute list in pcAttrs. The pcAttrs list is a comma separated 1444 list of attribute assignments in on the wire format (including 1445 escaping of reserved characters). The sLifetime parameter must 1446 be nonzero and less than or equal to SLP_LIFETIME_MAXIMUM. The 1447 registration is done in scopes that are part of pcScopeList. If 1448 the fresh flag is SLP_TRUE, then the registration is new (the 1449 SLP protocol FRESH flag is set) and the registration replaces 1450 any existing registrations. If the fresh flag is SLP_FALSE, then 1451 an existing registration is updated. Rules for new and updated 1452 registrations, and the format for pcAttrs can be found in [11]. 1453 Registrations and updates take place in the language locale of the 1454 hSLP handle. 1456 The pcScopeList parameter supplies a comma delimited list of scopes 1457 for the registration. This parameter MUST NOT be NULL or the empty 1458 string, "". The scopes in the scope list SHOULD be one or more 1459 of the scopes obtainable from SLPFindScopes(). If an unsupported 1460 scope is specified, a SLP_SCOPE_NOT_SUPPORTED error MAY be returned. 1461 If the net.slp.useScopes parameter has been configured, then the 1462 pcScopeList parameter MUST be a supported scope. 1464 4.5.1.3. Parameters 1466 hSLP 1468 The language specific SLPHandle on which to register the 1469 advertisement. May not be NULL. 1471 pcSrvURL 1473 The URL to register. May not be NULL or the empty string. 1475 usLifetime 1477 An unsigned short giving the life time of the service 1478 advertisement, in seconds. The value must be an unsigned 1479 integer less than or equal to SLP_LIFETIME_MAXIMUM and greater 1480 than zero. 1482 pcSrvType 1484 The service type. If pURL is a service: URL, then this 1485 parameter is ignored. May not be null. 1487 pcScopeList 1489 The comma separated list of scopes applying to the 1490 registration. MUST contain all the scopes returned from the 1491 results of a SLPFindScopes() API invocation. May not be NULL. 1493 pcAttrs 1495 A comma separated list of attribute assignment expressions for 1496 the attributes of the advertisement. May not be NULL. Use 1497 empty string, "" for no attributes. 1499 callback 1501 A callback to report the operation completion status. May not 1502 be NULL. 1504 pvCookie 1506 Memory passed to the callback code from the client. May be 1507 NULL. 1509 4.5.1.4. Returns 1511 If an error occurs in starting the operation, one of the SLPError 1512 codes is returned. 1514 4.5.2. SLPDereg 1516 4.5.2.1. Synopsys 1518 SLPError SLPDereg(SLPHandle hSLP, 1519 const char *pcURL, 1520 const char *pcScopeList, 1521 SLPRegReport callback, 1522 void *pvCookie); 1524 4.5.2.2. Description 1526 Deregisters the advertisment for URL pURL in all scopes where the 1527 service is registered and all language locales, not just the locale 1528 of the SLPHandle. 1530 4.5.2.3. Parameters 1532 hSLP 1534 The language specific SLPHandle to use for deregistering. May 1535 not be NULL. 1537 pcURL 1539 The URL to deregister. May not be NULL. 1541 pcScopeList 1543 The comma separated list of scopes applying to the 1544 registration. MUST contain all the scopes returned from the 1545 results of a SLPFindScopes() API invocation. May not be NULL. 1547 callback 1549 A callback to report the operation completion status. May not 1550 be NULL. 1552 pvCookie 1554 Memory passed to the callback code from the client. May be 1555 NULL. 1557 4.5.2.4. Returns 1559 If an error occurs in starting the operation, one of the SLPError 1560 codes is returned. 1562 4.5.3. SLPDelAttrs 1564 4.5.3.1. Synopsys 1566 SLPError SLPDelAttrs(SLPHandle hSLP, 1567 const char *pcURL, 1568 const char *pcScopeList, 1569 const char *pcAttrs, 1570 SLPRegReport callback, 1571 void *pvCookie); 1573 4.5.3.2. Description 1575 Delete the selected attributes in the locale of the SLPHandle. 1577 4.5.3.3. Parameters 1579 hSLP 1581 The language specific SLPHandle to use for deleting attributes. 1582 May not be NULL. 1584 pURL 1586 The URL of the advertisement from which the attributes should 1587 be deleted. May not be NULL. 1589 pcScopeList 1591 The comma separated list of scopes applying to the 1592 registration. MUST contain all the scopes returned from the 1593 results of a SLPFindScopes() API invocation. May not be NULL. 1595 pcAttrs 1597 A comma separated list of attribute ids for the attributes to 1598 deregister. See Section 9.8 in [11] for a description of the 1599 list format. May not be NULL. 1601 callback 1603 A callback to report the operation completion status. May not 1604 be NULL. 1606 pvCookie 1608 Memory passed to the callback code from the client. May be 1609 NULL. 1611 4.5.3.4. Returns 1613 If an error occurs in starting the operation, one of the SLPError 1614 codes is returned. 1616 4.5.4. SLPFindSrvTypes 1618 4.5.4.1. Synopsis 1620 SLPError SLPFindSrvTypes(SLPHandle hSLP, 1621 const char *pcNamingAuthority, 1622 const char *pcScopeList, 1623 SLPSrvTypeCallback callback, 1624 void *pvCookie); 1626 The SLPFindSrvType() function issues an SLP service type request 1627 for service types in the scopes indicated by the pcScopeList. The 1628 results are returned through the callback parameter. The service 1629 types are independent of language locale, but only for services 1630 registered in one of scopes and for the indicated naming authority. 1632 If the naming authority is "*", then results are returned for all 1633 naming authorities. If the naming authority is the empty string, 1634 i.e. "", then the default naming authority, "IANA", is used. "IANA" 1635 is not a valid naming authority name, and it is a PARAMETER_BAD error 1636 to include it explicitly. 1638 The service type names are returned with the naming authority 1639 intact. If the naming authority is the default (i.e. empty string) 1640 then it is omitted, as is the separating ``.''. See [12] for more 1641 information on the syntax of service type names. 1643 4.5.4.2. Parameters 1645 hSLP 1647 The SLPHandle on which to search for types. May not be NULL. 1649 pcNamingAuthority 1651 The naming authority to search. Use "*" for all naming 1652 authorities and the empty string, "", for the default naming 1653 authority. May not be NULL. 1655 pcScopeList 1657 A pointer to a char containing comma separated list of scope 1658 names to search for service types. May not be NULL or the 1659 empty string, "". 1661 callback 1663 A callback function through which the results of the operation 1664 are reported. May not be NULL. 1666 pvCookie 1668 Memory passed to the callback code from the client. May be 1669 NULL. 1671 4.5.4.3. Returns 1673 If an error occurs in starting the operation, one of the SLPError 1674 codes is returned. 1676 4.5.5. SLPFindSrvs 1678 4.5.5.1. Synopsis 1680 SLPError SLPFindSrvs(SLPHandle hSLP, 1681 const char *pcServiceType, 1682 const char *pcScopeList, 1683 const char *pcSearchFilter, 1684 SLPSrvURLCallback callback, 1685 void *pvCookie); 1687 4.5.5.2. Description 1689 Issue the query for services on the language specific SLPHandle and 1690 return the results through the callback. The parameters determine 1691 the results 1693 4.5.5.3. Parameters 1695 hSLP 1697 The language specific SLPHandle on which to search for 1698 services. May not be NULL. 1700 pcServiceType 1702 The Service Type String for the request, such as can be 1703 discovered using SLPSrvTypes(). This could be, for example 1704 "service:printer:lpr" or "service:nfs". May not be NULL. 1706 pcScopeList 1708 A pointer to a char containing comma separated list of scope 1709 names. May not be NULL or the empty string, "". 1711 pcSearchFilter 1713 A query formulated of attribute pattern matching expressions in 1714 the form of a LDAPv3 Search Filter, see [8]. If this filter 1715 is empty, ie. "", all services of the requested type in the 1716 specified scopes are returned. May not be NULL. 1718 callback 1720 A callback function through which the results of the operation 1721 are reported. May not be NULL. 1723 pvCookie 1725 Memory passed to the callback code from the client. May be 1726 NULL. 1728 4.5.5.4. Returns 1730 If an error occurs in starting the operation, one of the SLPError 1731 codes is returned. 1733 4.5.6. SLPFindAttrs 1735 4.5.6.1. Synopsis 1737 SLPError SLPFindAttrs(SLPHandle hSLP, 1738 const char *pcURL, 1739 const char *pcScopeList, 1740 const char *pcAttrIds, 1741 SLPAttrCallback callback, 1742 void *pvCookie); 1744 4.5.6.2. Description 1746 This function returns service attributes matching the attribute ids 1747 for the indicated full or partial URL. If pcURL is a complete URL, 1748 the attribute information returned is for that particular service in 1749 the language locale of the SLPHandle. If pcURL is a partial URL, 1750 then all attributes for the service type are returned regardless 1751 of the language of registration. Results are returned through the 1752 callback. 1754 The result is filtered with an SLP attribute request filter string 1755 parameter, the syntax of which is described in [11]. If the filter 1756 string is the empty string, i.e. "", all attributes are returned. 1758 4.5.6.3. Parameters 1760 hSLP 1762 The language specific SLPHandle on which to search for 1763 attributes. May not be NULL. 1765 pcURL 1767 The full or partial URL. See [11] for partial URL syntax. May 1768 not be NULL. 1770 pcScopeList 1772 A pointer to a char containing comma separated list of scope 1773 names. May not be NULL or the empty string, "". 1775 pcAttrIds 1777 The filter string indicating which attribute values to return. 1778 Use empty string, "", to indicate all values. Wildcards 1779 matching all attribute ids having a particular prefix or suffix 1780 are also possible. See [11] for the exact format of the filter 1781 string. May not be NULL. 1783 callback 1785 A callback function through which the results of the operation 1786 are reported. May not be NULL. 1788 pvCookie 1790 Memory passed to the callback code from the client. May be 1791 NULL. 1793 4.5.6.4. Returns 1795 If an error occurs in starting the operation, one of the SLPError 1796 codes is returned. 1798 4.6. Miscellaneous Functions 1800 4.7. SLPFindScopes 1802 4.7.0.5. Synopsis 1804 SLPError SLPFindScopes(SLPHandle hSLP, 1805 const char* pcTypeHint, 1806 char** ppcScopeList); 1808 4.7.0.6. Description 1810 Sets ppcScopeList parameter to a pointer to a comma separated list 1811 including all available scope values. The list of scopes comes from 1812 a variety of sources: the configuration file's net.slp.useScopes 1813 property and the net.slp.DAAddresses property, DHCP, or through the 1814 DA discovery process. If there is any order to the scopes, preferred 1815 scopes are listed before less desirable scopes. There is always at 1816 least one name in the list, the default scope, "DEFAULT". 1818 4.7.0.7. Parameters 1820 hSLP 1822 The SLPHandle on which to search for scopes. May not be NULL. 1824 pcTypeHint 1826 A service type name to use as a hint if no scope information is 1827 available from DAs and SA discovery is used. Must not be NULL. 1828 Note that the API is free to ignore the hint if SA discovery is 1829 not implemented or the API client passes in an empty string or 1830 syntactically invalid service type name. 1832 ppcScopeList 1834 A pointer to char pointer into which the buffer pointer is 1835 placed upon return. The buffer is null terminated. The memory 1836 should be freed by calling SLPFree(). 1838 4.7.0.8. Returns 1840 If no error occurs, returns SLP_OK, otherwise, the appropriate error 1841 code. 1843 4.8. SLPParseSrvURL 1845 4.8.0.9. Synopsis 1847 SLPError SLPParseSrvURL(char *pcSrvURL 1848 SLPSrvURL** ppSrvURL); 1850 4.8.0.10. Description 1852 Parses the URL passed in as the argument into a service URL structure 1853 and return it in the ppSrvURL pointer. If a parse error occurs, 1854 returns SLP_PARSE_ERROR. The input buffer pcSrvURL is destructively 1855 modified during the parse and used to fill in the fields of the 1856 return structure. The structure returned in ppSrvURL should be freed 1857 with SLPFreeURL(). If the URL has no service part, the s_pcSrvPart 1858 string is the empty string, "", i.e. not NULL. If pcSrvURL is not 1859 a service: URL, then the s_pcSrvType field in the returned data 1860 structure is the URL's scheme, which might not be the same as the 1861 service type under which the URL was registered. If the transport is 1862 IP, the s_pcTransport field is the empty string. If the transport is 1863 not IP or there is no port number, the s_iPort field is zero. 1865 4.8.0.11. Parameters 1867 pcSrvURL 1869 A pointer to a character buffer containing the null terminated 1870 URL string to parse. It is destructively modified to produce 1871 the output structure. May not be NULL. 1873 ppSrvURL 1875 A pointer to a pointer for the SLPSrvURL structure to receive 1876 the parsed URL. May not be NULL. The memory should be freed by 1877 a call to SLPFree() when no longer needed. 1879 4.8.0.12. Returns 1881 If no error occurs, the return value is the SLP_OK. Otherwise, if 1882 an error occurs, one of the SLPError codes is returned. If no 1883 memory is available to allocate the character strings, returns 1884 SLP_COULD_NOT_ALLOCATE_MEMORY. If a parse error occurs, returns 1885 SLP_PROTOCOL_PARSE_ERROR. 1887 4.9. SLPFree 1889 4.9.0.13. Synopsis 1891 void SLPFree(void* pvMem); 1893 4.9.0.14. Description 1895 Frees memory returned from SLPParseSrvURL(), SLPEscape(), 1896 SLPUnescape(), and SLPFindScopes(). 1898 4.9.0.15. Parameters 1900 pvMem 1902 A pointer to the storage allocated by the SLPParseSrvURL(), 1903 SLPEscape(), SLPUnescape(), or SLPFindScopes() function. 1904 Ignored if NULL. 1906 4.10. SLPEscape 1908 4.10.0.16. Synopsis 1910 SLPError SLPEscape(const char* pcInbuf, 1911 char** ppcOutBuf, 1912 SLPBoolean isTag); 1914 4.10.0.17. Description 1916 Process the input string in pcInbuf and escape any SLP reserved 1917 characters. If the isTag parameter is SLPTrue, then look for 1918 bad tag characters and signal an error if any are found with the 1919 SLP_PARSE_ERROR code. The results are put into a buffer allocated by 1920 the API library and returned in the ppcOutBuf parameter. This buffer 1921 should be deallocated using SLPFree() when the memory is no longer 1922 needed. 1924 4.10.0.18. Parameters 1926 pcInbuf 1928 Pointer to he input buffer to process for escape characters. 1930 ppcOutBuf 1932 Pointer to a pointer for the output buffer with the SLP 1933 reserved characters escaped. Must be freed using SLPFree() 1934 when the memory is no longer needed. 1936 isTag 1938 When true, the input buffer is checked for bad tag characters. 1940 4.10.0.19. Returns 1942 Return SLP_PARSE_ERROR if any characters are bad tag characters and 1943 the isTag flag is true, otherwise SLP_OK. 1945 4.11. SLPUnescape 1947 4.11.0.20. Synopsis 1949 SLPError SLPUnescape(const char* pcInbuf, 1950 char** ppcOutBuf, 1951 SLPBoolean isTag); 1953 4.11.0.21. Description 1955 Process the input string in pcInbuf and unescape any SLP reserved 1956 characters. If the isTag parameter is SLPTrue, then look for 1957 bad tag characters and signal an error if any are found with the 1958 SLP_PARSE_ERROR code. No transformation is performed if the input 1959 string is an opaque. The results are put into a buffer allocated by 1960 the API library and returned in the ppcOutBuf parameter. This buffer 1961 should be deallocated using SLPFree() when the memory is no longer 1962 needed. 1964 4.11.0.22. Parameters 1966 pcInbuf 1968 Pointer to he input buffer to process for escape characters. 1970 ppcOutBuf 1972 Pointer to a pointer for the output buffer with the SLP 1973 reserved characters escaped. Must be freed using SLPFree() 1974 when the memory is no longer needed. 1976 isTag 1978 When true, the input buffer is checked for bad tag characters. 1980 4.11.0.23. Returns 1982 Return SLP_PARSE_ERROR if any characters are bad tag characters and 1983 the isTag flag is true, otherwise SLP_OK. 1985 4.12. SLPGetProperty 1987 4.12.0.24. Synopsis 1989 const char* SLPGetProperty(const char* pcName); 1991 4.12.0.25. Description 1993 Returns the value of the corresponding SLP property name. The 1994 returned string is owned by the library and MUST NOT be freed. 1996 4.12.0.26. Parameters 1998 pcName 2000 Null terminated string with the property name, from 2001 Section 2.1. May not be NULL. 2003 4.12.0.27. Returns 2005 If no error, returns a pointer to the property value. If the 2006 property was not set, returns the empty string, "". If an error 2007 occurs, returns NULL. The returned string MUST NOT be freed. 2009 4.13. SLPSetProperty 2011 4.13.0.28. Synopsis 2013 void SLPSetProperty(const char *pcName, 2014 const char *pcValue); 2016 4.13.0.29. Description 2018 Sets the value of the SLP property to the new value. The pcValue 2019 parameter should be the property value as a string. 2021 4.13.0.30. Parameters 2023 pcName 2025 Null terminated string with the property name, from 2026 Section 2.1. May not be NULL. 2028 pcValue 2030 Null terminated string with the property value, in character 2031 format. May not be NULL. 2033 4.14. Implementation Notes 2035 4.14.1. Refreshing Registrations 2037 Because not all C platforms support multithreading, implementing 2038 automatic refreshing of registrations in the SA may be difficult. 2039 Therefore, automatic registration refreshing is not required of C 2040 implementations, however, implementations with multithreading are 2041 encouraged to support this important feature. 2043 4.14.2. Syntax for String Parameters 2045 Query strings, attribute registration lists, attribute deregistration 2046 lists, scope lists, and attribute selection lists follow the syntax 2047 described in [11] for the appropriate requests. The API directly 2048 reflects the strings passed in from clients into protocol requests, 2049 and directly reflects out strings returned from protocol replies to 2050 clients. As a consequence, clients are responsible for formatting 2051 request strings, including escaping and converting opaque values to 2052 escaped byte encoded strings. Similarly, on output, clients are 2053 required to unescape strings and convert escaped string encoded 2054 opaques to binary. The functions SLPEscape() and SLPUnescape() can 2055 be used for escaping SLP reserved characters, but perform no opaque 2056 processing. 2058 Opaque values consist of a character buffer containing a UTF8-encoded 2059 string, the first characters of which are the nonUTF8 encoding '\ff'. 2060 Subsequent characters are the escaped values for the original bytes 2061 in the opaque. The escape convention is relatively simple. An 2062 escape consists of a backslash followed by the two hexadecimal digits 2063 encoding the byte. in the ASCII subset of UTF8. An example is '\2c' 2064 for the byte 0x2c. Clients handle opaque processing themselves, 2065 since the algorithm is relatively simple and uniform. 2067 4.14.3. Client Side Syntax Checking 2069 API implementations may do syntax checking of scope names, naming 2070 authority names, and service type names on the client side, but 2071 are not required to do so. Since the C API is designed to be a 2072 thin layer over the protocol, some low memory SA implementations 2073 may find extensive syntax checking on the client side to be 2074 burdensome. If syntax checking uncovers an error in a parameter, the 2075 SLP_PARAMETER_BAD error must be returned. If any parameter is NULL 2076 and is required to be nonNULL, SLP_PARAMETER_BAD is returned. 2078 4.14.4. System Properties 2080 The system properties established in the configuration file are 2081 accessable through the SLPGetProperty() and SLPSetProperty() 2082 functions. The SLPSetProperty() function only modifies properties 2083 in the running process, not in the configuration file. Errors 2084 are checked when the property is used and, as with parsing the 2085 configuration file, are logged. Program execution continues without 2086 interruption by substituting the default for the erroneous parameter. 2087 In general, individual agents should rarely be required to override 2088 these properties, since they reflect properties of the SLP network 2089 that are not of concern to individual agents. If changes are 2090 required, system administrators should modify the configuration file. 2092 4.14.5. Memory Management 2094 The only API functions returning memory specifically requiring 2095 deallocation on the part of the client are SLPParseSrvURL(), 2096 SLPEscape(), SLPUnescape(), and SLPFindScopes(). This memory should 2097 be freed using SLPFree() when no longer needed. Character strings 2098 returned via the SLPGetProperty() function should NOT be freed, they 2099 are owned by the SLP library. 2101 Memory passed to callbacks belongs to the library and MUST NOT be 2102 retained by the client code. Otherwise, crashes are possible. 2103 Clients are required to copy data out of the callback parameters. No 2104 other use of the memory in callback parameters is allowed. 2106 4.14.6. Asychronous and Incremental Return Semantics 2108 If a handle parameter to an API function was opened asychronously, 2109 API function calls on the handle check the other parameters, open the 2110 appropriate operation and return immediately. In an error occurs in 2111 the process of starting the operation, an error code is returned. If 2112 the handle parameter was opened synchronously, the API function call 2113 blocks until all results are available, and returns only after the 2114 results are reported through the callback function. The return code 2115 indicates whether any errors occured both starting and during the 2116 operation. 2118 The callback function is called whenever the API library has 2119 results to report. The callback code is required to check the 2120 error code parameter before looking at the other parameters. If 2121 the error code is not SLP_OK, the other parameters may be NULL or 2122 otherwise invalid. The API library has the option of terminating 2123 any outstanding operation on which an error occurs. The callback 2124 code can similarly indicate that the operation should be terminated 2125 by passing back SLP_FALSE. Callback functions are not permitted to 2126 recursively call into the API on the same SLPHandle. If an attempt 2127 is made to recursively call into the API, the API function returns 2128 SLP_HANDLE_IN_USE. Prohibiting recursive callbacks on the same handle 2129 simplifies implementation of thread safe code, since locks held 2130 on the handle will not be in place during a second outcall on the 2131 handle. 2133 The total number of results received can be controlled by setting the 2134 net.slp.maxResults parameter. 2136 4.15. Examples 2138 4.15.1. Discovering one's mailbox 2140 A POP3 server might register itself with the SLP framework. The 2141 attributes it registers are "USER", a comma delimited list of all 2142 users whose mail is available through the POP3 server. 2144 The POP3 server code could be the following: 2146 SLPHandle slph; 2147 SLPRegReport errCallback = POPRegErrCallback; 2149 /* Create an English SLPHandle, asynchronous processing. */ 2151 SLPError err = SLPOpen("en", SLP_TRUE, &slph); 2153 if( err != SLP_OK ) { 2155 /* Deal with error. */ 2157 } 2159 /* Create the service: URL and attribute parameters. */ 2161 const char* surl = "service:pop3://mail.netsurf.de"; /* the URL */ 2163 const char *pcScopeList = "default,engineering"; 2165 const char *pcAttrs = "(user=sally,sue,sandra,zsuzsa)" 2167 err = SLPReg(slph, 2168 surl, SLP_LIFETIME_DEFAULT, 2169 pcScopeList, pcAttrs, 2170 errCallback, NULL); 2172 if (err != SLP_OK ) { 2174 /*Deal with error.*/ 2176 } 2178 The errCallback reports any errors: 2180 void 2181 POPRegErrCallback(SLPHandle hSLP, 2182 SLPError errCode, 2183 void* pvCookie) { 2185 if( errCode != SLP_OK ) { 2187 /* Report error through a dialog, message, etc. */ 2189 } 2190 } 2192 The POP3 client may locate the server for the user: 2194 /* 2195 * The client calls SLPOpen(), exactly as above. 2196 */ 2198 const char *pcSrvType = "service:pop3"; /* the service type */ 2199 const char *pcScopeList = "default"; /* the scope */ 2200 const char *pcFilter = "(user=sue)"; /* the search filter */ 2201 SLPSrvURLCallback srvCallback = /* the callback */ 2202 POPSrvURLCallback; 2204 err = SLPFindSrvs(slph, 2205 pcSrvType, pcScopeList, pcFilter, 2206 srvCallback, NULL); 2208 if( err != SLP_OK ) { 2210 /* Deal with error. */ 2212 } 2214 Within the callback, the client code can use the returned POP 2215 service: 2217 SLPBoolean 2218 POPSrvURLCallback(SLPHandle hSLP, 2219 const char* pcSrvURL, 2220 unsigned short sLifetime, 2221 SLPError errCode, 2222 void* pvCookie) { 2224 if( errCode != SLP_OK ) { 2226 /* Deal with error. */ 2228 } 2230 SLPSrvURL* pSrvURL; 2232 errCode = SLPParseSrvURL(pcSrvURL, &pSrvURL); 2234 if (err != SLP_OK ) { 2236 /* Deal with error. */ 2238 } else { 2240 /* get the server's address */ 2242 struct hostent *phe = gethostbyname(pSrvURL.s_pcHost); 2244 /* use hostname in pSrvURL to connect to the POP3 server 2245 * . . . 2246 */ 2248 SLPFreeSrvURL(pSrvURL); /* Free the pSrvURL storage */ 2249 } 2251 return SLP_FALSE; /* Done! */ 2253 } 2255 A client that wanted to discover all the users receiving mail at the 2256 server could do so with the following query: 2258 /* 2259 * The client calls SLPOpen(), exactly as above. We assume the 2260 * service: URL was retrieved into surl. 2261 */ 2263 const char *pcScopeList = "default"; /* the scope */ 2264 const char *pcAttrFilter = "use"; /* the attribute filter */ 2265 SLPAttrCallback attrCallBack = /* the callback */ 2266 POPUsersCallback 2268 err = 2269 SLPFindAttrs(slph, 2270 surl, 2271 pcScopeList, pcAttrFilter, 2272 attrCallBack, NULL); 2274 if( err != SLP_OK ) { 2276 /* Deal with error. */ 2278 } 2280 The callback processes the attributes: 2282 SLPBoolean 2283 POPUsersCallback(const char* pcAttrList, 2284 SLPError errCode, 2285 void* pvCookie) { 2287 if( errCode != SLP_OK ) { 2289 /* Deal with error. */ 2291 } else { 2293 /* Parse attributes. */ 2295 } 2297 return SLP_FALSE; /* Done! */ 2299 } 2301 5. Java Language Binding 2303 5.1. Introduction 2305 The Java API is designed to model the various SLP entities in 2306 classes and objects. APIs are provided for SA, UA, and service type 2307 template access capabilities. The ServiceLocationManager class 2308 contains methods that return instances of objects implementing SA 2309 and UA capability. Each of these is modelled in an interface. 2310 The Locator interface provides UA capability and the Advertiser 2311 interface provides SA capability. The TemplateRegistry abstract 2312 class contains methods that return objects for template introspection 2313 and attribute type checking. The ServiceURL, ServiceType, and 2314 ServiceLocationAttribute classes model the basic SLP concepts. A 2315 concrete subclass instance of TemplateRegistry is returned by a class 2316 method. 2318 All SLP classes and interfaces are located within a single package. 2319 The package name should begin with the name of the implementation and 2320 conclude with the suffix "slp". Thus, the name for a hypothetical 2321 implementation from the University of Michigan would look like: 2323 edu.umich.slp 2325 This follows the Java convention of prepending the top level DNS 2326 domain name for the organization implementing the package onto the 2327 organization's name and using that as the package prefix. 2329 5.2. Exceptions and Errors 2331 Most parameters to API methods are required to be nonnull. The 2332 API description indicates if a null parameter is acceptable, or 2333 if other restrictions constrain a parameter. When parameters 2334 are checked for validity (such as not being null) or their 2335 syntax is checked, an error results in the RuntimeException 2336 subclass IllegalArgumentException being thrown. Clients of the 2337 API are reminded that IllegalArgumentException, derived from 2338 RuntimeException, is unchecked by the compiler. Clients should 2339 thus be careful to include try/catch blocks for it if the relevent 2340 parameters could be erroneous. 2342 Standard Java practice is to encode every exceptional condition as a 2343 seperate subclass of Exception. Because of the relatively high cost 2344 in code size of Exception subclasses, the API contains only a single 2345 Exception subclass with different conditions being determined by an 2346 integer error code property. A subset, appropriate to Java, of the 2347 error codes described in Section 3 are available as constants on the 2348 ServiceLocationException class. The subset excludes error codes such 2349 as MEMORY_ALLOC_FAILED. 2351 5.2.1. Class ServiceLocationException 2353 5.2.1.1. Synopsis 2355 public class ServiceLocationException 2356 extends Exception 2358 5.2.1.2. Description 2360 The ServiceLocationException class is thrown by all methods when 2361 exceptional conditions occur in the SLP framework. The error 2362 code property determines the exact nature of the condition, and an 2363 optional message may provide more information. 2365 5.2.1.3. Fields 2367 public static final short LANGUAGE_NOT_SUPPORTED; 2368 public static final short PARSE_ERROR; 2369 public static final short INVALID_REGISTRATION; 2370 public static final short SCOPE_NOT_SUPPORTED; 2371 public static final short AUTHENTICATION_FAILED; 2372 public static final short AUTHENTICATION_ABSENT; 2373 public static final short INVALID_UPDATE; 2374 public static final short NOT_IMPLEMENTED; 2375 public static final short NETWORK_INIT_FAILED; 2376 public static final short NETWORK_TIMED_OUT; 2377 public static final short NETWORK_ERROR; 2378 public static final short INTERNAL_SYSTEM_ERROR; 2379 public static final short TYPE_ERROR; 2381 5.2.1.4. Instance Methods 2383 public short getErrorCode() 2385 Return the error code. The error code takes on one of the static 2386 field values. 2388 5.3. Basic Data Structures 2390 5.3.1. Interface ServiceLocationEnumeration 2392 public interface ServiceLocationEnumeration 2393 extends Enumeration 2395 5.3.1.1. Description 2397 The ServiceLocationEnumeration class is the return type for all 2398 Locator SLP operations. The Java API library may implement this 2399 class to block until results are available from the SLP operation, 2400 so that the client can achieve asynchronous operation by retrieving 2401 results from the enumeration in a separate thread. Clients use the 2402 superclass nextElement() method if they are unconcerned with SLP 2403 exceptions. 2405 5.3.1.2. Instance Methods 2407 public abstract Object next() throws ServiceLocationException 2409 Return the next value or block until it becomes available. 2411 Throws: 2413 ServiceLocationException 2415 Thrown if the SLP operation encounters an error. 2417 NoSuchElementException 2419 If there are no more elements to return. 2421 5.3.2. Class ServiceLocationAttribute 2423 5.3.2.1. Synopsis 2425 public class ServiceLocationAttribute 2426 extends Object implements Serializable 2428 5.3.2.2. Description 2430 The ServiceLocationAttribute class models SLP attributes. Instances 2431 of this class are returned by Locator.findAttributes() and are 2432 communicated along with register/deregister requests. 2434 5.3.2.3. Constructors 2436 public ServiceLocationAttribute(String id,Vector values) 2438 Construct a service location attribute. Errors in the id or values 2439 vector result in an IllegalParameterException. 2441 Parameters: 2443 id 2445 The attribute name. The String can consist of any Unicode 2446 character. 2448 values 2450 A Vector of one or more attribute values. Vector contents 2451 must be uniform in type and one of Integer, String, Boolean, 2452 or byte[]. If the attribute is a keyword attribute, then 2453 parameter should be null. String values can consist of any 2454 Unicode character. 2456 5.3.2.4. Class Methods 2458 public static String escapeId(String id) 2459 throws ServiceLocationException 2461 Returns an escaped version of the id parameter, suitable for 2462 inclusion in a query. Any reserved characters as specified in [11] 2463 are escaped using UTF8 encoding. 2465 Parameters: 2467 id 2469 The attribute id to escape. ServiceLocationException is thrown 2470 if any characters are illegal in an id. 2472 public static String escapeValue(Object value) 2473 throws ServiceLocationException 2475 Returns a String containing the escaped value parameter as a String, 2476 suitable for inclusion in a query. If the value parameter is a 2477 string, any reserved characters as specified in [11] are escaped 2478 using UTF8 encoding. If the value parameter is a byte array, then 2479 the escaped string begins with the nonUTF8 sequence `\ff` and the 2480 rest of the string consists of the escaped bytes. If the value 2481 parameter is a Boolean or Integer, then the returned string contains 2482 the object converted into a string. If the value is any other type, 2483 an IllegalArgumentException is thrown. 2485 Parameters: 2487 value 2489 The attribute value to be converted into a string and escaped. 2491 5.3.2.5. Instance Methods 2493 public Vector getValues() 2495 Returns a cloned vector of attribute values, or null if the attribute 2496 is a keyword attribute. If the attribute is single-valued, then the 2497 vector contains only one object. 2499 public String getId() 2501 Returns the attribute's name. 2503 public boolean equals(Object o) 2505 Overrides Object.equals(). Two attributes are equal if their 2506 identifiers are equal and their value vectors contain the same number 2507 of equal values as determined by the Object equals() method. Values 2508 having byte[] type are equal if the contents of all byte arrays in 2509 both vectors match. 2511 public String toString() 2513 Overrides Object.toString(). 2515 public int hashCode() 2517 Overrides Object.hashCode(). Hashes on the attribute's id. 2519 5.3.3. Class ServiceType 2521 5.3.3.1. Synopsis 2523 public class ServiceType extends Object implements Serializable 2525 5.3.3.2. Description 2527 The ServiceType object models the SLP service type. It parses a 2528 string based service type specifier into its various components, and 2529 contains property accessors to return the components. URL schemes, 2530 protocol service types, and abstract service types are all handled. 2532 5.3.3.3. Constructors 2534 public ServiceType(String type) 2536 Construct a service type object from the service type specifier. 2537 Throws IllegalArgumentException if the type name is syntactically 2538 incorrect. 2540 Parameters: 2542 type 2544 The service type name as a String. If the service type is from 2545 a service: URL, the "service:" prefix must be intact. 2547 5.3.3.4. Methods 2549 public boolean isServiceURL() 2551 Returns true if the type name contains the "service:" prefix. 2553 public boolean isServiceURL() 2555 Returns true if the type name contains the "service:" prefix. 2557 public boolean isAbstractType() 2559 Returns true if the type name is for an abstract type. 2561 public boolean isNADefault() 2563 Returns true if the naming authority is the default, i.e. is the 2564 empty string. 2566 public String getConcreteTypeName() 2568 Returns the concrete type name in an abstract type, the protocol name 2569 in a protocol type, or the URL scheme if the type name is not for a 2570 service: URL. 2572 public String getPrincipleTypeName() 2574 Returns the abstract type name for an abstract type or an empty 2575 string for a protocol type or URL scheme. 2577 public String getAbstractTypeName() 2579 If the type is an abstract type, returns the fully formatted abstract 2580 type name including the "service:" and naming authority but without 2581 the concrete type name or intervening colon. 2583 public String getNamingAuthority() 2585 Return the naming authority name, or the empty string if the naming 2586 authority is the default. 2588 public boolean equals(Object obj) 2590 Overrides Object.equals(). The two objects are equal if they are 2591 both ServiceType objects and the components of both are equal. 2593 public String toString() 2595 Returns the fully formatted type name, including the "service:" if 2596 the type was originally from a service: URL. 2598 public int hashCode() 2600 Overrides Object.hashCode(). Hashes on the string value of the 2601 individual components of the service type name. 2603 5.3.4. Class ServiceURL 2605 5.3.4.1. Synopsis 2607 public class ServiceURL extends Object implements Serializable 2609 5.3.4.2. Description 2611 The ServiceURL object models the advertised SLP service URL. It 2612 can be either a service: URL or a regular URL. These objects are 2613 returned from service lookup requests, and describe the registered 2614 services. This class should be a subclass of java.net.URL but can't 2615 since that class is final. 2617 5.3.4.3. Class Variables 2619 public static final int NO_PORT 2621 Indicates that no port information is required or was returned for 2622 this URL. 2624 public static final int LIFETIME_NONE 2626 Indicates that the URL has a zero lifetime. This value is never 2627 returned from the API, but can be used to create a ServiceURL object 2628 to deregister, delete attributes, or find attributes. 2630 public static final int LIFETIME_DEFAULT 2632 The default URL lifetime (3 hours) in seconds. 2634 public static final short LIFETIME_MAXIMUM 2636 The maximum URL lifetime (about 18 hours) in seconds. 2638 5.3.4.4. Constructors 2640 public ServiceURL(String URL,short lifetime) 2642 Construct a service URL object having the specified lifetime. 2644 Parameters: 2646 URL 2648 The URL as a string. Must be either a service: URL or a valid 2649 regular URL. 2651 lifetime 2653 The service advertisement lifetime in seconds. This value may 2654 be between LIFETIME_NONE and LIFETIME_MAXIMUM. 2656 5.3.4.5. Methods 2658 public ServiceType getServiceType() 2660 Returns the service type object representing the service type name of 2661 the URL. 2663 public final void setServiceType(ServiceType type) 2664 throws ServiceLocationException 2666 Set the service type name to the object. Ignored if the URL is a 2667 service: URL. 2669 Parameters: 2671 type 2673 The service type object. 2675 public String getTransport() 2677 Get the network layer transport identifier. If the transport is IP, 2678 an empty string, "", is returned. 2680 public String getHost() 2682 Returns the host identifier. For IP, this will be the machine name 2683 or IP address. 2685 public int getPort() 2687 Returns the port number, if any. For nonIP transports, always 2688 returns NO_PORT. 2690 public String getURLPath() 2692 Returns the URL path description, if any. 2694 public int getLifetime() 2696 Returns the service advertisement lifetime. This will be a positive 2697 int between LIFETIME_NONE and LIFETIME_MAXIMUM. 2699 public boolean equals(Object obj) 2701 Compares the object to the ServiceURL and returns true if the two are 2702 the same. Two ServiceURL objects are equal if their current service 2703 types match and they have the same host, port, transport, and URL 2704 path. 2706 public String toString() 2708 Returns formatted string with the URL. Overrides Object.toString(). 2709 The returned URL has the original service type or URL scheme, not the 2710 current service type. 2712 public int hashCode() 2714 Overrides Object.hashCode(). Hashes on the current service type, 2715 transport, host, port, and URL part. 2717 5.4. SLP Access Interfaces 2719 5.4.1. Interface Advertiser 2721 5.4.1.1. Synopsis 2723 public interface Advertiser 2725 5.4.1.2. Description 2727 The Advertiser is the SA interface, allowing clients to register new 2728 service instances with SLP, to change the attributes of existing 2729 services, and to deregister service instances. New registrations 2730 and modifications of attributes are made in the language locale 2731 with which the Advertiser was created, deregistrations of service 2732 instances are made for all locales. 2734 5.4.1.3. Instance Methods 2736 public abstract Locale getLocale() 2738 Return the language locale with which this object was created. 2740 public abstract void register(ServiceURL URL, 2741 Vector scopes, 2742 Vector attributes) 2743 throws ServiceLocationException 2745 Register a new service with SLP having the given attributes and 2746 in the given scope. 2748 Parameters: 2750 URL 2752 The URL for the service. 2754 scopes 2756 A Vector of scope names. Scope Strings MUST contain all 2757 the scopes returned from the results of a findScopes() API 2758 invocation. 2760 attributes 2762 A vector of ServiceLocationAttribute objects describing the 2763 service. 2765 public abstract void deregister(ServiceURL URL,Vector scopes) 2766 throws ServiceLocationException 2768 Deregister a service from the SLP framework. This has the effect of 2769 deregistering the service from every language locale in the given 2770 scopes. 2772 Parameters: 2774 URL 2776 The URL for the service. 2778 scopes 2780 A Vector of scope names. Scope Strings MUST contain all 2781 the scopes returned from the results of a findScopes() API 2782 invocation. 2784 public abstract void 2785 addAttributes(ServiceURL URL, 2786 Vector scopes, 2787 Vector attributes) 2788 throws ServiceLocationException 2790 Update the registration by adding the given attributes in the given 2791 scopes. 2793 Parameters: 2795 URL 2797 The URL for the service. 2799 scopes 2801 A Vector of scope names. Scope Strings MUST contain all 2802 the scopes returned from the results of a findScopes() API 2803 invocation. 2805 attributes 2807 A Vector of ServiceLocationAttribute objects to add to the 2808 existing registration. Use an empty vector to update the URL 2809 alone. May not be null. 2811 public abstract void 2812 deleteAttributes(ServiceURL URL, 2813 Vector scopes, 2814 Vector attributeIds) 2815 throws ServiceLocationException 2817 Delete the attributes from a URL in all scopes for the locale with 2818 which the Advertiser was created. 2820 Parameters: 2822 URL 2824 The URL for the service. 2826 scopes 2828 A Vector of scope names. Scope Strings MUST contain all 2829 the scopes returned from the results of a findScopes() API 2830 invocation. 2832 attributeIds 2834 A vector of Strings indicating the ids of the attributes to 2835 remove. Use an empty vector to indicate all attributes. 2837 5.4.2. Interface Locator 2839 5.4.2.1. Synopsis 2841 public interface Locator 2843 5.4.2.2. Description 2845 The Locator is the UA interface, allowing clients to query the SLP 2846 framework about existing service types, services instances, and about 2847 the attributes of an existing service instance or service type. 2848 Queries for services and attributes are made in the locale with which 2849 the Locator was created, queries for service types are independent of 2850 locale. 2852 5.4.2.3. Instance Methods 2854 public abstract Locale getLocale() 2856 Return the language locale with which this object was created. 2858 public abstract ServiceLocationEnumeration 2859 findServiceTypes(String namingAuthority, 2860 Vector scopes) 2862 throws ServiceLocationException 2864 Returns an enumeration of ServiceType objects giving known service 2865 types for the given scopes and given naming authority. If no service 2866 types are found, an empty enumeration is returned. 2868 Parameters: 2870 namingAuthority 2872 The naming authority. Use "" for the default naming authority 2873 and "*" for all naming authorities. 2875 scopes 2877 A Vector of scope names. Scope Strings SHOULD be selected from 2878 the results of a findScopes() API invocation. Use "DEFAULT" 2879 for the default scope. 2881 public abstract ServiceLocationEnumeration 2882 findServices(ServiceType type, 2883 Vector scopes, 2884 String searchFilter) 2885 throws ServiceLocationException 2887 Returns a vector of ServiceURL objects for services matching the 2888 query, and having a matching type in the given scopes. If no 2889 services are found, an empty enumeration is returned. 2891 Parameters: 2893 type 2895 The SLP service type of the service. 2897 scopes 2899 A Vector of scope names. Scope Strings SHOULD be selected from 2900 the results of a findScopes() API invocation. Use "DEFAULT" 2901 for the default scope. 2903 searchFilter 2905 An LDAPv3 [8] string encoded query. If the filter is empty, 2906 ie. "", all services of the requested type in the specified 2907 scopes are returned. SLP reserved characters must be escaped 2908 in the query. Use ServiceLocationAttribute.escapeId() and 2909 ServiceLocatinAttribute.escapeValue() to construct the query. 2911 public abstract ServiceLocationEnumeration 2912 findAttributes(ServiceURL URL, 2913 Vector scopes, 2914 Vector attributeIds) 2915 throws ServiceLocationException 2917 For the URL and scope, return a Vector of ServiceLocationAttribute 2918 objects whose ids match the String patterns in the attributeIds 2919 Vector. The request is made in the language locale of the Locator. 2920 If no attributes match, an empty enumeration is returned. 2922 Parameters: 2924 URL 2926 The URL for which the attributes are desired. 2928 scopes 2930 A Vector of scope names. Scope Strings SHOULD be selected from 2931 the results of a findScopes() API invocation. Use "DEFAULT" 2932 for the default scope. 2934 attributeIds 2936 A Vector of String patterns identifying the desired attributes. 2937 An empty vector means return all attributes. As described 2938 in [11], the patterns may include wildcards to match 2939 all prefixes or suffixes. The patterns may include SLP 2940 reserved characters, they will be escaped by the API before 2941 transmission. 2943 public abstract ServiceLocationEnumeration 2944 findAttributes(ServiceType type, 2945 Vector scopes, 2946 Vector attributeIds) 2947 throws ServiceLocationException 2949 For the type and scope, return a Vector of all ServiceLocationAttribute 2950 objects whose ids match the String patterns in the attributeIds 2951 Vector. The request is made independent of language locale. If no 2952 attributes are found, an empty vector is returned. 2954 Parameters: 2956 serviceType 2958 The service type. 2960 scopes 2962 A Vector of scope names. Scope Strings SHOULD be selected from 2963 the results of a findScopes() API invocation. Use "DEFAULT" 2964 for the default scope. 2966 attributeIds 2968 A Vector of String patterns identifying the desired attributes. 2969 An empty vector means return all attributes. As described 2970 in [11], the patterns may include wildcards to match 2971 all prefixes or suffixes. The patterns may include SLP 2972 reserved characters, they will be escaped by the API before 2973 transmission. 2975 5.5. The Service Location Manager 2977 5.5.1. Class ServiceLocationManager 2979 5.5.1.1. Synopsis 2981 public class ServiceLocationManager 2982 extends Object 2984 5.5.1.2. Description 2986 The ServiceLocationManager manages access to the service location 2987 framework. Clients obtain the Locator and Advertiser objects 2988 for UA and SA, and a Vector of known scope names from the 2989 ServiceLocationManager. 2991 5.5.1.3. Class Methods 2993 public static Vector findScopes(ServiceType typeHint) 2994 throws ServiceLocationException 2995 Returns an Vector of strings with all available scope names. The 2996 list of scopes comes from a variety of sources. Scope names obtained 2997 through DHCP have first priority, followed by scope names in the 2998 net.slp.useScopes property. These names are used to filter names 2999 obtained from the net.slp.DAAddresses property and through active 3000 and passive discovery. There is always at least one string in the 3001 Vector, the default scope, "DEFAULT". 3003 Parameters: 3005 typeHint 3007 A service type name to use as a hint if no scope information is 3008 available from DAs and SA discovery is used. May be null if SA 3009 discovery is not desired. Note that the API is free to ignore 3010 the hint if SA discovery is not implemented. 3012 public static Locator 3013 getLocator(Locale locale) 3014 throws ServiceLocationException 3016 Return a Locator object for the given language Locale. If the 3017 implementation does not support UA functionality, returns null. 3019 Parameters: 3021 locale 3023 The language locale of the Locator. The default SLP locale is 3024 used if null. 3026 public static Advertiser 3027 getAdvertiser(Locale locale) 3028 throws ServiceLocationException 3030 Return an Advertiser object for the given language locale. If the 3031 implementation does not support SA functionality, returns null. 3033 Parameters: 3035 locale 3037 The language locale of the Advertiser. The default SLP locale 3038 is used if null. 3040 5.6. Service Template Introspection 3042 5.6.1. Abstract Class TemplateRegistry 3044 5.6.1.1. Synopsis 3046 public abstract class TemplateRegistry 3048 5.6.1.2. Description 3050 Subclasses of the TemplateRegistry abstract class provide 3051 access to service location templates [12]. Classes implementing 3052 TemplateRegistry perform a variety of functions. They manage the 3053 registration and access of service type template documents. They 3054 create attribute verifiers from service templates, for verification 3055 of attributes and introspection on template documents. Note that 3056 clients of the Advertiser are not required to verify attributes 3057 before registering (though they may get a TYPE_ERROR if the 3058 implementation supports type checking and there is a mismatch with 3059 the template). 3061 5.6.1.3. Class Methods 3063 public static TemplateRegistry getTemplateRegistry(); 3065 Returns the distinguished TemplateRegistry object for performing 3066 operations on and with service templates. Returns null if the 3067 implementation doesn't support TemplateRegistry functionality. 3069 5.6.1.4. Instance Methods 3071 public abstract void 3072 registerServiceTemplate(ServiceType type, 3073 String documentURL, 3074 Locale locale, 3075 String version) 3076 throws ServiceLocationException 3078 Register the service template with the template registry. 3080 Parameters: 3082 type 3084 The service type. 3086 documentURL 3088 The URL of the template document. 3090 locale 3092 A Locale object containing the language locale of the template. 3094 version 3096 The version number of template document. 3098 public abstract void 3099 deregisterServiceTemplate(ServiceType type, 3100 Locale locale, 3101 String version) 3102 throws ServiceLocationException 3104 Deregister the template for the service type. 3106 Parameters: 3108 type 3110 The service type. 3112 locale 3114 A Locale object containing the language locale of the template. 3116 version 3118 A String containing the version number. Use null to indicate 3119 the latest version. 3121 public abstract 3122 String findTemplateURL(ServiceType type, 3123 Locale locale, 3124 String version) 3125 throws ServiceLocationException 3126 Returns the URL for the template document. 3128 Parameters: 3130 type 3132 The service type. 3134 locale 3136 A Locale object containing the language locale of the template. 3138 version 3140 A String containing the version number. Use null to indicate 3141 the latest version. 3143 public abstract 3144 ServiceLocationAttributeVerifier 3145 attributeVerifier(String documentURL) 3146 throws ServiceLocationException 3148 Reads the template document URL and returns an attribute verifier 3149 for the service type. The attribute verifier can be used for 3150 verifying that registration attributes match the template, and for 3151 introspection on the template definition. 3153 Parameters: 3155 documentURL 3157 A String containing the template document's URL. 3159 5.6.2. Interface ServiceLocationAttributeVerifier 3161 5.6.2.1. Synopsis 3163 public interface ServiceLocationAttributeVerifier 3165 5.6.2.2. Description 3167 The ServiceLocationAttributeVerifier provides access to service 3168 templates. Classes implementing this interface parse SLP template 3169 definitions, provide information on attribute definitions for 3170 service types, and verify whether a ServiceLocationAttribute object 3171 matches a template for a particular service type. Clients obtain 3172 ServiceLocationAttributeVerifier objects for specific SLP service 3173 types through the TemplateRegistry. 3175 5.6.2.3. Instance Methods 3177 public abstract ServiceType getServiceType() 3179 Returns the SLP service type for which this is the verifier. 3181 public abstract Vector 3182 getTemplateAttributeDescriptors() 3184 Returns a Vector of ServiceLocationAttributeDescriptor objects 3185 describing the template service type attributes. The template 3186 service type attributes are: 3188 service-type 3190 The SLP service type name (a String). 3192 version 3194 The version number of the template (a String). 3196 language 3198 The RFC 1766 [10] Language Tag locale of the template (a 3199 String). 3201 description 3203 A natural language description of the service in the language 3204 of the language locale (a String). 3206 url-syntax 3208 An ABNF [9] description for the of the service type's URL (a 3209 String). 3211 public abstract Vector 3212 getTemplateAttributes() 3214 Returns a Vector of ServiceLocationAttribute objects for the template 3215 attributes of this service type. The template attributes are listed 3216 above. The ServiceLocationAttribute objects in this vector have the 3217 actual values of the template attributes. 3219 public abstract ServiceLocationAttributeDescripton 3220 getAttributeDescriptor(String attrId) 3222 Return the ServiceLocationAttributeDescription for the attribute 3223 having the named id. If no such attribute exists in this template, 3224 return null. This method is primarily for GUI tools to display 3225 attribute information. Programmatic verification of attributes 3226 should use the verifyAttribute() method. 3228 public abstract Enumeration 3229 getAttributeDescriptors() 3231 Returns an Enumeration allowing introspection on the attribute 3232 definition in the service template. The Enumeration returns 3233 ServiceLocationAttributeDescriptor objects for the attributes. 3234 This method is primarily for GUI tools to display attribute 3235 information. Programmatic verification of attributes should use the 3236 verifyAttribute() method. 3238 public abstract void 3239 verifyAttribute( 3240 ServiceLocationAttribute attribute) 3241 throws ServiceLocationException 3243 Verify that the attribute matches the template definition. If the 3244 attribute doesn't match, ServiceLocationException is thrown with the 3245 error code as ServiceLocationException.PARSE_ERROR. 3247 Parameters: 3249 attribute 3251 The ServiceLocationAttribute object to be verified. 3253 public abstract void 3254 verifyRegistration( 3255 Vector attributeVector) 3256 throws ServiceLocationException 3258 Verify that the Vector of ServiceLocationAttribute objects matches 3259 the template for this service type. The vector must contain all the 3260 required attributes, and all attributes must match their template 3261 definitions. If the attributes don't match, ServiceLocationException 3262 is thrown with the error code as ServiceLocationException.PARSE_ERROR 3264 Parameters: 3266 attributeVector 3268 A Vector of ServiceLocationAttribute objects for the 3269 registration. 3271 5.6.3. Interface ServiceLocationAttributeDescriptor 3273 5.6.3.1. Synopsis 3275 public interface 3276 ServiceLocationAttributeDescriptor 3278 5.6.3.2. Description 3280 The ServiceLocationAttributeDescriptor interface provides 3281 introspection on a template attribute defintion. Classes 3282 implementing the ServiceLocationAttributeDescriptor interface return 3283 information on a particular service location attribute definition 3284 from the service template. This information is primarily for GUI 3285 tools. Programmatic attribute verification should be done through 3286 the ServiceLocationAttributeVerifier. 3288 5.6.3.3. Instance Methods 3290 public abstract String getId() 3292 Return a String containing the attribute's id. 3294 public abstract String getValueType() 3296 Return a String containing the fully package-qualified Java type of 3297 the attribute. SLP types are translated into Java types as follows: 3299 STRING 3301 "java.lang.String" 3303 INTEGER 3305 "java.lang.Integer" 3307 BOOLEAN 3309 "java.lang.Boolean" 3311 OPAQUE 3313 "[B" (i.e. array of byte, byte[]) 3315 KEYWORD 3317 empty string, "" 3319 public abstract String getDescription() 3321 Return a String containing the attribute's help text. 3323 public abstract Enumeration 3324 getAllowedValues() 3326 Return an Enumeration of allowed values for the attribute type. 3327 For keyword attributes returns null. For no allowed values (i.e. 3328 unrestricted) returns an empty Enumeration. 3330 public abstract Enumeration 3331 getDefaultValues() 3333 Return an Enumeration of default values for the attribute type. 3334 For keyword attributes returns null. For no allowed values (i.e. 3335 unrestricted) returns an empty Enumeration. 3337 public abstract boolean getIsMultivalued() 3339 Returns true if the "M" flag is set. 3341 public abstract boolean getIsOptional() 3343 Returns true if the "O"" flag is set. 3345 public abstract boolean 3346 getRequiredAttribute() 3348 Returns true if the "X"" flag is set, indicating that the attribute 3349 SHOULD be included in an any Locator.findServices() request search 3350 filter. 3352 public abstract boolean getIsLiteral() 3354 Returns true if the "L" flag is set. 3356 public abstract boolean getIsKeyword() 3358 Returns true if the attribute is a keyword attribute. 3360 5.7. Implementation Notes 3362 5.7.1. Refreshing Registrations 3364 Because Java supports threads at the language level, automatic 3365 refreshing of service advertisements in the Advertiser API is 3366 required. 3368 5.7.2. Parsing Alternate Transports in ServiceURL 3370 The ServiceURL class is designed to handle multiple transports. The 3371 standard API performs no additional processing on transports other 3372 than IP. However, implementations are free to subclass ServiceURL 3373 and support additional methods that provide more detailed parsing of 3374 alternate transport information. For IP transport, the port number, 3375 if any, is returned from the getPort() method. For nonIP transports, 3376 the getPort() method returns NO_PORT. 3378 5.7.3. Client Side Syntax Checking 3380 The syntax of scope names, service type names, naming authority 3381 names, and URLs is described in [11] and [12]. The various methods 3382 and classes taking String parameters for these entities should 3383 type check the parameters for syntax errors on the client side, 3384 and throw an IllegalArgumentException if an error occurs. In 3385 addition, character escaping should be implemented before network 3386 transmission for escapable characters in attribute ids and String 3387 values. This reduces the number of error messages transmitted. The 3388 ServiceLocationAttribute class provides methods for obtaining escaped 3389 attribute id and value strings to facilitate query construction. 3391 5.7.4. Language Locale Handling 3393 The Locator and Advertiser interfaces are created with a Locale 3394 parameter. The language locale with which these objects are created 3395 is used in all SLP requests issued through the object. If the Locale 3396 parameter is null, the default SLP locale is used. The default SLP 3397 locale is determined by, first, checking the net.slp.locale System 3398 property. If that is unset, then the default SLP locale [11] is 3399 used, namely "en". The net.slp.locale property is the only SLP 3400 system property that a client of the API would routinely override. 3402 5.7.5. Setting SLP System Properties 3404 SLP system properties that are originally set in the configuration 3405 file can be overridden programmatically in API clients by simply 3406 invoking the System.getProperties() operation to get a copy of the 3407 system properties, modifying or adding the SLP property in question, 3408 then using System.setProperties() to set the properties to the 3409 modified Property object. Errors are checked when the property 3410 is used and, as with parsing the configuration file, are logged. 3411 Program execution continues without interruption by substituting the 3412 default for the erroneous parameter. In general, individual agents 3413 should rarely be required to override these properties, since they 3414 reflect properties of the SLP network that are not of concern to 3415 individual agents. If changes are required, system administrators 3416 should modify the configuration file. 3418 5.7.6. Multithreading 3420 Thread-safe operation are relatively easy to achieve in Java. By 3421 simply making each method in the classes implementing the Locator 3422 and Advertiser interfaces synchronized, and by synchronizing access 3423 to any shared data structures within the class the Locator and 3424 Advertiser interfaces are made safe. Alternatively, finer grained 3425 synchronization is also possible within the classes implementing 3426 Advertiser and Locator. 3428 5.7.7. Modular Implementations 3430 While, at first glance, the API may look rather heavyweight, the 3431 design has been carefully arranged so that modular implementations 3432 that provide only SA, only UA, or only service template access 3433 capability, or any combination of the three, are possible. 3435 Because the objects returned from the ServiceLocationManager.getLocator() 3436 and ServiceLocationManager.getAdvertiser() operations are interfaces, 3437 and because the objects returned through those interfaces are in 3438 the set of base data structures, an implementation is free to omit 3439 either UA or SA capability by simply returning null from the instance 3440 creation operation if the classes implementing the missing function 3441 is cannot be dynamically linked. API clients are encouraged to check 3442 for such a contingency, and to signal an exception if it occurs. 3443 Similarly, the TemplateRegistry subclass can simply be omitted from 3444 an implementation that only supports UA and/or SA clients, and 3445 the getRegistry() method can return null. In this way, the API 3446 implementation can be taylored for the particular memory requirements 3447 at hand. 3449 In addition, if an implementation only supports the minimal subset of 3450 SLP [11], the unsupported Locator and Advertiser interface operations 3451 can throw an exception with ServiceLocationException.NOT_IMPLEMENTED 3452 as the error code. This supports better source portablity between 3453 low and high memory platforms. 3455 5.7.8. Asynchronous and Incremental Return Semantics 3457 The Java API contains no specific support for asychronous operation. 3458 Incremental return is not needed for the Advertiser because service 3459 registrations can be broken up into pieces when large. Asychronous 3460 return is also not needed because clients can always issue the 3461 Advertiser operation in a separate thread if the calling thread can't 3462 block. 3464 The Locator can be implemented either sychronously or 3465 asychronously. Since the return type for Locator calls is 3466 ServiceLocationEnumeration, a Java API implementation that supports 3467 asynchronous semantics can implement ServiceLocationEnumeration 3468 to dole results out as they come in, blocking when no results are 3469 available. If the client code needs to support other processing 3470 while the results are trickling in, the call into the enumeration to 3471 retrieve the results can be done in a separate thread. 3473 Unlike the C case, collation semantics for return of attributes when 3474 the request is made with a service type require that the API collate 3475 returned values so that only one attribute having a collation of all 3476 returned values appear to the API client. In practice, this may 3477 limit the amount of asychronony possible with the findAttributes() 3478 method. This requirement is imposed because memory management is 3479 much easier in Java and so implementing collation as part of the API 3480 should not be as difficult as in C, and it saves the client from 3481 having to do the collation. 3483 5.8. Examples 3485 In this example, a printer server advertises its availability to 3486 clients. Additionally, the server advertises a service template for 3487 use by client software in validating service requests: 3489 //Get the Advertiser and TemplateRegistry. 3491 Advertiser adv = null; 3492 TemplateRegistry tr = null 3494 try { 3495 adv = ServiceLocationManager.getAdvertiser("en"); 3497 tr = TemplateRegistry.getTemplateRegistry(); 3499 } catch( ServiceLocationException ex ) { } //Deal with error. 3501 if( adv == null ) { 3503 //Serious error as printer can't be registered 3504 // if the implementation doesn't support SA 3505 // functionality. 3507 } 3509 //Get the scopes in which we are supposed to 3510 // register. 3512 Vector scopes = ServiceLocationManager.findScopes(); 3514 //Get the printer's attributes, from a file or 3515 // otherwise. We assume that the attributes 3516 // conform to the template, otherwise, we 3517 // could register the template here and verify 3518 // them. 3520 Vector attributes = getPrinterAttributes(); 3522 //Create the service: URL for the printer. 3524 ServiceURL printerURL = 3525 new ServiceURL( 3526 "service:printer:lpr://printshop/color2", 3527 ServiceURL.LIFETIME_MAXIMUM); 3529 try { 3531 //Register the printer in all scopes. 3533 adv.register(printerURL, scopes, attributes); 3535 //If the template registry is available, 3536 // register the printer's template. 3538 if( tr != null ) { 3539 tr.registerServiceTemplate( 3540 new ServiceType("service:printer"), 3541 "http://shop.arv/printer/printer-lpr.slp", 3542 new Locale("en",""), 3543 "1.0"); 3545 } 3547 } catch( ServiceLocationException ex ) { } //Deal with error. 3549 Suppose a client is looking for color printer. The following code 3550 might be used to issue a request for printer advertisements: 3552 Locator loc = null; 3553 TemplateRegistry tr = null; 3555 try { 3557 loc = ServiceLocationManager.getLocator("en"); 3559 } catch( ServiceLocationException ex ) { } //Deal with error. 3561 if( loc == null ) { 3563 //Serious error as client can't be located 3564 // if the implementation doesn't support 3565 // UA functionality. 3567 } 3569 //We want a color printer that does CMYK 3570 // and prints at least 600 dpi. 3572 String query = "(&(marker-type=CMYK)(resolution=600))"; 3574 //Get scopes. 3576 Vector scopes = ServiceLocationManager.findScopes(); 3578 Enumeration services; 3580 try { 3582 services = 3583 loc.findServices(new ServiceType("service:printer"),scopes,query); 3585 } catch { } //Deal with error. 3587 if (services.hasMoreElements() ) { 3589 //Printers can now be used. 3591 ServiceURL surl = (ServiceURL) services.next(); 3593 Socket sock = new Socket(surl.getHost, surl.getPort()); 3595 // Use the Socket... 3597 } 3599 6. Internationalization Considerations 3601 6.1. service URL 3603 The service URL itself must be encoded using the rules set forth 3604 in [2]. The character set encoding is limited to specific ranges 3605 within the UTF8 character set [7]. 3607 The attribute information associated with the service URL may be 3608 expressed in any character set, and in any language. See [12] for 3609 attribute internationalization guidelines. 3611 6.2. Character Set Encoding 3613 Configuration and serialized registration files are encoded in 3614 the UTF8 character set [7]. This is fully compatible with ASCII 3615 character values. C platforms that do not support UTF8 are required 3616 to check the top bit of input bytes to determine whether the incoming 3617 character is multibyte. If it is, the character should be dealt with 3618 accordingly. Since the SLP wire protocol requires that strings are 3619 encoded as UTF8, C platforms without UTF8 support need to supply 3620 their own support, if only in the form of multibyte string handling. 3622 At the API level, the character encoding is specified to be Unicode 3623 for Java and UTF8 for C. Unicode is the default in Java. For C, the 3624 standard ASCII 8 bits per character, null terminated C strings are 3625 a subset of the UTF8 character set, and so work in the API. Because 3626 the C API is very simple, the API library needs to do a minimum of 3627 processing on UTF8 strings. They primarily just need to be reflected 3628 into the outgoing SLP messages, and reflected out of the API from 3629 incoming SLP messages. 3631 6.3. Language Tagging 3633 All SLP requests and registrations are tagged to indicate in which 3634 language the strings included are encoded. This allows multiple 3635 languages to be supported. It also presents the possibility that 3636 error conditions result when a request is made in a language that is 3637 not supported. In this case, an error is only returned when there is 3638 data available, but not obtainable in the language requested. 3640 The dialect portion of the Language Tag is used on 'best effort' 3641 basis for matching strings by SLP. Dialects that match are prefered 3642 over those which don't. Dialects that do not match will not prevent 3643 string matching or comparisons to occur. 3645 7. Security Considerations 3647 SLP makes use of an existing host based authentication framework once 3648 it becomes available as an Internet Standard. [5] 3650 An adversary could delete valid service advertisements, provide false 3651 service information and deny UAs knowledge of existing services 3652 unless the mechanisms in SLP for authenticating SLP messages are 3653 used. These mechanisms allow DA Adverts, SA Adverts, Service URLs 3654 and Service Attributes to be verified using digital cryptography. 3655 For this reason, all SLP agents SHOULD be configured to use protected 3656 scopes and DA Advertisement verifying cryptographic keys. See [11] 3657 for a description of how these mechanisms work. 3659 8. Acknowledgements 3661 The authors would like to thank Don Provan for his pioneering work 3662 during the initial stages of API definition. 3664 References 3666 [1] ANSI. Coded Character Set -- 7-bit American Standard code for 3667 Information Interchange. X3.4-1986, 1986. 3669 [2] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource 3670 Locators (URL): Generic Syntax and Semantics. RFC1738 as 3671 amended by RFC1808 and updated by draft-fielding-url-syntax-05.txt, 3672 May 1997. (work in progress). 3674 [3] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service 3675 Location Protocol. RFC 2165, July 1997. 3677 [4] IANA IANA Character Set Registry 3678 3680 [5] R. Atkinson Security Architecture for the Internet RFC 1825 3681 July 1995 3683 [6] Geneva ISO Code for the representation of names of languages 3684 ISO 639:1998 (E/F) 1998 3686 [7] F. Yerfeau UTF-8, a transformation format of ISO 10646. RFC 3687 2279 January 1998. 3689 [8] T. Howes The String Representation of LDAP Search Filters RFC 3690 2254 December 1997. 3692 [9] D. Crocker and P Overell. Augmented BNF for Syntax 3693 Specifications: ABNF. RFC 2234 November 1997. 3695 [10] H. Alvestrand. Tags for the Identification of Languages. RFC 3696 1766 March 1995. 3698 [11] E. Guttman, C. Perkins, J. Veizades, and M. Day. Service 3699 Location Protocol. draft-ietf-svrloc-protocol-v2-04.txt A work 3700 in progress March 1998. 3702 [12] E. Guttman, C. Perkins, J. Kempf Service Templates and service: 3703 Schemes draft-ietf-svrloc-service-scheme-09.txt A work in 3704 progress March 1998. 3706 Authors' Addresses 3708 Questions about this memo can be directed to: 3710 James Kempf Erik Guttman 3711 Sun Microsystems Sun Microsystems 3712 901 San Antonio Rd. Bahnstr. 2 3713 Palo Alto, CA, 94303 74915 Waibstadt 3714 USA Germany 3715 +1 650 786 5890 +49 7263 911 701 3716 +1 650 786 6445 (fax) 3717 james.kempf@sun.com erik.guttman@sun.com