idnits 2.17.1 draft-kempf-svrloc-rfc2614bis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 26) being 63 lines 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 40 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 734 has weird spacing: '... int s_iP...' == Line 815 has weird spacing: '...LPError errCo...' == Line 838 has weird spacing: '...PHandle hSLP...' == Line 840 has weird spacing: '...LPError err...' == Line 910 has weird spacing: '...PHandle hSLP...' == (3 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.) -- The document date (Feburary 2002) is 8166 days in the past. Is this intentional? -- 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) ** Downref: Normative reference to an Informational RFC: RFC 2614 (ref. '1') ** Obsolete normative reference: RFC 2396 (ref. '3') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2279 (ref. '4') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2254 (ref. '5') (Obsoleted by RFC 4510, RFC 4515) ** Obsolete normative reference: RFC 2234 (ref. '6') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 1766 (ref. '7') (Obsoleted by RFC 3066, RFC 3282) -- No information found for draft-guttman-rfc2608bis - is the name correct? -- Possible downref: Normative reference to a draft: ref. '8' Summary: 9 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 James Kempf 3 Internet Draft Erik Guttman 4 Document: draft-kempf-svrloc-rfc2614bis-00.txt 5 Expires: August 2002 Feburary 2002 7 An API for Service Location 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 24 The list of Internet-Draft Shadow Directories can be accessed at 25 http://www.ietf.org/shadow.html. 27 Abstract 28 The Service Location Protocol (SLP) provides a way for clients to 29 dynamically discovery network services. This document describes a 30 standardized API for SLP in the C language. In addition, 31 standardized file formats for configuration and serialized 32 registrations are defined. This document defines a new API for SLP 33 that supercedes the definition in RFC 2614. 35 Table of Contents 37 1.0 Introduction.................................................3 38 1.1 Terminology..................................................3 39 2.0 File Formats.................................................3 40 2.1 Configuration File Format....................................4 41 2.1.1 DA configuration............................................6 42 2.1.2 Preconfiguration............................................6 43 2.1.3 Tracing and Logging.........................................7 44 2.1.4 Serialized Proxy Registrations..............................7 45 2.1.5 Network Configuration Properties............................7 46 2.1.6 SA Configuration............................................9 47 2.1.7 UA Configuration............................................9 48 2.2 Serialized Registration File.................................10 49 2.3 Processing Serialized Registration and Configuration Files..11 50 3.0 The API.....................................................11 51 3.1 Constant Types...............................................11 52 3.1.1 URL Lifetimes..............................................11 53 3.2 Error Codes..................................................12 54 3.3 SLPBoolean...................................................13 55 3.4 Structure Types..............................................14 56 3.4.1 SLPSrvURL..................................................14 57 3.4.2 SLPHandle..................................................15 58 3.5 Callback Types..............................................15 59 3.5.1 SLPRegReport...............................................15 60 3.5.2 SLPSrvTypeCallback.........................................16 61 3.5.3 SLPSrvURLCallback..........................................16 62 3.5.4 SLPAttrCallback............................................17 63 3.6 Opening and Closing an SLPHandle............................18 64 3.6.1 SLPOpen....................................................18 65 3.6.2 SLPClose...................................................18 66 3.7 SA API.......................................................19 67 3.7.1 SLPReg.....................................................19 68 3.7.2 SLPDereg...................................................20 69 3.7.3 SLPFindSrvTypes............................................21 70 3.7.4 SLPFindSrvs................................................22 71 3.7.5 SLPFindAttrs...............................................23 72 3.8 Miscellaneous Functions......................................24 73 3.8.1 SLPGetRefreshInterval......................................24 74 3.8.2 SLPFindScopes..............................................24 75 3.8.3 SLPParseSrvURL.............................................25 76 3.8.4 SLPParseAttrs..............................................25 77 3.8.5 SLPEscape..................................................26 78 3.8.6 SLPUnescape................................................27 79 3.8.7 SLPFree....................................................27 80 3.8.8 SLPGetProperty.............................................28 81 3.8.9 SLPSetProperty.............................................28 82 3.8.10 SLPGetExtensionInterface..................................29 83 3.8.11 SLPFreeExtensionInterface.................................29 84 4.0 Implementation Considerations...............................30 85 4.1 Callback Semantics...........................................30 86 4.2 Asynchronous Semantics.......................................31 87 4.3 Scope and DA Configuration and Discovery.....................32 88 4.4 Multithreading...............................................32 89 4.5 Type Checking for Registrations..............................32 90 4.6 Refreshing Registrations.....................................33 91 4.7 Character Set Encoding.......................................33 92 4.8 Error Handling...............................................33 93 4.9 Modular Implementations......................................34 94 4.10 Handling Special Service Types..............................34 95 4.11 Syntax for String Parameters................................34 96 4.12 Client Side Syntax Checking.................................35 97 4.13 SLP Configuration Properties................................35 98 4.14 Memory Management...........................................35 99 4.15 Multi-homed Hosts...........................................35 100 4.16 Unicast UA Requests.........................................36 101 4.17 UA Caching..................................................36 102 5.0 Deprecated Features.........................................37 103 6.0 Example.....................................................37 104 7.0 Security Considerations.....................................39 105 8.0 Acknowledgements............................................39 106 9.0 References..................................................40 107 10.0 Editors' Addresses.........................................40 108 11.0 Full Copyright Statement...................................40 110 1.0 Introduction 112 The Service Location API is designed for standardized access to the 113 Service Location Protocol (SLP) through a C language interface. The 114 API facilitates writing portable client and service programs. In 115 addition, standardized formats for configuration files and for 116 serialized registration files are presented. These files allow 117 system administrators to configure network parameters, to register 118 legacy services that have not been SLP-enabled, and to portably 119 exchange configuration and registration files. This document 120 supercedes the SLP API definition in RFC 2614 [1] and corresponds to 121 the protocol definition described in [8]. 123 1.1 Terminology 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in RFC 2119 [2]. 129 Please see [8] for specific SLP protocol-related terms. 131 SA Server 133 Many operating system platforms only allow a single process to 134 listen on a particular port number for TCP. Since general 135 purpose SAs are required to listen on TCP for SLP requests, 136 implementations of the SLP supporting multiple SAs on such 137 platforms need to arrange for a single process to do the 138 listening. The advertising SAs communicate with that process 139 through another mechanism, described here in Section XXX. The 140 single listening process is called an SA server. SA servers 141 share many characteristics with DAs, but they are not the 142 same. 144 2.0 File Formats 146 This section describes the configuration and serialized registration 147 file formats. Both files are defined in the UTF-8 character set [4], 148 and they must not include a Byte Order Mark (BOM) at the beginning, 149 to maximize compatibility with US-ASCII. The rules governing 150 attribute tags and values in serialized registration files and 151 configuration files are exactly the same as those for the wire 152 format described in [8]. Attribute tags and string values require 153 SLP reserved characters to be escaped. The SLP reserved characters 154 are '(', ')', ',', '\', '!', '<', '=', '>', '~' and control 155 characters (characters with UTF codes less than 0x0020 and the 156 character 0x007f, which is US-ASCII DEL). The escapes are formed 157 exactly as for the wire protocol, i.e. a backslash followed by two 158 hex digits representing the character. For example, the escape for 159 ',' is '\2c'. In addition, the characters "\n", "\r", "\t", and '_' 160 are prohibited from attribute tags by the SLP wire syntax grammar 161 [8]. Other characters may be escaped, and are processed into the 162 corresponding characters upon input, exactly as for reserved 163 characters. 165 In file encodings for attribute values, strings beginning with 166 "\ff", an encoding for a nonUTF-8 character, are treated as opaques. 167 Exactly as in the wire protocol, syntactically correct opaque 168 encodings consist of a string beginning with "\ff" and containing 169 *only* escaped characters that are transformed to bytes. Such 170 strings are only syntactically correct as attribute values. In a 171 string beginning with "\ff", if any characters are not escaped, it 172 is a syntax error. 174 Escaped characters in URLs use the URL escape convention [3]. 176 Property names and values in the configuration file have a few 177 reserved characters that are involved in file's lexical definition, 178 in addition to those involving attributes described above, for those 179 property values that contain attribute list definitions. The 180 characters '.' and '=' are reserved in property names and must be 181 escaped. The characters ',', '(', and ')' are reserved in all 182 property values, not just attribute list definitions, and must be 183 escaped. In addition, scope names in the net.slp.configuredScopes 184 property use the SLP wire format escape convention for SLP reserved 185 characters. This simplifies implementation, since the same code can 186 be used to unescape scope names as is used for formatting wire 187 messages. 189 On platforms that only support US-ASCII and not UTF-8, the upper bit 190 of bytes incoming from the configuration and registration files 191 determines whether the character is US-ASCII or not. According to 192 the standard UTF-8 encoding, the upper bit is zero if the character 193 is US-ASCII and one if the character is multibyte and thus not US- 194 ASCII. Platforms without intrinsic UTF-8 support are required to 195 parse the multibyte character and store it in an appropriate 196 internal format. Support for UTF-8 is required to implement the SLP 197 protocol (see [8]), and can therefore be used in file processing as 198 well. 200 The location and name of the configuration file is system-dependent, 201 but implementations of the API are encouraged to locate it together 202 with other configuration files and name it consistently. 204 2.1 Configuration File Format 206 The configuration file format consists of a newline delimited list 207 of zero or more property definitions. Each property definition 208 corresponds to a particular configurable SLP, network, or other 209 parameter in one or more of the three SLP agents. The file format 210 grammar in ABNF [6] syntax is: 212 config-file = line-list 213 line-list = line / line line-list 214 line = property-line / comment-line 215 comment-line = ( "#" / ";" ) 1*allchar newline 216 property-line = property newline 217 property = tag "=" value-list 218 tag = prop / prop "." tag 219 prop = 1*tagchar 220 list = value / value "," list 221 value = int / bool / attribute / 222 string / addr 223 int = 1*DIGIT 224 bool = "true" / "false" / "TRUE" / "FALSE" 225 newline = CR / ( CRLF ) 226 string = 1*stringchar 227 attribute = ; see the definition of attribute 228 ; list in Section 4.3.6 of [8]. 229 addr = fqdn / hostnumber 230 fqdn = ALPHA / ALPHA *[ anum / "-" ] anum 231 anum = ALPHA / DIGIT 232 hostnumber = 1*3DIGIT 3("." 1*3DIGIT) 233 tagchar = DIGIT / ALPHA / tother / escape 234 tother = %x21-%x2d / %x2f / 235 %x3a / %x3c-%x40 / 236 %x5b-%x60 / %7b-%7e 237 ; i.e., all characters except `.', 238 ; and `='. 239 stringchar = DIGIT / ALPHA / sother / escape 240 sother = %x21-%x29 / %x2a-%x2b / 241 %x2d-%x2f / %x3a-%x40 / 242 %x5b-%x60 / %7b-%7e 243 ; i.e., all characters except `,' 244 allchar = DIGIT / ALPHA / HTAB / SP 245 escape = "\" HEXDIG HEXDIG 246 ; Used for reserved characters 248 All properties can be changed through the SLPSetProperty() API 249 function. However, changing certain properties has no effect on 250 further execution in the API library, since these properties are 251 only involved in conveying preconfigured information to the API 252 library on startup and are not used afterwards. These properties are 253 net.slp.configuredScopes, net.slp.configuredDAAddresses, and 254 net.slp.enableBroadcast. 256 On multi-homed hosts, it may be necessary to have different network 257 configuration properties for different interfaces. The 258 net.slp.interfaces property indicates which network interfaces are 259 SLP enabled. An API library implementation may support configuration 260 customization on a per network interface basis by allowing the 261 interface IP address or host name to be appended to the property 262 name. In that case, the values of the property are only used for 263 that particular interface, the generic property (or defaults if no 264 generic property is set) applies to all others. 266 For example, if a configuration file has the following properties: 268 net.slp.interfaces=125.196.42.41,125.196.42.42,125.196.42.43 269 net.slp.multicastTTL.125.196.42.42=1 270 then the network interface on subnet 42 is restricted to a TTL of 1, 271 while the interfaces on the other subnets have the default multicast 272 TTL, 255. 274 The following subsections describe an area and its properties. 276 2.1.1 DA configuration 278 The following properties are used for DA configuration. They are 279 ignored if the host is not configured as a DA: 281 net.slp.isDA 282 Type: Boolean 283 Default: FALSE 284 Use: A Boolean configuring the SLP server to act as a DA. 285 If TRUE, run as a DA. 287 net.slp.DAHeartBeat 288 Type: Unsigned 32 bit integer 289 Default: 10800 seconds (3 hours) 290 Use: The number of seconds between transmission of 291 unsolicited DAAdverts by the DA. This property 292 corresponds to the protocol specification parameter 293 CONFIG_DA_BEAT [8]. 295 net.slp.DAAttributes 296 Type: List of Attribute 297 Default: Null 298 Use: A list of parenthesized attribute/value list pairs 299 that the DA must advertise in DAAdverts. 301 2.1.2 Preconfiguration 303 The following properties convey statically configured or DHCP- 304 configured information to all agents. Changing these properties 305 using SLPSetProperty() has no effect on execution. 307 net.slp.configuredScopes 308 Type: List of String 309 Default: Null 310 Use: A list of statically configured or DHCP-configured 311 scopes. 313 net.slp.configuredDAAddresses 314 Type: List of Address 315 Default: Null 316 Use: A list of statically configured or DHCP-configured DA 317 IP addresses or DNS-resolvable host names. 319 net.slp.enableBroadcast 320 Type: Boolean 321 Default: FALSE 322 Use: If TRUE, enable all SLP agents to use broadcast 323 instead of multicast, and disable multicast. 325 2.1.3 Tracing and Logging 327 The following properties are used to control tracing and logging of 328 error and warning messages. 330 net.slp.traceDATraffic 331 Type: Boolean 332 Default: FALSE 333 Use: If TRUE, print log messages about traffic to DAs. 335 net.slp.traceMsg 336 Type: Boolean 337 Default: FALSE 338 Use: If TRUE, print log messages of all incoming and 339 outgoing SLP messages. 341 net.slp.traceDrop 342 Type: Boolean 343 Default: FALSE 344 Use: If TRUE, print log messages when a SLP message is 345 dropped for any reason. 347 net.slp.traceReg 348 Type: Boolean 349 Default FALSE 350 Use: If TRUE, dump all registred services when a 351 registration or deregistration occurs. 353 2.1.4 Serialized Proxy Registrations 355 The following property controls processing of serialized 356 registrations. 358 net.slp.serializedRegURL 359 Type: String 360 Default: Null 361 Use: A URL pointing to a document containing serialized 362 registrations that should be processed when the DA or 363 SA server starts up. 365 2.1.5 Network Configuration Properties 367 The properties in this section allow various network configuration 368 properties to be set. 370 net.slp.multicastTTL 371 Type: Positive integer less than or equal to 255 372 Default: 255 373 Use: Multicast TTL. 375 net.slp.DAActiveDiscoveryInterval 376 Type: Unsigned 16 bit integer 377 Default: 900 378 Use: The number of seconds between DA active discovery 379 queries. The queries may be done periodically or in 380 response to a particular SLP operation. This property 381 corresponds to the protocol specification parameter 382 CONFIG_DA_FIND [8]. If the property is set to zero, 383 active discovery is turned off. 385 net.slp.passiveDADetection 386 Type: Boolean 387 Default: TRUE 388 Use: If FALSE, ignore any unsolicited DAAdverts that are 389 received. 391 net.slp.multicastMaximumWait 392 Type: Positive 32 bit integer. 393 Default 15000 ms (15 sec.) 394 Use: Maximum number of milliseconds to multicast a request 395 before giving up. This property corresponds to the 396 CONFIG_MC_MAX parameter in the protocol specification 397 [8]. 399 net.slp.multicastTimeouts 400 Type: List of positive 32 bit integer 401 Default: 3000,3000,3000,3000,3000 402 Use: The timeouts, in milliseconds, to use for multiple 403 attempts at multicast for UA requests. Each value 404 specifies the time to wait before sending the next 405 request, or until nothing new has been learned from 406 two successive requests. The sum should equal 407 net.slp.multicastMaximumWait. 409 net.slp.DADiscoveryTimeouts 410 Type: List of positive 32 bit integer 411 Default: 2000,2000,2000,2000,3000,4000 412 Use: The timeouts, in milliseconds, to use for multiple 413 attempts at multicast for active DA discovery. Each 414 value specifies the time to wait before sending the 415 next request, or until nothing new has been learned 416 from two successive requests. The sum should equal 417 net.slp.multicastMaximumWait. 419 net.slp.datagramTimeouts 420 Type: List of positive 32 bit integer 421 Default: 3000,3000,3000,3000,3000 422 Use: The timeouts, in milliseconds, to use for 423 retransmitting unicast UDP requests. The nth value 424 gives the time to block waiting for a reply on the 425 nth try to contact the DA. The sum of these values 426 should equal the protocol specification property 427 CONFIG_RETRY_MAX [8]. 429 net.slp.randomWaitBound 430 Type: Positive 32 bit integer 431 Default: 1000 ms (1 sec.) 432 Use: The maximum value in milliseconds for all random wait 433 parameters. This value corresponds to the protocol 434 specification parameters CONFIG_START_WAIT, 435 CONFIG_REG_PASSIVE, and CONFIG_REG_ACTIVE [8]. 437 net.slp.MTU 438 Type: Positive 16 bit integer 439 Default: 1500 440 Use: Maximum datagram size for an SLP agent to send, and 441 includes IP and UDP or TCP headers. 443 net.slp.interfaces 444 Type: List of Address 445 Default: System Default 446 Use: List of IP addresses for interfaces on the host on 447 which the DA or SA server should listen on port 427 448 for multicast, unicast UDP, and TCP messages. 450 2.1.6 SA Configuration 452 The following properties are used for SA or SA server configuration. 454 net.slp.SAAttributes 455 Type: List of Attribute 456 Default: "(service-type=" ")" 457 Use: A list of attribute definitions advertised by the SA 458 in an SAAdvert. The list must contain the "service- 459 type" attribute with value equal to all service types 460 advertised by the SA. 462 2.1.7 UA Configuration 464 The following properties are used by the UA for configuration. They 465 can be set dynamically through SLPSetProperty() to alter API library 466 execution. 468 net.slp.locale 469 Type: RFC 1766 Language Tag [7] 470 Default: "en" 471 Use: The default locale used for language tags in SLP 472 messages. This property is also used for SA and DA 473 configuration. 475 net.slp.maxResults 476 Type: Nonnegative 32 bit integer, and -1 477 Default: -1 478 Use: The maximum number of results to report. A value of 479 -1 indicates that all requests should be reported. 481 net.slp.typeHint 482 Type: List of string 483 Default: Null 484 Use: A list of service type names that are used when 485 performing SA discovery 487 net.slp.enableUnicastSARequest 488 Type: Boolean 489 Default: FALSE 490 Use: If TRUE, the UA uses unicast to contact SAs directly 491 rather than multicast, and does not use DAs even if 492 DAs are available 493 2.2 Serialized Registration File 495 The serialized registration file contains a group of proxy 496 registrations that a DA or SA server performs when it starts up. 497 These registrations are primarily for older service programs that do 498 not internally support SLP and cannot be converted, and for portably 499 exchanging registrations between SLP implementations. The character 500 encoding of the registrations is UTF-8. 502 The syntax of the serialized registration file, in ABNF format [6], 503 is as follows: 505 ser-file = reg-list 506 reg-list = reg / reg reg-list 507 reg = creg / ser-reg 508 creg = comment-line ser-reg 509 comment-line = ( "#" / ";" ) 1*allchar newline 510 ser-reg = url-props [attr-list] newline 511 url-props = surl "," lang "," ltime [ "," type ] newline 512 surl = ;The registration's URL. See 513 ; [9] for syntax. 514 lang = 1*8ALPHA [ "-" 1*8ALPHA ] 515 ;RFC 1766 Language Tag see [7]. 516 ltime = 1*5DIGIT 517 ; A positive 16-bit integer 518 ; giving the lifetime 519 ; of the registration. 520 type = ; The service type name, see [8] 521 ; and [9] for syntax. 522 attr-list = attr-def / attr-def attr-list 523 attr-def = ( attr / keyword ) newline 524 keyword = attr-id 525 attr = attr-id "=" attr-val-list 526 attr-id = ;Attribute id, see [8] for syntax. 527 attr-val-list = attr-val / attr-val "," attr-val-list 528 attr-val = ;Attribute value, see [8] for syntax. 529 allchar = char / WSP 530 char = DIGIT / ALPHA / other 531 other = %x21-%x2f / %x3a-%x40 / 532 %x5b-%x60 / %7b-%7e 533 ; All printable, nonwhitespace US-ASCII 534 ; characters. 535 newline = CR / ( CRLF ) 537 The syntax for attribute tags and attribute value lists is specified 538 in [8]. DAs and SA servers that process serialized registrations 539 must handle them exactly as if they were registered by an SA. In the 540 url-props production, the type token is optional. If the type token 541 is absent, the URL's scheme is used as the type. If the maximum 542 lifetime is specified (65535 sec.), the advertisement is taken to be 543 permanent, and is continually refreshed by the DA or SA server until 544 it exits. The API library should respect any advertised DA minimum 545 refresh interval values, and otherwise, should only register after 546 half or more of the lifetime has expired. If the lifetime is other 547 than the maximum, the advertisement times out after the lifetime 548 expires. Advertisements are registered in the scopes with which the 549 DA or SA server is configured. 551 2.3 Processing Serialized Registration and Configuration Files 553 Implementations are encouraged to make processing of configuration 554 and serialized registration files as transparent as possible to 555 clients of the API. Agents processing the configuration file and the 556 serialized registration file must log any errors using the platform 557 specific error reporting mechanism. An agent must not fail if a file 558 format error occurs. 560 For configuration files, errors must be caught at the latest when 561 the relevant configuration item is used. Errors may be caught at the 562 earliest when the configuration file is loaded into the executing 563 agent. The default value must be substituted when an error is 564 caught. Configuration file loading must complete prior to the 565 initiation of the first networking connection. 567 For serialized registration files, errors must be caught and 568 reported when the file is loaded, and the offending registration 569 must be rejected. Serialized registration must be complete before 570 the DA or SA server accepts the first network request. 572 3.0 The API 574 The C language binding presents a minimal overhead implementation 575 mapping directly into the protocol. To conform with standard C 576 practice, all character strings passed to and returned through the 577 API are null terminated, even though the SLP protocol does not use 578 null terminated strings. Strings passed as parameters are in the 579 multi-byte UTF-8 encoding but they must be passed as a type char*, a 580 null terminated array of bytes. In the common case of US-ASCII, the 581 usual one byte per character C strings work because the US-ASCII 582 encoding is a subset of the UTF-8 encoding. 584 Unless otherwise noted, a NULL parameter value can be used to denote 585 "no value." Some parameters may have restrictions. If any parameter 586 fails to satisfy the restrictions on its value, the operation 587 returns a PARAMETER_BAD error. 589 An exception is scope lists in the UA API. A NULL or empty string 590 for a scope list parameter indicates "default the list". Section 4.3 591 describes how to construct the default list. 593 3.1 Constant Types 595 3.1.1 URL Lifetimes 597 Synopsis 599 typedef enum { 600 SLP_LIFETIME_DEFAULT = 10800, 601 SLP_LIFETIME_MAXIMUM = 65535 602 } SLPURLLifetime; 603 Description 605 The SLPURLLifetime enum type contains frequently used URL lifetime 606 values, in seconds. SLP_LIFETIME_DEFAULT is 3 hours, while 607 SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the 608 maximum size of the lifetime field in SLP messages. A registration 609 made with SLP_LIFETIME_MAXIMUM causes the service advertisement to 610 be automatically re-registered. 612 3.2 Error Codes 614 Synopsis 616 typedef enum { 617 SLP_LAST_CALL = 1, 618 SLP_OK = 0, 619 SLP_LANGUAGE_NOT_SUPPORTED = -1, 620 SLP_PARSE_ERROR = -2, 621 SLP_INVALID_REGISTRATION = -3, 622 SLP_SCOPE_NOT_SUPPORTED = -4, 623 SLP_REFRESH_REJECTED = -15, 624 SLP_NOT_IMPLEMENTED = -17, 625 SLP_BUFFER_OVERFLOW = -18, 626 SLP_NETWORK_TIMED_OUT = -19, 627 SLP_NETWORK_INIT_FAILED = -20, 628 SLP_MEMORY_ALLOC_FAILED = -21, 629 SLP_PARAMETER_BAD = -22, 630 SLP_NETWORK_ERROR = -23, 631 SLP_INTERNAL_SYSTEM_ERROR = -24, 632 SLP_HANDLE_IN_USE = -25, 633 SLP_TYPE_ERROR = -26 634 } SLPError ; 636 Description 638 The SLPError enum contains error codes that are returned from API 639 functions or passed as error parameters to callback functions. 641 The SLP protocol errors OPTION_NOT_UNDERSTOOD, 642 VERSION_NOT_SUPPORTED, INTERNAL_ERROR, MSG_NOT_SUPPORTED, 643 AUTHENTICATON_UNKNOWN, and DA_BUSY_NOW should be handled internally 644 and not surfaced to clients through the API. 646 The error codes SLP_OK, SLP_LANGAUGE_NOT_UNDERSTOOD, 647 SLP_PARSE_ERROR, SLP_SCOPE_NOT_SUPPORTED, and SLP_REFRESH_REJECTED 648 correspond directly to the protocol error codes as described in [8]. 649 In addition, SLP_PARSE_ERROR may be returned by the API library if 650 the library itself detects any syntactic errors. 652 The remaining error codes indicate the following conditions: 654 SLP_LAST_CALL 656 The SLP_LAST_CALL code is passed to callback functions for 657 both synchronous and asynchronous calls when the API library 658 has no more data for them and therefore no further calls will 659 be made to the callback on the currently outstanding 660 operation. The callback can use this to signal the main body 661 of the client code that no more data will be forthcoming on 662 the operation, so that the main body of the client code can 663 break out of data collection loops. The other callback 664 parameters are all NULL. If an SLP request results in no 665 return values, then only one call is made, with the error 666 parameter set to SLP_LAST_CALL. 668 SLP_NETWORK_INIT_FAILED 670 The network failed to initialize properly. 672 SLP_NETWORK_TIMED_OUT 674 No reply can be obtained in the time specified by the 675 configured timeout interval for a unicast request. 677 SLP_NETWORK_ERROR 679 Networking failed during normal operation. 681 SLP_BUFFER_OVERFLOW 683 An outgoing request overflowed the maximum network MTU size. 685 SLP_MEMORY_ALLOC_FAILED 687 The API failed to allocate memory. 689 SLP_PARAMETER_BAD 691 A bad parameter was passed into the API. 693 SLP_INTERNAL_SYSTEM_ERROR 695 A basic failure of the API, such as the failure of a system 696 call, occurred. 698 SLP_HANDLE_IN_USE 700 An attempt was made to make an API call on an SLPHandle that 701 already has an outstanding call on it. 703 SLP_TYPE_ERROR 705 If the API supports type checking of registrations against 706 service type templates, this error is returned if the 707 attributes in a registration do not match the service type 708 template for the service. 710 More information on the causes of these errors may be available 711 through the platform specific system error reporting API. 713 3.3 SLPBoolean 714 Synopsis 716 typedef enum { 717 SLP_FALSE = 0, 718 SLP_TRUE = 1 719 } SLPBoolean; 721 Description 723 The SLPBoolean enum is used as a Boolean flag. 725 3.4 Structure Types 727 3.4.1 SLPSrvURL 729 Synopsis 731 typedef struct srvurl { 732 char *s_pcSrvType; 733 char *s_pcHost; 734 int s_iPort; 735 char *s_pcNetFamily; 736 char *s_pcSrvPart; 737 } SLPSrvURL; 739 Description 741 The SLPSrvURL structure is filled in by the SLPParseSrvURL() 742 function when a service URL string is parsed. The fields correspond 743 to different parts of the URL. Note that the structure is in 744 conformance with the standard Berkeley sockets struct servent, with 745 the exception that the pointer to an array of characters for aliases 746 (s_aliases field) is replaced by the pointer to host name (s_pcHost 747 field). 749 s_pcSrvType 750 A pointer to a character string containing the service type 751 name, including naming authority. The service type name 752 includes the "service:" if the URL is of the service: scheme 753 [8]. 755 s_pcHost 756 A pointer to a character string containing the host 757 identification information. 759 s_iPort 760 The port number, or zero if none. The port is only available 761 if the transport is IP. 763 s_pcNetFamily 764 A pointer to a character string containing the network address 765 family identifier. Possible values are "ipx" for the IPX 766 family, "at" for the Appletalk family, and "" (i.e. the empty 767 string) for the IP address family. 769 s_pcSrvPart 770 The remainder of the URL, after the host identification. 772 The host and port should be sufficient to open a socket to the 773 machine hosting the service, and the remainder of the URL should 774 allow further differentiation of the service. 776 3.4.2 SLPHandle 778 Synopsis 780 typedef void* SLPHandle; 782 Description 784 The SLPHandle type is returned by SLPOpen() and is a parameter to 785 all SLP functions. It serves as a handle for all resources allocated 786 on behalf of the process by the SLP library. The type is opaque, 787 since the exact nature differs depending on the implementation. 789 3.5 Callback Types 791 The callback functions report the results of an SLP protocol 792 operation. In addition to parameters for reporting the results of 793 the operation, each callback parameter list contains an error code 794 parameter and a cookie parameter. The error code parameter reports 795 the error status of the ongoing (for asynchronous) or completed (for 796 synchronous) operation. The cookie parameter allows the client code 797 starting the operation to pass information down to the callback 798 through the API function without using global variables. If the 799 cookie is not set when the API function is called, the parameter is 800 NULL. 802 The callback returns an SLPBoolean to indicate whether the API 803 library should continue processing the operation. If the value 804 returned from the callback is SLP_TRUE, asynchronous operations are 805 terminated, synchronous operations ignore the return, since the 806 operation is already complete. 808 Section 4.1 contains more detail on callback processing. 810 3.5.1 SLPRegReport 812 Synopsis 814 typedef void SLPRegReport(SLPHandle hSLP, 815 SLPError errCode, 816 void *pvCookie); 818 Description 820 The SLPRegReport callback type is the type of the callback function 821 to the SLPReg() and SLPDereg() functions. 823 Parameters 825 hSLP 826 The SLPHandle used to initiate the operation. 828 errCode 829 The error code. 831 pvCookie 832 The cookie. 834 3.5.2 SLPSrvTypeCallback 836 Synopsis 838 typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP, 839 const char* pcSrvTypes, 840 SLPError errCode, 841 void *pvCookie); 843 Description 845 The SLPSrvTypeCallback callback type is the type of the callback 846 function parameter to the SLPFindSrvTypes() function. 848 Parameters 850 hSLP 851 The SLPHandle used to initiate the operation. 853 pcSrvTypes 854 A character buffer containing a comma separated, null 855 terminated list of service types. 857 errCode 858 The error code. 860 pvCookie 861 The cookie. 862 Returns 864 The client code should return SLP_TRUE if more data is desired, 865 otherwise SLP_FALSE. 867 3.5.3 SLPSrvURLCallback 869 Synopsis 871 typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP, 872 const char* pcSrvURL, 873 unsigned short sLifetime, 874 SLPError errCode, 875 void *pvCookie); 877 Description 879 The SLPSrvURLCallback callback type is the type of the callback 880 function parameter to the SLPFindSrvs() function. 882 Parameters 884 hSLP 885 The SLPHandle used to initiate the operation. 887 pcSrvURL 888 A character buffer containing the returned service URL. 890 sLifetime 891 An unsigned short giving the life time of the service 892 advertisement, in seconds. The value must be an unsigned 893 integer less than or equal to SLP_LIFETIME_MAXIMUM. 895 errCode 896 The error code. 898 pvCookie 899 The cookie. 901 Returns 903 The client code should return SLP_TRUE if more data is desired, 904 otherwise SLP_FALSE. 906 3.5.4 SLPAttrCallback 908 Synopsis 910 typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP, 911 const char* pcAttrList, 912 SLPError errCode, 913 void *pvCookie); 915 Description 917 The SLPAttrCallback type is the callback type of the callback 918 function parameter to SLPFindAttrs() function. 920 Parameters 922 hSLP 923 The SLPHandle used to initiate the operation. 925 pcAttrList 926 A character buffer containing a comma separated, null 927 terminated list of attribute id/value assignments, in SLP wire 928 format, see [8] for details. 930 errCode 931 The error code. 933 pvCookie 934 The cookie. 936 Returns 937 The client code should return SLP_TRUE if more data is desired, 938 otherwise SLP_FALSE. 940 3.6 Opening and Closing an SLPHandle 942 3.6.1 SLPOpen 944 Synopsis 946 SLPError SLPOpen(const char *pcLang, 947 SLPBoolean isAsync, 948 SLPHandle *phSLP); 950 Description 952 Returns a SLPHandle handle in the phSLP parameter for the language 953 locale passed in as the pcLang parameter. If the isAsync parameter 954 is TRUE, operations are performed asynchronously. The handle 955 encapsulates the language locale for SLP requests issued through the 956 handle, and any other resources required by the implementation. 957 However, SLP properties are not encapsulated by the handle; they are 958 global. The return value of the function is an SLPError code 959 indicating the status of the operation. 961 An SLPHandle can only be used for one SLP API operation at a time. 962 If the original operation was started asynchronously, any attempt to 963 start an additional operation on the handle while the original 964 operation is pending results in the return of an SLP_HANDLE_IN_USE 965 error from the API function. If an implementation is unable to 966 support an asynchronous (resp. synchronous) operation, due to memory 967 constraints or lack of threading support, the SLP_NOT_IMPLEMENTED 968 flag must be returned when the isAsync flag is SLP_TRUE (resp. 969 SLP_FALSE). 971 Parameters 973 pcLang 974 The RFC 1766 Language Tag [7] for the natural language locale 975 of requests and registrations issued on the handle. 977 isAsync 978 A SLPBoolean indicating whether the SLPHandle should be opened 979 for asynchronous operation or not. 981 phSLP 982 A pointer to an SLPHandle, in which the open SLPHandle is 983 returned. If an error occurs, the value upon return is NULL. 985 3.6.2 SLPClose 987 Synopsis 989 void SLPClose(SLPHandle hSLP); 991 Description 992 Frees all resources associated with the handle. If the handle was 993 invalid, the function returns silently. Any outstanding synchronous 994 or asynchronous operations are cancelled immediately, so their 995 callback functions will not be called any further. 997 Parameters 999 SLPHandle 1000 A SLPHandle handle returned from a call to SLPOpen(). 1002 3.7 SA API 1004 3.7.1 SLPReg 1006 Synopsis 1008 SLPError SLPReg(SLPHandle hSLP, 1009 const char *pcSrvURL, 1010 const unsigned short usLifetime, 1011 const char *pcSrvType, 1012 const char *pcAttrs 1013 SLPBoolean fresh, 1014 SLPRegReport callback, 1015 void *pvCookie); 1017 Description 1019 Registers the URL in pcSrvURL having the lifetime usLifetime with 1020 the attribute list in pcAttrs. The pcAttrs list is a comma separated 1021 list of attribute assignments in the wire format (including escaping 1022 of reserved characters). The usLifetime parameter must be nonzero 1023 and less than or equal to SLP_LIFETIME_MAXIMUM. The pcSrvType 1024 parameter is a service type name and may be NULL or the empty string 1025 if the URL is a service: URL. The fresh parameter is ignored. The 1026 format for pcAttrs and pcScopeList can be found in [8]. 1027 Registrations and updates take place in the language locale of the 1028 hSLP handle. 1030 The API library is required to perform the operation in all scopes 1031 obtained through configuration. 1033 Parameters 1035 hSLP 1036 The language specific SLPHandle on which to register the 1037 advertisement. 1039 pcSrvURL 1040 The URL to register. May not be NULL or the empty string. This 1041 parameter must be a properly formatted URL [3]; otherwise, the 1042 SLP SrvReg returns a parse error and the callback is called 1043 with the SLP_PARSE_ERROR error code. 1045 usLifetime 1046 An unsigned short giving the life time of the service 1047 advertisement, in seconds. The value must be an unsigned 1048 integer less than or equal to SLP_LIFETIME_MAXIMUM and greater 1049 than zero. 1051 pcSrvType 1052 The service type. If a service: URL is present in pcSrvURL and 1053 this parameter is NULL or an empty string, then the value of 1054 the the service type field in the SrvReg message is obtained 1055 from the service: URL's scheme [8]. 1057 pcAttrs 1058 A comma separated list of attribute assignment expressions for 1059 the attributes of the advertisement. See [8] for the format. 1060 Use NULL or the empty string for no attributes. 1062 fresh 1063 Ignored. 1065 callback 1066 A callback to report the operation completion status. 1068 pvCookie 1069 Memory passed to the callback code from the client. May be 1070 NULL. 1072 Returns 1074 One of the SLPError codes is returned indicating the status of 1075 starting the operation. 1077 3.7.2 SLPDereg 1079 Synopsis 1081 SLPError SLPDereg(SLPHandle hSLP, 1082 const char *pcURL, 1083 SLPRegReport callback, 1084 void *pvCookie); 1086 Description 1088 Deregisters the advertisement for URL pcURL in all scopes where the 1089 service is registered and all language locales. The deregistration 1090 is not just confined to the locale of the SLPHandle, it is in all 1091 locales. The API library is required to perform the operation in all 1092 scopes obtained through configuration. 1094 Parameters 1096 hSLP 1097 The language specific SLPHandle to use for deregistering. 1099 pcURL 1100 The URL to deregister. May not be the empty string. This 1101 parameter must be a properly formatted URL [3]; otherwise, the 1102 SLP SrvDeReg returns a parse error and the callback is called 1103 with the SLP_PARSE_ERROR error code. 1105 callback 1106 A callback to report the operation completion status. 1108 pvCookie 1109 Memory passed to the callback code from the client. May be 1110 NULL. 1111 Returns 1113 One of the SLPError codes is returned indicating the status of 1114 starting the operation. 1116 3.7.3 SLPFindSrvTypes 1118 Synopsis 1120 SLPError SLPFindSrvTypes(SLPHandle hSLP, 1121 const char *pcNamingAuthority, 1122 const char *pcScopeList, 1123 SLPSrvTypeCallback callback, 1124 void *pvCookie); 1126 Description 1128 The SLPFindSrvType() function issues an SLP service type request for 1129 service types in the scopes indicated by the pcScopeList. The 1130 results are returned through the callback parameter. The service 1131 types are independent of language locale, but only for services 1132 registered in one of scopes and for the indicated naming authority. 1133 If the naming authority is "*", then results are returned for all 1134 naming authorities. If the naming authority is NULL or the empty 1135 string, then the default naming authority, IANA, is used. "IANA" is 1136 not a valid naming authority name, and it is a PARAMETER_BAD error 1137 to include it explicitly. 1139 The service type names are returned with the naming authority 1140 intact. If the naming authority is the default (i.e. empty string) 1141 then it is omitted, as is the separating ".". Service type names 1142 from URLs of the service: scheme are returned with the "service:" 1143 prefix intact [8]. See [9] for more information on the syntax of 1144 service type names. 1146 Parameters 1148 hSLP 1149 The SLPHandle on which to search for types. 1151 pcNamingAuthority 1152 The naming authority to search. Use "*" for all naming 1153 authorities and NULL or the empty string for the default 1154 naming authority. 1156 pcScopeList 1157 The comma separated list of scope names to search for service 1158 types. Use NULL or the empty string for the default scope 1159 list. 1161 callback 1162 A callback function through which the results of the operation 1163 are reported. 1165 pvCookie 1166 Memory passed to the callback code from the client. May be 1167 NULL. 1169 Returns 1171 One of the SLPError codes is returned indicating the status of 1172 starting the operation. 1174 3.7.4 SLPFindSrvs 1176 Synopsis 1178 SLPError SLPFindSrvs(SLPHandle hSLP, 1179 const char *pcServiceType, 1180 const char *pcScopeList, 1181 const char *pcSearchFilter, 1182 SLPSrvURLCallback callback, 1183 void *pvCookie); 1185 Description 1187 Issue the query for services on the locale-specific SLPHandle and 1188 return the results through the callback. The parameters determine 1189 the results. 1191 Parameters 1193 hSLP 1194 The locale-specific SLPHandle on which to search for services. 1196 pcServiceType 1197 The service type name, including naming authority if any, for 1198 the request, such as can be discovered using SLPSrvTypes(). 1199 May not be NULL or the empty string. 1201 pcScopeList 1202 The comma separated list of scope names. Use NULL or the empty 1203 string for the default scope list. 1205 pcSearchFilter 1206 A query formulated of attribute pattern matching expressions 1207 in the form of an LDAPv3 Search Filter, see [5]. If this 1208 filter is NULL or the empty string, all services of the 1209 requested type in the specified scopes are returned. The 1210 search filter should be a simple search filter as defined in 1211 [8]. 1213 callback 1214 A callback function through which the results of the operation 1215 are reported. 1217 pvCookie 1218 Memory passed to the callback code from the client. May be 1219 NULL. 1221 Returns 1223 One of the SLPError codes is returned indicating the status of 1224 starting the operation. 1226 3.7.5 SLPFindAttrs 1228 Synopsis 1230 SLPError SLPFindAttrs(SLPHandle hSLP, 1231 const char *pcURL, 1232 const char *pcScopeList, 1233 const char *pcAttrIds, 1234 SLPAttrCallback callback, 1235 void *pvCookie); 1236 Description 1238 This function returns service attributes matching the attribute ids 1239 for the indicated URL. The attribute information returned is for the 1240 matching advertisement in the locale of the SLPHandle. 1241 The result is filtered with an SLP attribute request filter string 1242 parameter, pcAttrIds, the syntax of which is described in [8]. If 1243 the filter string is NULL or the empty string, all attributes are 1244 returned. 1246 Parameters 1248 hSLP 1249 The language specific SLPHandle on which to search for 1250 attributes. 1252 pcURL 1253 The URL. May not be NULL or the empty string. This parameter 1254 must be a properly formatted URL [3]; otherwise, the SLP 1255 AttrRqst returns a parse error and the callback is called with 1256 the SLP_PARSE_ERROR error code. 1258 pcScopeList 1259 The comma separated list of scope names. Use NULL or the empty 1260 string for the default scope list. 1262 pcAttrIds 1263 The filter string indicating which attribute values to return. 1264 Use NULL or the empty string to indicate all values. See [8] 1265 for the exact format of the filter string. 1267 callback 1268 A callback function through which the results of the operation 1269 are reported. 1271 pvCookie 1272 Memory passed to the callback code from the client. May be 1273 NULL. 1275 Returns 1277 One of the SLPError codes is returned indicating the status of 1278 starting the operation. 1280 3.8 Miscellaneous Functions 1282 3.8.1 SLPGetRefreshInterval 1284 Synopsis 1286 unsigned short SLPGetRefreshInterval(); 1288 Description 1290 Returns the maximum across all DAs of the min-refresh-interval 1291 attribute. This value satisfies the advertised refresh interval 1292 bounds for all DAs, and, if used by the SA as the minimum service 1293 advertisement lifetime, assures that no refresh registration will be 1294 rejected. If no DA advertises a min-refresh-interval attribute, a 1295 value of 0 is returned. 1297 Returns 1299 If no error, the maximum refresh interval value allowed by all DAs 1300 (a positive integer). If no DA advertises a min-refresh-interval 1301 attribute, returns 0. If an error occurs, returns an SLP error code. 1303 3.8.2 SLPFindScopes 1305 Synopsis 1307 SLPError SLPFindScopes(SLPHandle hSLP, 1308 char **ppcScopeList); 1310 Description 1312 Sets ppcScopeList parameter to a pointer to a comma separated list 1313 including all available scope values. See Section 4.3 for a 1314 description of how the list is determined. If there is any order to 1315 the scopes, preferred scopes are listed before less desirable 1316 scopes. There is always at least one name in the list, the default 1317 scope, "DEFAULT". 1319 Parameters 1321 hSLP 1322 The SLPHandle on which to search for scopes. 1324 ppcScopeList 1325 On return, contains a pointer to a null terminated string with 1326 the comma-separated list of scopes. The memory should be freed 1327 by calling SLPFree(). 1329 Returns 1331 If no error occurs, returns SLP_OK, otherwise, the appropriate error 1332 code. 1334 3.8.3 SLPParseSrvURL 1336 Synopsis 1338 SLPError SLPParseSrvURL(char *pcSrvURL 1339 SLPSrvURL** ppSrvURL); 1341 Description 1343 The URL passed in as the argument is parsed into a SLPSrvURL 1344 structure and is return in the ppSrvURL pointer. If a parse error 1345 occurs, returns SLP_PARSE_ERROR as the value of the function. The 1346 input buffer pcSrvURL may be destructively modified during the parse 1347 and used to fill in the fields of the return structure. The 1348 structure returned in ppSrvURL should be freed with SLPFree(). 1350 If the URL has no service part, the s_pcSrvPart string is the empty 1351 string, "", i.e. not NULL. If pcSrvURL is not a service: URL, then 1352 the s_pcSrvType field in the returned data structure is the URL's 1353 scheme, which might not be the same as the service type under which 1354 the URL was registered. If the transport is IP, the s_pcTransport 1355 field is the empty string. If the transport is not IP or there is no 1356 port number, the s_iPort field is zero. 1358 Parameters 1360 pcSrvURL 1361 The null terminated URL string to parse. It may be 1362 destructively modified to produce the output structure. This 1363 parameter must be a properly formatted URL; otherwise, 1364 function returns the SLP_PARSE_ERROR error code. 1366 ppSrvURL 1367 On return, contains a pointer to the SLPSrvURL structure with 1368 the parsed URL, or NULL if the parse failed. The memory should 1369 be freed by a call to SLPFree() when no longer needed. 1371 Returns 1373 If no error occurs, the return value is SLP_OK. Otherwise, the 1374 appropriate error code is returned. 1376 3.8.4 SLPParseAttrs 1378 Synopsis 1380 SLPError SLPParseAttrs(const char *pcAttrList, 1381 const char *pcAttrId, 1382 char **ppcAttrVal); 1383 Description 1385 Parses an attribute list to obtain the attribute value of a specified 1386 attribute ID. SLP_PARSE_ERROR is returned if a value for pcAttrId can 1387 not be found. The attribute value string returned in ppcAttrVal must 1388 be freed with SLPFree(). 1390 Parameters 1392 pcAttrList 1393 A comma separated list of attribute assignment expressions. See 1394 [8] for the format. 1395 pcAttrId 1396 The string indicating which attribute value to return. May not 1397 be NULL or the empty string. 1398 ppcAttrVal 1399 Upon return, a pointer to the buffer containing the attribute 1400 value. The returned memory should be freed by a call to 1401 SLPFree() when no longer needed. 1403 Returns 1405 If no error occurs, the return value is SLP_OK. Otherwise, the 1406 appropriate error code is returned. If this function is not 1407 implemented, the library should return SLP_NOT_IMPLEMENTED. If a 1408 parse error occurs, the library should return SLP_PARSE_ERROR. 1410 3.8.5 SLPEscape 1412 Synopsis 1414 SLPError SLPEscape(const char *pcInbuf, 1415 char **ppcOutBuf, 1416 SLPBoolean isTag); 1418 Description 1420 Process the input string in pcInbuf and escape any SLP reserved 1421 characters. If the isTag parameter is SLPTrue, then look for bad tag 1422 characters and signal an error if any are found by returning the 1423 SLP_PARSE_ERROR code. The results are put into a buffer allocated by 1424 the API library and returned in the ppcOutBuf parameter. This buffer 1425 should be deallocated using SLPFree() when the memory is no longer 1426 needed. 1428 Parameters 1430 pcInbuf 1431 Pointer to he input buffer to process for escape characters. 1433 ppcOutBuf 1434 On output, contains a pointer to a copy of the input buffer 1435 with the SLP reserved characters escaped. Must be freed using 1436 SLPFree()when the memory is no longer needed. 1438 isTag 1439 When true, the input buffer is checked for bad tag characters. 1441 Returns 1442 Return SLP_PARSE_ERROR if any characters are bad tag characters and 1443 the isTag flag is true, otherwise SLP_OK, or the appropriate error 1444 code if another error occurs. 1446 3.8.6 SLPUnescape 1448 Synopsis 1450 SLPError SLPUnescape(const char *pcInbuf, 1451 char **ppcOutBuf, 1452 SLPBoolean isTag); 1454 Description 1456 Process the input string in pcInbuf and unescape any SLP reserved 1457 characters. If the isTag parameter is SLPTrue, then look for bad tag 1458 characters and signal an error if any are found with the 1459 SLP_PARSE_ERROR code. No transformation is performed if the input 1460 string is an SLP opaque. The results are put into a buffer allocated 1461 by the API library and returned in the ppcOutBuf parameter. This 1462 buffer should be deallocated using SLPFree() when the memory is no 1463 longer needed. 1465 Parameters 1467 pcInbuf 1468 Pointer to he input buffer to process for escape characters. 1470 ppcOutBuf 1471 On output, contains a pointer to a copy of the input buffer 1472 with the SLP reserved characters unescaped. Must be freed 1473 using SLPFree()when the memory is no longer needed. 1475 isTag 1476 When true, the input buffer is checked for bad tag characters. 1478 Returns 1480 Return SLP_PARSE_ERROR if any characters are bad tag characters and 1481 the isTag flag is true, otherwise SLP_OK, or the appropriate error 1482 code if another error occurs. 1484 3.8.7 SLPFree 1486 Synopsis 1488 void SLPFree(void* pvMem); 1490 Description 1492 Frees memory returned from SLPParseSrvURL(), 1493 SLPFindScopes(),SLPEscape(), SLPUnescape(), and SLPGetProperty(). 1495 Parameters 1497 pvMem 1498 A pointer to the storage allocated by the 1499 SLPParseSrvURL(),SLPEscape(), SLPUnescape(), or 1500 SLPFindScopes() function. Ignored if NULL. 1502 3.8.8 SLPGetProperty 1504 Synopsis 1506 SLPError SLPGetProperty(const char *pcPropertyName, 1507 char **ppcPropertyValue); 1509 Description 1511 Upon return, the ppcPropertyValue parameter is set to a pointer to 1512 the property value string corresponding to pcPropertyName, or NULL 1513 if the pcPropertyName string does not name a valid SLP property. The 1514 ppcPropertyValue buffer should be deallocated using SLPFree() when 1515 the memory is no longer needed. 1517 Parameters 1519 pcPropertyName 1520 Null terminated string with the property name, from Section 1521 2.1. 1523 ppcPropertyValue 1524 On return, contains a pointer to a string with the property 1525 value, or NULL if the pcPropertyName parameter does not name a 1526 property. 1527 Returns 1529 Returns one of the following status codes: SLP_OK, 1530 SLP_MEMORY_ALLOC_FAILED, SLP_NOT_IMPLEMENTED, or SLP_PARAMETER_BAD. 1531 The latter is returned if the pcPropertyName parameter does not name 1532 a valid SLP property. 1534 3.8.9 SLPSetProperty 1536 Synopsis 1538 SLPError SLPSetProperty(const char *pcPropertyName, 1539 const char *pcPropertyValue); 1541 Description 1543 Sets the value of the SLP property to the new value. The pcValue 1544 parameter should be the property value as a string. 1546 Parameters 1548 pcPropertyName 1549 Null terminated string with the property name, from Section 1550 2.1. 1552 pcPropertyValue 1553 Null terminated string with the property value. Use NULL or 1554 the empty string to indicate that the property should be 1555 unset, and thus return to default. 1557 Returns 1559 Returns one of the following status codes: SLP_OK, 1560 SLP_MEMORY_ALLOC_FAILED, SLP_NOT_IMPLEMENTED, or 1561 SLP_PARAMETER_BAD. The latter is returned if the 1562 pcPropertyName parameter does not name a valid SLP property. 1564 3.8.10 SLPGetExtensionInterface 1566 Synopsis 1568 SLPError SLPGetExtensionInterface(SLPHandle hSLP, 1569 const char *pcExtName, 1570 void **ppExtInterface); 1572 Description 1574 Called with an initialized SLPHandle and the name of an SLP 1575 extension. On return, a pointer to the extension interface is in the 1576 ppExtInterface parameter, or NULL if there is no such extension. 1577 Exactly how the code for the extension is located, the exact format 1578 of the interface structure implementing access to the extension, how 1579 the interface code is made available (i.e.dynamically linked v.s. 1580 statically linked), and how names of extensions are formatted are 1581 implementation dependent issues. 1583 Parameters 1585 hSLP 1586 The language specific SLPHandle to use for locating the 1587 extension interface. 1589 pcExtName 1590 The name of the extention to return. 1592 ppExtInterface 1593 On return, contains a pointer to a structure implementing the 1594 interface. 1596 Returns 1598 If no error occurs, the return value is SLP_OK. Otherwise, the 1599 appropriate error code is returned. If no extension is available 1600 corresponding to pcExtName, the return value is SLP_NOT_IMPLEMENTED 1601 and the ppExtInterface parameter is NULL. 1603 3.8.11 SLPFreeExtensionInterface 1605 Synopsis 1607 SLPError SLPFreeExtensionInterface(void **ppExtInterface); 1608 Description 1610 Free up memory and code associated with the interface accessed 1611 through ppExtInterface. Upon return, ppExtInterface is NULL and 1612 the memory for the interface is freed. 1614 Parameters 1616 ppExtInterface 1617 A valid interface implementation obtained through 1618 SLPGetExtInterface() 1620 Return 1622 If no error occurs, the return value is SLP_OK. Otherwise, the 1623 appropriate error code is returned. 1625 4.0 Implementation Considerations 1627 This section discusses a number of implementation considerations. 1629 4.1 Callback Semantics 1631 There will always be at least one callback for every API operation: 1632 a callback with the error code set to SLP_LAST_CALL indicating that 1633 the request has completed. There may be more callbacks in certain if 1634 a result is returned. Any callback in which the error code is not 1635 set to SLP_LAST_CALL is a return report. If there are no results to 1636 report, the callback with SLP_LAST_CALL set is the only callback. 1638 For the SA API, SLPSrvReg() and SLPSrvDereg() callbacks are only 1639 ever called once with a return report. If the SA API implementation 1640 performs DA forwarding directly, then it must wait until all DA 1641 replies are back before calling the callback. If the SA API 1642 implementation registers with an SA server, the SA server replies 1643 with a single SrvAck, the contents of which are reported through the 1644 callback. 1646 For the UA API, only one callback containing a return report is ever 1647 made if a DA is in use for SLPFindSrvTypes(). If the UA multicasts a 1648 request or unicasts to multiple SAs, multiple calls to a callback 1649 with return reports may result for SLPFindSrvTypes() if multiple 1650 replies are received. The UA may also collate replies from multiple 1651 SAs and present them through a single callback. Only one return 1652 report callback invocation ever occurs for SLPFindAttrs(), and 1653 multiple callback reports are possible for SLPFindSrvs() regardless 1654 of how the request was transmitted if multiple URLs are received in 1655 the reply. 1657 The callback function is called whenever the API library has results 1658 to report. The callback code is required to check the error code 1659 parameter before looking at the other parameters. If the error code 1660 is not SLP_OK, the other parameters may be invalid. The API library 1661 may terminate any outstanding operation on which an error occurs. 1662 The callback code can similarly indicate that the operation should 1663 be terminated by passing back SLP_FALSE. 1665 Callback functions are not permitted to recursively call into the 1666 API on the same SLPHandle. If an attempt is made to recursively call 1667 into the API, the API function returns SLP_HANDLE_IN_USE. 1668 Prohibiting recursive callbacks on the same handle simplifies 1669 implementation of thread safe code, since locks held on the handle 1670 will not be in place during a second outcall on the handle. Handle 1671 creation should be fairly lightweight so a client program can easily 1672 support multiple outstanding calls. 1674 The total number of results received can be controlled by setting 1675 the net.slp.maxResults parameter. Note that this parameter controls 1676 the number of results received, not the number of return messages. 1677 In the case of a multicast SrvRqst, for example, the number of 1678 return messages may be less than the number of results, since one 1679 message may contain multiple results. 1681 There are five reasons why a call can terminate: 1683 DA reply received 1685 A reply from a DA has been received and therefore nothing more 1686 is expected, or the request timed out. 1688 Unicast SA messages received 1690 All messages were received in reply to a unicast request to 1691 one or several SAs, or one or more of the requests timed out. 1693 Multicast terminated 1695 The multicast convergence time has elapsed and the API library 1696 multicast code is giving up. 1698 Multicast null results 1700 Nothing new has been received during multicast for a while and 1701 the API library multicast code is returning the existing 1702 replies, if any. 1704 Maximum results 1706 The user has set the net.slp.maxResults property and that 1707 number of results has been collected and returned 1709 4.2 Asynchronous Semantics 1711 If a handle parameter to an API function is opened asynchronously, 1712 API function calls on the handle check the other parameters, open 1713 the appropriate operation and return immediately. If the handle 1714 parameter was opened synchronously, the API function call blocks 1715 until all results are processed, and returns only after the callback 1716 function has been called with the callback error code set to 1717 SLP_LAST_CALL. If an error occurs in the process of starting the SLP 1718 operation, an error code is returned from the API function. Errors 1719 that occur as a result of the SLP operation are reported to the 1720 callback, and are not returned from the API function. 1722 If asynchronous semantics are supported, the API library is required 1723 to be thread-safe. The API must be re-entrant in order to avoid 1724 interference between callbacks. 1726 4.3 Scope and DA Configuration and Discovery 1728 The API must conform to the scope and DA configuration rules 1729 described in Section 8 of [8]. Preconfigured scopes and DAs, whether 1730 through static configuration or DHCP configuration, must be 1731 available via the configuration properties net.slp.configuredScopes 1732 and net.slp.configuredDAAddresses. 1734 Functions in the UA API have a scope parameter that determines the 1735 scopes used in UA requests. If that parameter is not NULL or the 1736 empty string, then the scopes in that parameter are used for the 1737 request. If that parameter is NULL or the empty string, the UA API 1738 library determines the scopes to use in the following fashion. If 1739 net.slp.configuredScopes is set, the listed scopes on 1740 net.slp.configuredScopes are used. If net.slp.configuredScopes is 1741 not set, the UA must use scopes obtained from any configured or 1742 discovered DAs, or scopes discovered through dynamic SA discovery, 1743 exactly as would be the case if the SLPFindScopes() function were 1744 called. 1746 Dynamic scope and DA information is available at any time through 1747 the API functions. Calling SLPSrvRqst() with the service type 1748 parameter set to "service:directory-agent" returns all discoverable 1749 DAs, including any that were configured. Calling SLPFindScopes() 1750 returns all discoverable scopes including any that were configured. 1751 SLPFindScopes() uses the rules outlined in [8] to determine what 1752 sources to consult for scope information. 1754 4.4 Multithreading 1756 Implementations of the API are required to make API calls thread- 1757 safe. Access to data structures shared between threads must be 1758 coordinated to avoid corruption or invalid access. Implementations 1759 should also attempt to maximize the amount of concurrent thread 1760 access to the API library. 1762 4.5 Type Checking for Registrations 1764 Service templates [9] allow SLP registrations to be type checked for 1765 correctness. Implementations of the API may use service type 1766 information for type checking. If a type error occurs, the 1767 registration should terminate with SLP_TYPE_ERROR. 1769 String encoded attribute values do not include explicit type 1770 information. All UA implementations and those SA and DA 1771 implementations that choose to support type checking should use the 1772 type rules described in [9] in order to convert from the string 1773 representation on the wire to an object typed appropriately. 1775 4.6 Refreshing Registrations 1777 SLP advertisements carry an explicit lifetime. After the lifetime 1778 expires, the DA flushes the registration from its cache. In some 1779 cases, an application may want to have the URL continue being 1780 registered for the entire time during which the application is 1781 executing. The API includes provision for clients to indicate 1782 whether they want URLs to be automatically refreshed: SLPReg() is 1783 called with the pLifetime parameter equivalent to 1784 SLP_LIFETIME_MAXIMUM (65535 seconds). Implementations of the SA API 1785 must provide automatic re-registration if a registration is made 1786 with the maximum lifetime. A client using this facility should 1787 explicitly deregister the service URL before exiting, since the API 1788 implementation may not be able to assure that the URL is 1789 deregistered when the application exits, although it times out in 1790 the DA eventually. 1792 4.7 Character Set Encoding 1794 Characters buffer parameters are represented in UTF-8 despite the 1795 defined type of char* or const char*. API functions are required to 1796 handle the full range of multi-byte UTF-8 characters because the SLP 1797 protocol requires it, but the API implementation can represent the 1798 characters internally in any convenient way. On the wire, all 1799 characters are converted to UTF-8 anyway. 1801 Inside URLs, characters that are not allowed by URL syntax [3] must 1802 be escaped according to the URL escape character convention. Strings 1803 that are included in SLP messages may include SLP reserved 1804 characters and can be escaped by clients through convenience 1805 functions provided by the API. The character encoding used in 1806 escapes is UTF-8. 1808 Due to constraints in SLP, no string parameter passed to the API may 1809 exceed 64K bytes in length. An API function that encounters a string 1810 longer than 64K should return SLP_PARSE_ERROR. 1812 4.8 Error Handling 1814 All errors encountered processing SLP messages should be logged, 1815 especially for the SA server and DA. 1817 For the UA API, since no errors are returned for multicast requests, 1818 and only a single DA is ever used at a time, there is only one case 1819 where multiple invocations of a callback could result in one or more 1820 calls to callbacks with the error code set to something other than 1821 SLP_OK: a unicast request to multiple SAs. In all other cases, there 1822 is a single callback invocation in which the error code is set if an 1823 error occurs, in addition to the last call callback. 1825 For the SA client API, a registration or deregistration to one DA 1826 among several may result in an error, but since only a single 1827 callback is ever made reporting return status for the SA API, the 1828 error code is only reported if no SrvAck indicating success was 1829 received. 1831 Since registration with an SA server results in the same error 1832 conditions as with a DA, the SA server is not required to forward a 1833 SrvReg to any DAs if the registration fails. The SA server must 1834 return a SrvAck to the client with the error code properly set. The 1835 SA server is also not required to wait to return the SrvAck to the 1836 SA client until registration with DAs has completed, since any 1837 errors occurring with DAs are likely to be unrelated to the content 1838 of the registration if the registration succeeded with the SA 1839 server. 1841 4.9 Modular Implementations 1843 Subset implementations that do not support the full range of 1844 functionality must support every interface in order to maintain link 1845 compatibility between compliant API implementations and 1846 applications. If a particular operation is not supported, a 1847 NOT_IMPLEMENTED error must be returned. Applications that are 1848 expected to run on a wide variety of platforms should be prepared 1849 for subset API implementations by checking returned error codes. 1851 4.10 Handling Special Service Types 1853 The DA service type, "service:directory-agent", and SA service type, 1854 "service:service-agent", are used internally in the SLP framework to 1855 discover DAs and SAs. The mechanism of DA and SA discovery is not 1856 normally exposed to the API client; however, the client may have 1857 interest in discovering DAs and SAs independently of their role in 1858 discovering other services. For example, a network management 1859 application may want to determine which machines are running SLP 1860 DAs. To facilitate that, API implementations must handle requests to 1861 find services and attributes for these two service types so that API 1862 clients obtain the information they expect. 1864 In particular, if the UA is using a DA, SrvRqst and AttrRqst for 1865 these service types must be multicast and not unicast to the DA, as 1866 is the case for other service types. If the requests are not 1867 multicast, the DA will respond with an empty reply to a request for 1868 the SA service type and with its URL only to a request for the DA 1869 service type. The UA would therefore not obtain a complete picture 1870 of the available DAs and SAs. 1872 4.11 Syntax for String Parameters 1874 Query strings, attribute registration lists, attribute 1875 deregistration lists, scope lists, and attribute selection lists 1876 follow the syntax described in [8] for the appropriate requests. The 1877 API directly reflects the strings passed in from clients into 1878 protocol requests, and directly reflects out strings returned from 1879 protocol replies to clients. As a consequence, clients are 1880 responsible for formatting request strings, including escaping and 1881 converting opaque values to escaped byte encoded strings. Similarly, 1882 on output, clients are required to unescape strings and convert 1883 escaped string encoded opaques to binary. The functions SLPEscape() 1884 and SLPUnescape() can be used for escaping SLP reserved characters, 1885 but perform no opaque processing. 1887 Opaque values consist of a character buffer containing a UTF-8 1888 encoded string, the first characters of which are the nonUTF-8 1889 encoding "\ff". Subsequent characters are the escaped values for the 1890 original bytes in the opaque. The escape convention is relatively 1891 simple. An escape consists of a backslash followed by the two 1892 hexadecimal digits encoding the byte. An example is "\2c" for the 1893 byte 0x2c. Clients handle opaque processing themselves, since the 1894 algorithm is relatively simple and uniform. 1896 4.12 Client Side Syntax Checking 1898 Client side API implementations may do syntax checking of scope 1899 names, naming authority names, and service type names. Since the C 1900 API is designed to be a thin layer over the protocol, some low 1901 memory SA implementations may find extensive syntax checking on the 1902 client side to be burdensome. If syntax checking uncovers an error 1903 in a parameter, the SLP_PARAMETER_BAD error must be returned. If any 1904 parameter is NULL and is required to be nonNULL, SLP_PARAMETER_BAD 1905 is returned. 1907 4.13 SLP Configuration Properties 1909 The SLP configuration properties properties established in the 1910 configuration file are accessible through the SLPGetProperty() and 1911 SLPSetProperty()functions. The SLPSetProperty() function only 1912 modifies properties in the running process, not in the configuration 1913 file. Properties are global to the process, affecting all threads 1914 and all handles created with SLPOpen. Errors are checked when the 1915 property is used and, as with parsing the configuration file, are 1916 logged. Program execution continues without interruption by 1917 substituting the default for the erroneous parameter. With the 1918 exception of net.slp.locale, net.slp.typeHint, and 1919 net.slp.maxResults, clients of the API should rarely be required to 1920 override these properties, since they reflect properties of the SLP 1921 network that are not of concern to individual agents. If changes are 1922 required, system administrators should modify the configuration 1923 file. 1925 4.14 Memory Management 1927 The only API functions returning memory specifically requiring 1928 deallocation on the part of the client are SLPParseSrvURL(), 1929 SLPFindScopes(), SLPEscape(), and SLPUnescape(), and 1930 SLPGetProperty(). This memory should be freed using SLPFree() when 1931 no longer needed. 1933 Memory passed to callbacks from the API library belongs to the 1934 library and MUST NOT be retained or freed by the client code. 1935 Otherwise, crashes are possible. Clients are required to copy data 1936 out of the callback parameters. No other use of the parameter memory 1937 in callback parameters is allowed. 1939 4.15 Multi-homed Hosts 1941 On a multi-homed host, routing may be disabled between interfaces. 1942 The net.slp.interfaces property must only be set if there is no 1943 routing between any of the interfaces or if broadcast is used 1944 instead of multicast. If the net.slp.interfaces is set, the DA (if 1945 any) and SAs on the host should respond to a DA or SA advertisement 1946 request with an IP address or host name on the list. Replies to 1947 requests should be made with service advertisements that are 1948 reachable through the interface on which the request arrived. If 1949 packets are routed between the interfaces, then the DA and SAs must 1950 only advertise on the default interface. 1952 Note that even if unicast packets are not routed between the 1953 interfaces, multicast may be routed through another router. The 1954 danger in listening for multicast on multiple interfaces is that the 1955 DA or SA may receive the same multicast request via more than one 1956 interface. Since the IP address is different on each interface, the 1957 DA or SA cannot identify the request as having already being 1958 answered via the previous responder's list. The requesting agent 1959 will end up getting URLs that refer to the same DA or service but 1960 have different addresses or host names. 1962 4.16 Unicast UA Requests 1964 If the net.slp.enableUnicastSARequest property is TRUE, UAs are 1965 required to use unicast directly to discovered SAs rather than use 1966 multicast or DAs for the request. This allows the UA to receive 1967 errors directly from SAs that it otherwise wouldn't, for example, if 1968 the SA supports simple queries only but the UA issues a complex 1969 query. For SrvRqst and AttrRqst, prior to sending a request, the UA 1970 performs a multicast service request for SAs that advertise the 1971 service type of interest. The request is then unicast to the 1972 returned SAs. For SrvTypeRqst, the UA performs a service requests 1973 for all SAs, and either constructs the returned list of service 1974 types based on the "service-type" attribute definition in the SAs' 1975 attribute lists, or sends a SrvTypeRqst to each SA individually. The 1976 UA may cache the results of returned SAAdverts for some period of 1977 time to avoid having to perform the repeat multicast for SAAdverts. 1978 Unicasting of UA requests should be used with caution, in 1979 particular, it should not be used as a substitute for DAs. Deploying 1980 DAs is likely to result in better network performance and 1981 scalability. 1983 4.17 UA Caching 1985 In general, clients of the UA API should limit repeat queries until 1986 the lifetime of the service advertisement is about to expire. 1987 Because the base protocol and API lack any support for notification 1988 when a new service comes up, however, some applications may want to 1989 poll periodically for new services. Such polling could completely 1990 overwhelm the network with requests, especially if multicast is in 1991 use. 1993 In order to regulate polling, the UA API library should cache the 1994 results of queries and return them when a repeat query arrives 1995 within some short time, say 10 seconds. The lifetime of the cache 1996 entries should be kept short in order to avoid stale information. 1998 5.0 Deprecated Features 2000 The following features were defined in RFC 2614 and have been 2001 deprecated in this update due to changes in the SLP protocol: 2003 1) The property net.slp.securityEnabled is no longer supported. 2004 Security in SLP is now handled through IPSEC. Implementations 2005 should ignore this property if it is in the configuration file. 2006 2) Scope lists have been dropped from the serialized registration 2007 file. Serialized registrations must be made in the configured 2008 scopes for the DA or SA server. Existing files must be edited 2009 to remove the scopes attribute definition, because it will 2010 otherwise be treated as a normal SLP attribute definition 2011 3) The SLPDelAttrs() function is no longer supported. SLP no 2012 longer allows incremental update of service advertisements. 2013 Existing implementations of SLP should return the 2014 SLP_NOT_IMPLEMENTED error code from this function. 2015 4) The SLPFindAttrs() function no longer takes a service type 2016 name. Attribute Request by Service Type has been dropped from 2017 SLP. 2018 5) The error codes SLP_AUTHENTICATION_ABSENT, 2019 SLP_AUTHENTICATION_FAILED, and SLP_INVALID_UPDATE are no longer 2020 supported because these errors no longer occur in the protocol. 2022 6.0 Example 2024 This example illustrates how to discover a mailbox. 2025 A POP3 server registers itself with the SLP framework. The 2026 attributes it registers are "USER", a list of all users whose mail 2027 is available through the POP3 server. 2028 The POP3 server code is the following: 2030 SLPHandle slph; 2031 SLPRegReport errCallback = POPRegErrCallback; 2032 /* Create an English SLPHandle, asynchronous processing. */ 2033 SLPError err = SLPOpen("en", SLP_TRUE, &slph); 2034 if( err != SLP_OK ) { 2035 /* Deal with error. */ 2036 } 2038 /* Create the service: URL and attribute parameters. */ 2039 const char* surl = "service:pop3://mail.netsurf.de"; /* the URL 2040 */ 2041 const char *pcAttrs = "(user=zaphod,trillian,roger,marvin)" 2042 /* Perform the registration. */ 2043 err = SLPReg(slph, 2044 surl, 2045 SLP_LIFETIME_DEFAULT, 2046 ppcAttrs, 2047 errCallback, 2048 NULL); 2050 if (err != SLP_OK ) { 2051 /*Deal with error.*/ 2052 } 2053 The errCallback reports any errors: 2054 void 2055 POPRegErrCallback(SLPHandle hSLP, 2056 SLPError errCode, 2057 unsigned short usLifetime, 2058 void* pvCookie) { 2059 if( errCode != SLP_OK ) { 2060 /* Report error through a dialog, message, etc. */ 2061 } 2063 /*Use lifetime interval to update periodically. */ 2064 } 2066 The POP3 client locates the server for the user with the following 2067 code: 2069 /* 2070 * The client calls SLPOpen(), exactly as above. 2071 */ 2073 const char *pcSrvType = "service:pop3"; /* the service type */ 2074 const char *pcScopeList = "default"; /* the scope */ 2075 const char *pcFilter = "(user=roger)"; /* the search filter */ 2076 SLPSrvURLCallback srvCallback = /* the callback */ 2077 POPSrvURLCallback; 2078 err = SLPFindSrvs(slph, 2079 pcSrvType, pcScopeList, pcFilter, 2080 srvCallback, NULL); 2081 if( err != SLP_OK ) { 2082 /* Deal with error. */ 2083 } 2085 Within the callback, the client code can use the returned POP 2086 service: 2088 SLPBoolean 2089 POPSrvURLCallback(SLPHandle hSLP, 2090 const char* pcSrvURL, 2091 unsigned short sLifetime, 2092 SLPError errCode, 2093 void* pvCookie) { 2095 if( errCode != SLP_OK ) { 2096 /* Deal with error. */ 2097 } 2099 SLPSrvURL* pSrvURL; 2100 errCode = SLPParseSrvURL(pcSrvURL, &pSrvURL); 2101 if (err != SLP_OK ) { 2102 /* Deal with error. */ 2103 } else { 2104 /* get the server's address */ 2105 struct hostent *phe = gethostbyname(pSrvURL.s_pcHost); 2106 /* use hostname in pSrvURL to connect to the POP3 server 2107 * . . . 2108 */ 2109 SLPFreeSrvURL((void*)pSrvURL); /* Free the pSrvURL storage*/ 2110 } 2112 return SLP_FALSE; /* Done! */ 2113 } 2115 A client that wanted to discover all the users receiving mail at the 2116 server uses with the following query: 2118 /* 2119 * The client calls SLPOpen(), exactly as above. We assume the 2120 * service: URL was retrieved into surl. 2121 */ 2123 const char *pcScopeList = "default"; /* the scope */ 2124 const char *pcAttrFilter = "use"; /* the attribute filter */ 2125 SLPAttrCallback attrCallBack = /* the callback */ 2126 POPUsersCallback 2128 err = 2129 SLPFindAttrs(slph, 2130 surl, 2131 pcScopeList, pcAttrFilter, 2132 attrCallBack, NULL); 2133 if( err != SLP_OK ) { 2134 /* Deal with error. */ 2135 } 2137 The callback processes the attributes: 2139 SLPBoolean 2140 POPUsersCallback(const char* pcAttrList, 2141 SLPError errCode, 2142 void* pvCookie) { 2144 if( errCode != SLP_OK ) { 2145 /* Deal with error. */ 2146 } else { 2147 /* Parse attributes. */ 2148 } 2150 return SLP_FALSE; /* Done! */ 2151 } 2153 7.0 Security Considerations 2155 Security is handled by IPSEC and is not exposed to API clients. An 2156 adversary could delete valid service advertisements, provide false 2157 service information and deny UAs knowledge of existing services 2158 unless IPSEC is used to secure IP traffic between SLP agents, as 2159 described in [8]. 2161 8.0 Acknowledgements 2162 The authors would like to thank Don Provan for his pioneering work 2163 during the initial stages of the RFC 2614 API definition. The 2164 contributions of Matt Peterson, Ira McDonald, and Jim Mayer were 2165 invaluable in preparing the current document. 2167 9.0 References 2169 [1] Kempf, J. and Guttman, E., "An API for Service Location," RFC 2170 2614, June, 1999. 2171 [2] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement 2172 Levels," BCP 14, RFC 2119, March 1997. 2173 [3] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 2174 Resource Identifiers (URI): Generic Syntax," RFC 2396, August 2175 1998. 2176 [4] Yergeau, F., "UTF-8, a transformation format of ISO 10646," RFC 2177 2279, January 1998. 2178 [5] Howes, T., "The String Representation of LDAP Search Filters," 2179 RFC 2254 December 1997. 2180 [6] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2181 Specifications: ABNF," RFC 2234, November 1997. 2182 [7] Alvestrand, H., "Tags for the Identification of Languages," RFC 2183 1766, March 1995. 2184 [8] Guttman, E., and J. Kempf, "Service Location Protocol, Version 2185 2," draft-guttman-rfc2608bis-01.txt, a work in progress. 2186 [9] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and 2187 Service: Schemes," RFC 2609, June 1999. 2189 10.0 Editors' Addresses 2191 Erik Guttman James Kempf 2192 Sun Microsystems, Inc. DoCoMo Labs, USA 2193 Eichhoelzelstr. 7 180 Metro Drive, Suite 300 2194 74915 Waibstadt San Jose, CA, 95430 2195 GERMANY USA 2196 Phone: +49 172 865 5497 Phone: +1 408 451 4711 2197 Email: Erik.Guttman@Sun.Com Email: kempf@docomolabs-usa.com 2199 11.0 Full Copyright Statement 2201 Copyright (C) The Internet Society (1999). All Rights Reserved. 2202 This document and translations of it may be copied and furnished to 2203 others, and derivative works that comment on or otherwise explain it 2204 or assist in its implementation may be prepared, copied, published 2205 and distributed, in whole or in part, without restriction of any 2206 kind, provided that the above copyright notice and this paragraph 2207 are included on all such copies and derivative works. However, this 2208 document itself may not be modified in any way, such as by removing 2209 the copyright notice or references to the Internet Society or other 2210 Internet organizations, except as needed for the purpose of 2211 developing Internet standards in which case the procedures for 2212 copyrights defined in the Internet Standards process must be 2213 followed, or as required to translate it into languages other than 2214 English. 2215 The limited permissions granted above are perpetual and will not be 2216 revoked by the Internet Society or its successors or assigns. 2218 This document and the information contained herein is provided on an 2219 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 2220 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 2221 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 2222 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES 2223 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 2224 Funding for the RFC Editor function is currently provided by the 2225 Internet Society.