Debian Codegraph @

rfc2614.html

raw
1 <pre>Network Working Group J. Kempf
2 Request for Comments: 2614 E. Guttman
3 Category: Informational Sun Microsystems
4 June 1999
5
6
7 <span class="h1">An API for Service Location</span>
8
9 Status of This Memo
10
11 This memo provides information for the Internet community. It does
12 not specify an Internet standard of any kind. Distribution of this
13 memo is unlimited.
14
15 Abstract
16
17 The Service Location Protocol (SLP) provides a new way for clients to
18 dynamically discovery network services. With SLP, it is simple to
19 offer highly available services that require no user configuration or
20 assistance from network administrators prior to use. This document
21 describes standardized APIs for SLP in C and Java. The APIs are
22 modular and are designed to allow implementations to offer just the
23 feature set needed. In addition, standardized file formats for
24 configuration and serialized registrations are defined, allowing SLP
25 agents to set network and other parameters in a portable way. The
26 serialized file format allows legacy services to be registered with
27 SLP directory agents in cases where modifying the legacy service
28 program code is difficult or impossible, and to portably exchange a
29 registration database.
30
31 Table of Contents
32
33 1. Introduction 4
34 <a href="#section-1.1">1.1</a>. Goals . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
35 <a href="#section-1.2">1.2</a>. Terminology . . . . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
36 2. File Formats 7
37 <a href="#section-2.1">2.1</a>. Configuration File Format . . . . . . . . . . . . . . <a href="#page-8">8</a>
38 <a href="#section-2.1.1">2.1.1</a>. DA configuration . . . . . . . . . . . . . . <a href="#page-9">9</a>
39 <a href="#section-2.1.2">2.1.2</a>. Static Scope Configuration . . . . . . . . . . <a href="#page-9">9</a>
40 <a href="#section-2.1.3">2.1.3</a>. Tracing and Logging . . . . . . . . . . . . . <a href="#page-11">11</a>
41 <a href="#section-2.1.4">2.1.4</a>. Serialized Proxy Registrations . . . . . . . . <a href="#page-11">11</a>
42 <a href="#section-2.1.5">2.1.5</a>. Network Configuration Properties . . . . . . . <a href="#page-12">12</a>
43 <a href="#section-2.1.6">2.1.6</a>. SA Configuration . . . . . . . . . . . . . . . <a href="#page-14">14</a>
44 <a href="#section-2.1.7">2.1.7</a>. UA Configuration . . . . . . . . . . . . . . . <a href="#page-14">14</a>
45 <a href="#section-2.1.8">2.1.8</a>. Security . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
46 <a href="#section-2.2">2.2</a>. Multihomed Machines. . . . . . . . . . . . . . . . . . <a href="#page-16">16</a>
47 <a href="#section-2.3">2.3</a>. Serialized Registration File . . . . . . . . . . . . . <a href="#page-16">16</a>
48
49
50
51
52 <span class="grey">Kempf &amp; Guttman Informational [Page 1]</span></pre>
53 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
54 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
55
56
57 2.4. Processing Serialized Registration and Configuration
58 Files . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-18">18</a>
59 3. Binding Independent Implementation Considerations 18
60 <a href="#section-3.1">3.1</a>. Multithreading . . . . . . . . . . . . . . . . . . . . <a href="#page-18">18</a>
61 <a href="#section-3.2">3.2</a>. Asynchronous and Incremental . . . . . . . . . . . . . <a href="#page-19">19</a>
62 <a href="#section-3.3">3.3</a>. Type Checking for Service Types. . . . . . . . . . . . <a href="#page-19">19</a>
63 <a href="#section-3.4">3.4</a>. Refreshing Registrations . . . . . . . . . . . . . . . <a href="#page-19">19</a>
64 <a href="#section-3.5">3.5</a>. Configuration File Processing . . . . . . . . . . . . <a href="#page-19">19</a>
65 <a href="#section-3.6">3.6</a>. Attribute Types . . . . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
66 <a href="#section-3.7">3.7</a>. Removal of Duplicates . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
67 <a href="#section-3.8">3.8</a>. Character Set Encoding . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
68 <a href="#section-3.9">3.9</a>. Error Semantics . . . . . . . . . . . . . . . . . . . <a href="#page-20">20</a>
69 <a href="#section-3.10">3.10</a>. Modular Implementations . . . . . . . . . . . . . . . <a href="#page-24">24</a>
70 <a href="#section-3.11">3.11</a>. Handling Special Service Types . . . . . . . . . . . . <a href="#page-24">24</a>
71 <a href="#section-3.12">3.12</a>. Scope Discovery and Handling . . . . . . . . . . . . . <a href="#page-24">24</a>
72 4. C Language Binding 25
73 <a href="#section-4.1">4.1</a>. Constant Types . . . . . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
74 <a href="#section-4.1.1">4.1.1</a>. URL Lifetimes. . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
75 <a href="#section-4.1.2">4.1.2</a>. Error Codes. . . . . . . . . . . . . . . . . . <a href="#page-26">26</a>
76 <a href="#section-4.1.3">4.1.3</a>. SLPBoolean . . . . . . . . . . . . . . . . . . <a href="#page-27">27</a>
77 <a href="#section-4.2">4.2</a>. Struct Types . . . . . . . . . . . . . . . . . . . . <a href="#page-28">28</a>
78 <a href="#section-4.2.1">4.2.1</a>. SLPSrvURL . . . . . . . . . . . . . . . . . . <a href="#page-28">28</a>
79 <a href="#section-4.2.2">4.2.2</a>. SLPHandle . . . . . . . . . . . . . . . . . . <a href="#page-29">29</a>
80 <a href="#section-4.3">4.3</a>. Callbacks . . . . . . . . . . . . . . . . . . . . . . <a href="#page-29">29</a>
81 <a href="#section-4.3.1">4.3.1</a>. SLPRegReport . . . . . . . . . . . . . . . . <a href="#page-30">30</a>
82 <a href="#section-4.3.2">4.3.2</a>. SLPSrvTypeCallback . . . . . . . . . . . . . . <a href="#page-30">30</a>
83 <a href="#section-4.3.3">4.3.3</a>. SLPSrvURLCallback . . . . . . . . . . . . . . <a href="#page-31">31</a>
84 <a href="#section-4.3.4">4.3.4</a>. SLPAttrCallback . . . . . . . . . . . . . . . <a href="#page-33">33</a>
85 <a href="#section-4.4">4.4</a>. Opening and Closing an SLPHandle . . . . . . . . . . . <a href="#page-34">34</a>
86 <a href="#section-4.4.1">4.4.1</a>. SLPOpen. . . . . . . . . . . . . . . . . . . . <a href="#page-34">34</a>
87 <a href="#section-4.4.2">4.4.2</a>. SLPClose . . . . . . . . . . . . . . . . . . . <a href="#page-35">35</a>
88 <a href="#section-4.5">4.5</a>. Protocol API . . . . . . . . . . . . . . . . . . . . <a href="#page-36">36</a>
89 <a href="#section-4.5.1">4.5.1</a>. SLPReg . . . . . . . . . . . . . . . . . . . . <a href="#page-36">36</a>
90 <a href="#section-4.5.2">4.5.2</a>. SLPDereg . . . . . . . . . . . . . . . . . . . <a href="#page-37">37</a>
91 <a href="#section-4.5.3">4.5.3</a>. SLPDelAttrs . . . . . . . . . . . . . . . . . <a href="#page-38">38</a>
92 <a href="#section-4.5.4">4.5.4</a>. SLPFindSrvTypes. . . . . . . . . . . . . . . . <a href="#page-39">39</a>
93 <a href="#section-4.5.5">4.5.5</a>. SLPFindSrvs . . . . . . . . . . . . . . . . . <a href="#page-41">41</a>
94 <a href="#section-4.5.6">4.5.6</a>. SLPFindAttrs . . . . . . . . . . . . . . . . . <a href="#page-42">42</a>
95 <a href="#section-4.6">4.6</a>. Miscellaneous Functions . . . . . . . . . . . . . . . <a href="#page-43">43</a>
96 <a href="#section-4.6.1">4.6.1</a>. SLPGetRefreshInterval . . . . . . . . . . . . <a href="#page-44">44</a>
97 <a href="#section-4.6.2">4.6.2</a>. SLPFindScopes . . . . . . . . . . . . . . . . <a href="#page-44">44</a>
98 <a href="#section-4.6.3">4.6.3</a>. SLPParseSrvURL . . . . . . . . . . . . . . . . <a href="#page-45">45</a>
99 <a href="#section-4.6.4">4.6.4</a>. SLPEscape . . . . . . . . . . . . . . . . . . <a href="#page-46">46</a>
100 <a href="#section-4.6.5">4.6.5</a>. SLPUnescape . . . . . . . . . . . . . . . . . <a href="#page-47">47</a>
101 <a href="#section-4.6.6">4.6.6</a>. SLPFree . . . . . . . . . . . . . . . . . . . <a href="#page-48">48</a>
102 <a href="#section-4.6.7">4.6.7</a>. SLPGetProperty . . . . . . . . . . . . . . . . <a href="#page-48">48</a>
103 <a href="#section-4.6.8">4.6.8</a>. SLPSetProperty . . . . . . . . . . . . . . . . <a href="#page-49">49</a>
104 <a href="#section-4.7">4.7</a>. Implementation Notes . . . . . . . . . . . . . . . . <a href="#page-49">49</a>
105
106
107
108 <span class="grey">Kempf &amp; Guttman Informational [Page 2]</span></pre>
109 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
110 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
111
112
113 <a href="#section-4.7.1">4.7.1</a>. Refreshing Registrations . . . . . . . . . . . <a href="#page-49">49</a>
114 <a href="#section-4.7.2">4.7.2</a>. Syntax for String Parameters . . . . . . . . . <a href="#page-49">49</a>
115 <a href="#section-4.7.3">4.7.3</a>. Client Side Syntax Checking . . . . . . . . . <a href="#page-50">50</a>
116 <a href="#section-4.7.4">4.7.4</a>. System Properties . . . . . . . . . . . . . . <a href="#page-50">50</a>
117 <a href="#section-4.7.5">4.7.5</a>. Memory Management . . . . . . . . . . . . . . <a href="#page-51">51</a>
118 4.7.6. Asynchronous and Incremental Return Semantics. 51
119 <a href="#section-4.8">4.8</a>. Example. . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-52">52</a>
120 5. Java Language Binding 56
121 <a href="#section-5.1">5.1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . <a href="#page-56">56</a>
122 <a href="#section-5.2">5.2</a>. Exceptions and Errors . . . . . . . . . . . . . . . . <a href="#page-56">56</a>
123 <a href="#section-5.2.1">5.2.1</a>. Class ServiceLocationException . . . . . . . . <a href="#page-57">57</a>
124 <a href="#section-5.3">5.3</a>. Basic Data Structures . . . . . . . . . . . . . . . . <a href="#page-58">58</a>
125 <a href="#section-5.3.1">5.3.1</a>. Interface ServiceLocationEnumeration . . . . . <a href="#page-58">58</a>
126 <a href="#section-5.3.2">5.3.2</a>. Class ServiceLocationAttribute . . . . . . . <a href="#page-58">58</a>
127 <a href="#section-5.3.3">5.3.3</a>. Class ServiceType . . . . . . . . . . . . . . <a href="#page-61">61</a>
128 <a href="#section-5.3.4">5.3.4</a>. Class ServiceURL . . . . . . . . . . . . . . <a href="#page-63">63</a>
129 <a href="#section-5.4">5.4</a>. SLP Access Interfaces . . . . . . . . . . . . . . . . <a href="#page-67">67</a>
130 <a href="#section-5.4.1">5.4.1</a>. Interface Advertiser . . . . . . . . . . . . . <a href="#page-67">67</a>
131 <a href="#section-5.4.2">5.4.2</a>. Interface Locator . . . . . . . . . . . . . . <a href="#page-69">69</a>
132 <a href="#section-5.5">5.5</a>. The Service Location Manager . . . . . . . . . . . . . <a href="#page-72">72</a>
133 <a href="#section-5.5.1">5.5.1</a>. Class ServiceLocationManager . . . . . . . . . <a href="#page-72">72</a>
134 <a href="#section-5.6">5.6</a>. Service Template Introspection . . . . . . . . . . . . <a href="#page-74">74</a>
135 <a href="#section-5.6.1">5.6.1</a>. Abstract Class TemplateRegistry . . . . . . . <a href="#page-74">74</a>
136 <a href="#section-5.6.2">5.6.2</a>. Interface ServiceLocationAttributeVerifier . . <a href="#page-77">77</a>
137 5.6.3. Interface ServiceLocationAttributeDescriptor . 79
138 <a href="#section-5.7">5.7</a>. Implementation Notes . . . . . . . . . . . . . . . . . <a href="#page-81">81</a>
139 <a href="#section-5.7.1">5.7.1</a>. Refreshing Registrations . . . . . . . . . . . <a href="#page-81">81</a>
140 <a href="#section-5.7.2">5.7.2</a>. Parsing Alternate Transports in ServiceURL . . <a href="#page-81">81</a>
141 <a href="#section-5.7.3">5.7.3</a>. String Attribute Values . . . . . . . . . . . <a href="#page-82">82</a>
142 <a href="#section-5.7.4">5.7.4</a>. Client Side Syntax Checking. . . . . . . . . . <a href="#page-82">82</a>
143 <a href="#section-5.7.5">5.7.5</a>. Language Locale Handling . . . . . . . . . . . <a href="#page-82">82</a>
144 <a href="#section-5.7.6">5.7.6</a>. Setting SLP System Properties. . . . . . . . . <a href="#page-83">83</a>
145 <a href="#section-5.7.7">5.7.7</a>. Multithreading . . . . . . . . . . . . . . . . <a href="#page-83">83</a>
146 <a href="#section-5.7.8">5.7.8</a>. Modular Implementations . . . . . . . . . . . <a href="#page-83">83</a>
147 5.7.9. Asynchronous and Incremental Return Semantics. 84
148 <a href="#section-5.8">5.8</a>. Example. . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-85">85</a>
149 6. Internationalization Considerations 87
150 <a href="#section-6.1">6.1</a>. service URL. . . . . . . . . . . . . . . . . . . . . . <a href="#page-87">87</a>
151 <a href="#section-6.2">6.2</a>. Character Set Encoding . . . . . . . . . . . . . . . . <a href="#page-87">87</a>
152 <a href="#section-6.3">6.3</a>. Language Tagging . . . . . . . . . . . . . . . . . . <a href="#page-88">88</a>
153 7. Security Considerations 88
154 8. Acknowledgements 88
155 9. References 89
156 10. Authors' Addresses 90
157 11. Full Copyright Statement 91
158
159
160
161
162
163
164 <span class="grey">Kempf &amp; Guttman Informational [Page 3]</span></pre>
165 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
166 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
167
168
169 <span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
170
171 The Service Location API is designed for standardized access to the
172 Service Location Protocol (SLP). The APIs allow client and service
173 programs to be be written or modified in a very simple manner to
174 provide dynamic service discovery and selection. Bindings in the C
175 and Java languages are defined in this document. In addition,
176 standardized formats for configuration files and for serialized
177 registration files are presented. These files allow SLP agents to
178 configure network parameters, to register legacy services that have
179 not been SLP enabled, and to portably exchange registration
180 databases.
181
182 <span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Goals</span>
183
184 The overall goal of the API is to enable source portability of
185 applications that use the API between different implementations of
186 SLP. The result should facilitate the adoption of SLP, and conversion
187 of clients and service programs to SLP.
188
189 The goals of the C binding are to create a minimal but complete
190 access to the functionality of the SLP protocol, allowing for simple
191 memory management and limited code size.
192
193 The Java API provides for modular implementations (where unneeded
194 features can be omitted) and an object oriented interface to the
195 complete set of SLP data and functionality.
196
197 The standardized configuration file and serialized file formats
198 provide a simple syntax with complete functional coverage of the
199 protocol, but without system dependent properties and secure
200 information.
201
202 <span class="h3"><a class="selflink" id="section-1.2" href="#section-1.2">1.2</a>. Terminology</span>
203
204 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
205 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
206 document are to be interpreted as described in <a href="./rfc2119">RFC 2119</a> [<a href="#ref-1" title="&quot;Key Words for Use in RFCs to Indicate Requirement Levels&quot;">1</a>].
207
208 Service Location Protocol (SLP)
209
210 The underlying protocol allowing dynamic and scalable service
211 discovery. This protocol is specified in the Service Location
212 Protocol Version 2 [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>].
213
214
215
216
217
218
219
220 <span class="grey">Kempf &amp; Guttman Informational [Page 4]</span></pre>
221 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
222 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
223
224
225 SLP framework
226
227 When a 'Service Location framework' is mentioned, it refers to
228 both the SLP implementation and interface implementation; i.e.
229 whatever provides the SLP functionality to user level programs.
230 This includes remote agents.
231
232 Directory Agent (DA)
233
234 A service that automatically gathers service advertisements
235 from SAs in order to provide them to UAs.
236
237 User Agent (UA)
238
239 This is the Service Location process or library that allows SLP
240 requests to be made on behalf of a client process. UAs
241 automatically direct requests to DAs when they exist. In their
242 absence, UAs make requests to SAs.
243
244 Service Agent (SA)
245
246 This is the Service Location process or library that allows
247 service software to register and deregister itself with the SLP
248 framework. SAs respond to UA service requests, detect DAs and
249 register service advertisements with them.
250
251 SA Server
252
253 Many operating system platforms only allow a single process to
254 listen on a particular port number. Since SAs are required to
255 listen on a multicast address for SLP service requests,
256 implementations of the SLP framework on such platforms that
257 want to support multiple SAs on one machine need to arrange for
258 a single process to do the listening while the advertising SAs
259 communicate with that process through another mechanism. The
260 single listening process is called an SA server. SA servers
261 share many characteristics with DAs, but they are not the same.
262
263 Service Advertisement
264
265 A URL possibly combined with service attributes. These are
266 made available to UAs by SAs, either directly or via a DA.
267
268 Locale
269
270 The language localization that applies to strings passed into
271 or returned from the SLP API. The Locale is expressed using a
272 Language Tag [<a href="#ref-6" title="&quot;Tags for the Identification of Languages&quot;">6</a>]. All attribute strings are associated with a
273
274
275
276 <span class="grey">Kempf &amp; Guttman Informational [Page 5]</span></pre>
277 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
278 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
279
280
281 particular locale. The locale is completely orthogonal to the
282 ANSI C locale. The SLP locale is mapped into the Java locale
283 in the Java API.
284
285 Service Template
286
287 A document that describes the syntax of the URL for a given
288 service type and a definition of all service attributes
289 including the meaning, defaults, and constraints on values the
290 attributes may take. See [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for more information on service
291 templates.
292
293 The service: URL
294
295 A service of a particular type announces its availability with
296 a service: URL that includes its service access point (domain
297 name or IP address, and possibly its port number) and
298 optionally basic configuration parameters. The syntax of the
299 service: URL is defined in the service template. Other URL's
300 can be used in service advertisements if desired.
301
302 Service Attributes
303
304 The attributes associated with a given service. The values
305 that can be assigned to service attributes are defined by the
306 service template.
307
308 Scope
309
310 A string used to control the availability of service
311 advertisements. Every SLP Agent is configured with one or more
312 scope strings. Scopes are assigned by site administrators to
313 group services for many purposes, but chiefly as a means of
314 scalability. DAs store only services advertised having a scope
315 string matching the scopes with which they are configured.
316
317 Naming Authority (NA)
318
319 This is a 'suffix' to the service type string. It completely
320 changes the meaning of the service type. NAs are used for
321 private definitions of well known Service Types and
322 experimental Service Type extensions. The default NA is
323 "IANA", which must not be explicitly included. Service types
324 with the IANA naming authority are registered with the Internet
325 Assigned Numbers Authority (see [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for more information on the
326 registration procedure).
327
328
329
330
331
332 <span class="grey">Kempf &amp; Guttman Informational [Page 6]</span></pre>
333 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
334 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
335
336
337 <span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. File Formats</span>
338
339 This section describes the configuration and serialized registration
340 file formats. Both files are defined in the UTF-8 character set [<a href="#ref-3" title="&quot;UTF-8, a transformation format of ISO 10646&quot;">3</a>].
341
342 Attribute tags and values in the serialized registration file require
343 SLP reserved characters to be escaped. The SLP reserved characters
344 are `(', `)', `,', `\', `!', `&lt;', `=', `&gt;', `~' and control
345 characters (characters with UTF codes less than 0x0020 and the
346 character 0x007f, which is US-ASCII DEL). The escapes are formed
347 exactly as for the wire protocol, i.e. a backslash followed by two
348 hex digits representing the character. For example, the escape for '
349 ,' is '\2c'. In addition, the characters `\n', `\r', `\t', and `_'
350 are prohibited from attribute tags by the SLP wire syntax grammar.
351 [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
352
353 In serialized registration files, escaped strings beginning with
354 `\ff`, an encoding for a nonUTF-8 character, are treated as opaques.
355 Exactly as in the wire protocol, syntactically correct opaque
356 encodings consist of a string beginning with `\ff` and containing
357 *only* escaped characters that are transformed to bytes. Such
358 strings are only syntactically correct in the serialized registration
359 file as attribute values. In other cases, whenever an escape is
360 encountered and the character is not an SLP reserved character, an
361 error is signaled.
362
363 Escaped characters in URLs in serialized registration files use the
364 URL escape convention. [<a href="#ref-2" title="&quot;Uniform Resource Identifiers (URI): Generic Syntax&quot;">2</a>].
365
366 Property names and values in the configuration file have a few
367 reserved characters that are involved in file's lexical definition.
368 The characters '.' and '=' are reserved in property names and must
369 be escape. The characters ',', '(', and ')' are reserved in property
370 values and must be escaped. In addition, scope names in the
371 net.slp.useScopes property use the SLP wire format escape convention
372 for SLP reserved characters. This simplifies implementation, since
373 the same code can be used to unescape scope names as is used in
374 processing the serialized registration file or for formatting wire
375 messages.
376
377 On platforms that only support US-ASCII and not UTF-8, the upper bit
378 of bytes incoming from the configuration and registration files
379 determines whether the character is US-ASCII or not US-ASCII.
380 According to the standard UTF-8 encoding, the upper bit is zero if
381 the character is US-ASCII and one if the character is multibyte and
382 thus not US-ASCII. Platforms without intrinsic UTF-8 support are
383 required to parse the multibyte character and store it in an
384 appropriate internal format. Support for UTF-8 is required to
385
386
387
388 <span class="grey">Kempf &amp; Guttman Informational [Page 7]</span></pre>
389 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
390 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
391
392
393 implement the SLP protocol (see [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]), and can therefore be used in
394 file processing as well.
395
396 The location and name of the configuration file is system-dependent,
397 but implementations of the API are encouraged to locate it together
398 with other configuration files and name it consistently.
399
400 <span class="h3"><a class="selflink" id="section-2.1" href="#section-2.1">2.1</a>. Configuration File Format</span>
401
402 The configuration file format consists of a newline delimited list of
403 zero or more property definitions. Each property definition
404 corresponds to a particular configurable SLP, network, or other
405 parameter in one or more of the three SLP agents. The file format
406 grammar in ABNF [<a href="#ref-5" title="&quot;Augmented BNF for Syntax Specifications: ABNF&quot;">5</a>] syntax is:
407
408 config-file = line-list
409 line-list = line / line line-list
410 line = property-line / comment-line
411 comment-line = ( "#" / ";" ) 1*allchar newline
412 property-line = property newline
413 property = tag "=" value-list
414 tag = prop / prop "." tag
415 prop = 1*tagchar
416 value-list = value / value "," value-list
417 value = int / bool /
418 "(" value-list ")" / string
419 int = 1*DIGIT
420 bool = "true" / "false" / "TRUE" / "FALSE"
421 newline = CR / ( CRLF )
422 string = 1*stringchar
423 tagchar = DIGIT / ALPHA / tother / escape
424 tother = %x21-%x2d / %x2f /
425 %x3a / %x3c-%x40 /
426 %x5b-%x60 / %7b-%7e
427 ; i.e., all characters except `.',
428 ; and `='.
429 stringchar = DIGIT / ALPHA / sother / escape
430 sother = %x21-%x29 / %x2a-%x2b /
431 %x2d-%x2f / %x3a-%x40 /
432 %x5b-%x60 / %7b-%7e
433 ; i.e., all characters except `,'
434 allchar = DIGIT / ALPHA / HTAB / SP
435 escape = "\" HEXDIG HEXDIG
436 ; Used for reserved characters
437
438 With the exception of net.slp.useScopes, net.slp.DAAddresses, and
439 net.slp.isBroadcastOnly, all other properties can be changed through
440 property accessors in the C and Java APIs. The property accessors
441
442
443
444 <span class="grey">Kempf &amp; Guttman Informational [Page 8]</span></pre>
445 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
446 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
447
448
449 only change the property values in the running agent program and do
450 not affect the values in the configuration file. The
451 net.slp.useScopes and net.slp.DAAddresses properties are read-only
452 because they control the agent's view of the scopes and DAs and are
453 therefore critical to the function of the API scope discovery
454 algorithm. Attempts to modify them are unlikely to yield productive
455 results, and could harm the ability of the agent to find scopes and
456 use DAs. The net.slp.isBroadcastOnly property is read-only because
457 the API library needs to configure networking upon start up and
458 changing this property might invalidate the configuration. Whether
459 the local network uses broadcast or multicast is not likely to change
460 during the course of the program's execution.
461
462 The properties break down into the following subsections describes an
463 area and its properties.
464
465 <span class="h4"><a class="selflink" id="section-2.1.1" href="#section-2.1.1">2.1.1</a>. DA configuration</span>
466
467 Important configuration properties for DAs are included in this
468 section. These are:
469
470 net.slp.isDA
471
472 A boolean indicating if the SLP server is to act as a DA. If
473 false, not run as a DA. Default is false.
474
475 net.slp.DAHeartBeat
476
477 A 32 bit integer giving the number of seconds for the
478 DA heartbeat. Default is 3 hours (10800 seconds). This
479 property corresponds to the protocol specification parameter
480 CONFIG_DA_BEAT [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. Ignored if isDA is false.
481
482 net.slp.DAAttributes
483
484 A comma-separated list of parenthesized attribute/value list
485 pairs that the DA must advertise in DAAdverts. The property
486 must be in the SLP attribute list wire format, including
487 escapes for reserved characters. [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
488
489 <span class="h4"><a class="selflink" id="section-2.1.2" href="#section-2.1.2">2.1.2</a>. Static Scope Configuration</span>
490
491 These properties allow various aspects of scope handling to be
492 configured.
493
494
495
496
497
498
499
500 <span class="grey">Kempf &amp; Guttman Informational [Page 9]</span></pre>
501 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
502 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
503
504
505 net.slp.useScopes
506
507 A value-list of strings indicating the only scopes a UA or SA
508 is allowed to use when making requests or registering, or the
509 scopes a DA must support. If not present for the DA and SA,
510 then in the absence of scope information from DHCP, the default
511 scope "DEFAULT" is used. If not present for the UA, and there
512 is no scope information available from DHCP, then the user
513 scoping model is in force. Active and passive DA discovery
514 or SA discovery are used for scope discovery, and the scope
515 "DEFAULT" is used if no other information is available. If a
516 DA or SA gets another scope in a request, a SCOPE_NOT_SUPPORTED
517 error should be returned, unless the request was multicast, in
518 which case it should be dropped. If a DA gets another scope in
519 a registration, a SCOPE_NOT_SUPPORTED error must be returned.
520 Unlike other properties, this property is "read-only", so
521 attempts to change it after the configuration file has been
522 read are ignored. See <a href="#section-3.12">Section 3.12</a> for the algorithm the API
523 uses in determining what scope information to present.
524
525 net.slp.DAAddresses
526
527 A value-list of IP addresses or DNS resolvable host names
528 giving the SLPv2 DAs to use for statically configured UAs and
529 SAs. Ignored by DAs (unless the DA is also an SA server).
530 Default is none. Unlike other properties, this property is
531 "read-only", so attempts to change it after the configuration
532 file has been read are ignored.
533
534 The following grammar describes the property:
535
536
537 addr-list = addr / addr "," addr-list
538 addr = fqdn / hostnumber
539 fqdn = ALPHA / ALPHA *[ anum / "-" ] anum
540 anum = ALPHA / DIGIT
541 hostnumber = 1*3DIGIT 3("." 1*3DIGIT)
542
543
544 An example is:
545
546
547 sawah,mandi,sambal
548
549
550 IP addresses can be used instead of host names in networks
551 where DNS is not deployed, but network administrators are
552 reminded that using IP addresses will complicate machine
553
554
555
556 <span class="grey">Kempf &amp; Guttman Informational [Page 10]</span></pre>
557 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
558 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
559
560
561 renumbering, since the SLP configuration property files
562 in statically configured networks will have to be changed.
563 Similarly, if host names are used, implementors must be careful
564 that a name service is available before SLP starts, in other
565 words, SLP cannot be used to find the name service.
566
567 <span class="h4"><a class="selflink" id="section-2.1.3" href="#section-2.1.3">2.1.3</a>. Tracing and Logging</span>
568
569 This section allows tracing and logging information to be printed by
570 the various agents.
571
572 net.slp.traceDATraffic
573
574 A boolean controlling printing of messages about traffic with
575 DAs. Default is false.
576
577 net.slp.traceMsg
578
579 A boolean controlling printing of details on SLP messages.
580 The fields in all incoming messages and outgoing replies are
581 printed. Default is false.
582
583 net.slp.traceDrop
584
585 A boolean controlling printing details when a SLP message is
586 dropped for any reason. Default is false.
587
588 net.slp.traceReg
589
590 A boolean controlling dumps of all registered services upon
591 registration and deregistration. If true, the contents
592 of the DA or SA server are dumped after a registration or
593 deregistration occurs. Default is false.
594
595 <span class="h4"><a class="selflink" id="section-2.1.4" href="#section-2.1.4">2.1.4</a>. Serialized Proxy Registrations</span>
596
597 These properties control the reading and writing of serialized
598 registrations.
599
600 net.slp.serializedRegURL
601
602 A string containing a URL pointing to a document containing
603 serialized registrations that should be processed when the DA
604 or SA server starts up. Default is none.
605
606
607
608
609
610
611
612 <span class="grey">Kempf &amp; Guttman Informational [Page 11]</span></pre>
613 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
614 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
615
616
617 <span class="h4"><a class="selflink" id="section-2.1.5" href="#section-2.1.5">2.1.5</a>. Network Configuration Properties</span>
618
619 The properties in this section allow various network configuration
620 properties to be set.
621
622 net.slp.isBroadcastOnly
623
624 A boolean indicating if broadcast should be used instead of
625 multicast. Like the net.slp.useScopes and net.slp.DAAddresses
626 properties, this property is "read-only", so attempts to change
627 it after the configuration file has been read are ignored.
628 Default is false.
629
630 net.slp.passiveDADetection
631
632 A boolean indicating whether passive DA detection should be
633 used. Default is true.
634
635 net.slp.multicastTTL
636
637 A positive integer less than or equal to 255, giving the
638 multicast TTL. Default is 255.
639
640 net.slp.DAActiveDiscoveryInterval
641
642 A 16 bit positive integer giving the number of seconds
643 between DA active discovery queries. Default is 900 seconds
644 (15 minutes). This property corresponds to the protocol
645 specification parameter CONFIG_DA_FIND [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. If the property is
646 set to zero, active discovery is turned off. This is useful
647 when the DAs available are explicitly restricted to those
648 obtained from DHCP or the net.slp.DAAddresses property.
649
650 net.slp.multicastMaximumWait
651
652 A 32 bit integer giving the maximum amount of time to perform
653 multicast, in milliseconds. Default is 15000 ms (15 sec.).
654 This property corresponds to the CONFIG_MC_MAX parameter in the
655 protocol specification [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>].
656
657 net.slp.multicastTimeouts
658
659 A value-list of 32 bit integers used as timeouts, in
660 milliseconds, to implement the multicast convergence
661 algorithm. Each value specifies the time to wait before
662 sending the next request, or until nothing new has
663 been learned from two successive requests. Default
664 is: 3000,3000,3000,3000,3000. In a fast network the
665
666
667
668 <span class="grey">Kempf &amp; Guttman Informational [Page 12]</span></pre>
669 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
670 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
671
672
673 aggressive values of 1000,1250,1500,2000,4000 allow better
674 performance. This property corresponds to the CONFIG_MC_RETRY
675 parameter in the protocol specification [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. Note that the
676 net.slp.DADiscoveryTimeouts property must be used for active DA
677 discovery.
678
679 net.slp.DADiscoveryTimeouts
680
681 A value-list of 32 bit integers used as timeouts, in
682 milliseconds, to implement the multicast convergence algorithm
683 during active DA discovery. Each value specifies the time
684 to wait before sending the next request, or until nothing
685 new has been learned from two successive requests. This
686 property corresponds to the protocol specification parameter
687 CONFIG_RETRY [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. Default is: 2000,2000,2000,2000,3000,4000.
688
689 net.slp.datagramTimeouts
690
691 A value-list of 32 bit integers used as timeouts, in
692 milliseconds, to implement unicast datagram transmission to
693 DAs. The nth value gives the time to block waiting for a reply
694 on the nth try to contact the DA. The sum of these values is
695 the protocol specification property CONFIG_RETRY_MAX [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>].
696
697 net.slp.randomWaitBound
698
699 A 32 bit integer giving the maximum value for all random
700 wait parameters, in milliseconds. Default is 1000 (1
701 sec.). This value corresponds to the protocol specification
702 parameters CONFIG_START_WAIT, CONFIG_REG_PASSIVE, and
703 CONFIG_REG_ACTIVE [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>].
704
705 net.slp.MTU
706
707 A 16 bit integer giving the network packet MTU, in bytes.
708 This is the maximum size of any datagram to send, but the
709 implementation might receive a larger datagram. The maximum
710 size includes IP, and UDP or TCP headers. Default is 1400.
711
712 net.slp.interfaces
713
714 Value-list of strings giving the IP addresses of network
715 interfaces on which the DA or SA should listen on port 427 for
716 multicast, unicast UDP, and TCP messages. Default is empty,
717 i.e. use the default network interface. The grammar for this
718 property is:
719
720
721
722
723
724 <span class="grey">Kempf &amp; Guttman Informational [Page 13]</span></pre>
725 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
726 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
727
728
729 addr-list = hostnumber / hostnumber "," addr-list
730 hostnumber = 1*3DIGIT 3("." 1*3DIGIT)
731
732
733 An example is:
734
735
736 195.42.42.42,195.42.142.1,195.42.120.1
737
738
739 The example machine has three interfaces on which the DA should
740 listen.
741
742 Note that since this property only takes IP addresses, it will
743 need to be changed if the network is renumbered.
744
745 <span class="h4"><a class="selflink" id="section-2.1.6" href="#section-2.1.6">2.1.6</a>. SA Configuration</span>
746
747 This section contains configuration properties for the SA. These
748 properties are typically set programmatically by the SA, since they
749 are specific to each SA.
750
751 net.slp.SAAttributes
752
753 A comma-separated list of parenthesized attribute/value list
754 pairs that the SA must advertise in SAAdverts. The property
755 must be in the SLP attribute list wire format, including
756 escapes for reserved characters. [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
757
758 <span class="h4"><a class="selflink" id="section-2.1.7" href="#section-2.1.7">2.1.7</a>. UA Configuration</span>
759
760 This section contains configuration properties for the UA. These
761 properties can be set either programmatically by the UA or in the
762 configuration file.
763
764 net.slp.locale
765
766 A <a href="./rfc1766">RFC 1766</a> Language Tag [<a href="#ref-6" title="&quot;Tags for the Identification of Languages&quot;">6</a>] for the language locale. Setting
767 this property causes the property value to become the default
768 locale for SLP messages. Default is "en". This property is
769 also used for SA and DA configuration.
770
771 net.slp.maxResults
772
773 A 32 bit integer giving the maximum number of results to
774 accumulate and return for a synchronous request before the
775 timeout, or the maximum number of results to return through a
776 callback if the request results are reported asynchronously.
777
778
779
780 <span class="grey">Kempf &amp; Guttman Informational [Page 14]</span></pre>
781 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span>
782 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
783
784
785 Positive integers and -1 are legal values. If -1, indicates
786 that all results should be returned. Default value is -1.
787
788 DAs and SAs always return all results that match the
789 request. This configuration value applies only to UAs, that
790 filter incoming results and only return as many values as
791 net.slp.maxResults indicates.
792
793 net.slp.typeHint
794
795 A value-list of service type names. In the absence of any
796 DAs, UAs perform SA discovery for finding scopes. These SA
797 discovery requests may contain a request for service types as
798 an attribute.
799
800 The API implementation will use the service type names supplied
801 by this property to discover only those SAs (and their scopes)
802 which support the desired service type or types. For example,
803 if net.slp.typeHint is set to "service:imap,service:pop3" then
804 SA discovery requests will include the search filter:
805
806
807 (|(service-type=service:imap)(service-type=service:pop3))
808
809
810 The API library can also use unicast to contact the discovered
811 SAs for subsequent requests for these service types, to
812 optimize network access.
813
814 <span class="h4"><a class="selflink" id="section-2.1.8" href="#section-2.1.8">2.1.8</a>. Security</span>
815
816 The property in this section allows security for all agents to be set
817 on or off. When the property is true, then the agent must include
818 security information on all SLP messages transacted by that agent.
819 Since security policy must be set network wide to be effective, a
820 single property controls security for all agents. Key management and
821 management of SLP SPI strings [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] are implementation and policy
822 dependent.
823
824 net.slp.securityEnabled
825
826 A boolean indicating whether the agent should enable
827 security for URLs, attribute lists, DAAdverts, and SAAdverts.
828 Each agent is responsible for interpreting the property
829 appropriately. Default is false.
830
831
832
833
834
835
836 <span class="grey">Kempf &amp; Guttman Informational [Page 15]</span></pre>
837 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span>
838 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
839
840
841 <span class="h3"><a class="selflink" id="section-2.2" href="#section-2.2">2.2</a>. Multihomed Machines</span>
842
843 On multihomed machines, the bandwidth and latency characteristics on
844 different network interfaces may differ considerably, to the point
845 where different configuration properties are necessary to achieve
846 optimal performance. The net.slp.interfaces property indicates which
847 network interfaces are SLP enabled. An API library implementation
848 may support configuration customization on a per network interface
849 basis by allowing the interface IP address to be appended to the
850 property name. In that case, the values of the property are only
851 used for that particular interface, the generic property (or defaults
852 if no generic property is set) applies to all others.
853
854 For example, if a configuration has the following properties:
855
856
857 net.slp.interfaces=125.196.42.41,125.196.42.42,125.196.42.43
858 net.slp.multicastTTL.125.196.42.42=1
859
860
861 then the network interface on subnet 42 is restricted to a TTL of 1,
862 while the interfaces on the other subnets have the default multicast
863 radius, 255.
864
865 The net.slp.interfaces property must only be set if there is no
866 routing between the interfaces. If the property is set, the DA (if
867 any) and SAs should advertise with the IP address or host name
868 appropriate to the interface on the interfaces in the list. If
869 packets are routed between the interfaces, then the DA and SAs should
870 only advertise on the default interface. The property should also be
871 set if broadcast is used rather than multicast on the subnets
872 connected to the interfaces. Note that even if unicast packets are
873 not routed between the interfaces, multicast may be routed through
874 another router. The danger in listening for multicast on multiple
875 interfaces when multicast packets are routed is that the DA or SA may
876 receive the same multicast request via more than one interface.
877 Since the IP address is different on each interface, the DA or SA
878 cannot identify the request as having already being answered via the
879 previous responder's list. The requesting agent will end up getting
880 URLs that refer to the same DA or service but have different
881 addresses or host names.
882
883 <span class="h3"><a class="selflink" id="section-2.3" href="#section-2.3">2.3</a>. Serialized Registration File</span>
884
885 The serialized registration file contains a group of registrations
886 that a DA or SA server (if one exists) registers when it starts up.
887 These registrations are primarily for older service programs that do
888 not internally support SLP and cannot be converted, and for portably
889
890
891
892 <span class="grey">Kempf &amp; Guttman Informational [Page 16]</span></pre>
893 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span>
894 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
895
896
897 exchanging registrations between SLP implementations. The character
898 encoding of the registrations is required to be UTF-8.
899
900 The syntax of the serialized registration file, in ABNF format [<a href="#ref-5" title="&quot;Augmented BNF for Syntax Specifications: ABNF&quot;">5</a>],
901 is as follows:
902
903
904 ser-file = reg-list
905 reg-list = reg / reg reg-list
906 reg = creg / ser-reg
907 creg = comment-line ser-reg
908 comment-line = ( "#" / ";" ) 1*allchar newline
909 ser-reg = url-props [slist] [attr-list] newline
910 url-props = surl "," lang "," ltime [ "," type ] newline
911 surl = ;The registration's URL. See
912 ; [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for syntax.
913 lang = 1*8ALPHA [ "-" 1*8ALPHA ]
914 ;<a href="./rfc1766">RFC 1766</a> Language Tag see [<a href="#ref-6" title="&quot;Tags for the Identification of Languages&quot;">6</a>].
915 ltime = 1*5DIGIT
916 ; A positive 16-bit integer
917 ; giving the lifetime
918 ; of the registration.
919 type = ; The service type name, see [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
920 ; and [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for syntax.
921 slist = "scopes" "=" scope-list newline
922 scope-list = scope-name / scope-name "," scope-list
923 scope = ; See grammar of [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for
924 ; scope-name syntax.
925 attr-list = attr-def / attr-def attr-list
926 attr-def = ( attr / keyword ) newline
927 keyword = attr-id
928 attr = attr-id "=" attr-val-list
929 attr-id = ;Attribute id, see [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for syntax.
930 attr-val-list = attr-val / attr-val "," attr-val-list
931 attr-val = ;Attribute value, see [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for syntax.
932 allchar = char / WSP
933 char = DIGIT / ALPHA / other
934 other = %x21-%x2f / %x3a-%x40 /
935 %x5b-%x60 / %7b-%7e
936 ; All printable, nonwhitespace US-ASCII
937 ; characters.
938 newline = CR / ( CRLF )
939
940
941 The syntax for scope names, attribute tags, and attribute values
942 requires escapes for special characters as specified in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. DAs and
943 SA servers that process serialized registrations must handle them
944 exactly as if they were registered by an SA. In the url-props
945
946
947
948 <span class="grey">Kempf &amp; Guttman Informational [Page 17]</span></pre>
949 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-18" ></span>
950 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
951
952
953 production, the type token is optional. If the type token is present
954 for a service: URL, a warning is signaled and the type name is
955 ignored. If the maximum lifetime is specified (65535 sec.), the
956 registration is taken to be permanent, and is continually refreshed
957 by the DA or SA server until it exits. Scopes can be included in a
958 registration by including an attribute definition with tag "scopes"
959 followed by a comma separated list of scope names immediately after
960 the url-props production. If the optional scope list is present, the
961 registrations are made in the indicated scopes; otherwise, they are
962 registered in the scopes with which the DA or SA server was
963 configured through the net.slp.useScopes property.
964
965 If the scope list contains scopes that are not in the
966 net.slp.useScopes property (provided that property is set) or are not
967 specified by DHCP, the API library should reject the registration and
968 issue a warning message.
969
970 <span class="h3"><a class="selflink" id="section-2.4" href="#section-2.4">2.4</a>. Processing Serialized Registration and Configuration Files</span>
971
972 Implementations are encouraged to make processing of configuration
973 and serialized files as transparent as possible to clients of the
974 API. At the latest, errors must be caught when the relevant
975 configuration item is used. At the earliest, errors may be caught
976 when the relevant file is loaded into the executing agent. Errors
977 should be reported by logging to the appropriate platform logging
978 file, error output, or log device, and the default value substituted.
979 Serialized registration file entries should be caught and reported
980 when the file is loaded.
981
982 Configuration file loading must be complete prior to the initiation
983 of the first networking connection. Serialized registration must be
984 complete before the DA accepts the first network request.
985
986 <span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Binding Independent Implementation Considerations</span>
987
988 This section discusses a number of implementation considerations
989 independent of language binding, with language specific notes where
990 applicable.
991
992 <span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Multithreading</span>
993
994 Implementations of both the C and Java APIs are required to make API
995 calls thread-safe. Access to data structures shared between threads
996 must be co-ordinated to avoid corruption or invalid access. One way
997 to achieve this goal is to allow only one thread at a time in the
998 implementing library. Performance in such an implementation suffers,
999 however. Therefore, where possible, implementations are encouraged
1000 to allow multiple threads within the SLP API library.
1001
1002
1003
1004 <span class="grey">Kempf &amp; Guttman Informational [Page 18]</span></pre>
1005 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-19" ></span>
1006 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1007
1008
1009 <span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Asynchronous and Incremental</span>
1010
1011 The APIs are designed to encourage implementations supporting
1012 asynchronous and incremental client interaction. The goal is to
1013 allow large numbers of returned service URLs, service types, and
1014 attributes without requiring the allocation of huge chunks of memory.
1015 The particular design features to support this goal differ in the two
1016 language bindings.
1017
1018 <span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Type Checking for Service Types</span>
1019
1020 Service templates [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] allow SLP registrations to be type checked for
1021 correctness. Implementations of the API are free to make use of
1022 service type information for type checking, but are not required to
1023 do so. If a type error occurs, the registration should terminate
1024 with TYPE_ERROR.
1025
1026 <span class="h3"><a class="selflink" id="section-3.4" href="#section-3.4">3.4</a>. Refreshing Registrations</span>
1027
1028 SLP advertisements carry an explicit lifetime with them. After the
1029 lifetime expires, the DA flushes the registration from its cache. In
1030 some cases, an application may want to have the URL continue being
1031 registered for the entire time during which the application is
1032 executing. The API includes provision for clients to indicate
1033 whether they want URLs to be automatically refreshed.
1034 Implementations of the SA API must provide this automatic refreshing
1035 capability. Note that a client which uses this facility should
1036 explicitly deregister the service URL before exiting, since the API
1037 implementation may not be able to assure that the URL is deregistered
1038 when the application exits, although it will time out in the DA
1039 eventually.
1040
1041 <span class="h3"><a class="selflink" id="section-3.5" href="#section-3.5">3.5</a>. Configuration File Processing</span>
1042
1043 DAs, SAs and UAs processing the configuration file, and DAs and SA
1044 servers processing the serialized registration file are required to
1045 log any errors using whatever underlying error mechanism is
1046 appropriate for the platform. Examples include writing error
1047 messages to the standard output, writing to a system logging device,
1048 or displaying the errors to a logging window. After the error is
1049 reported, the offending property must be set to the default and
1050 program execution continued. An agent MUST NOT fail if a file format
1051 error occurs.
1052
1053
1054
1055
1056
1057
1058
1059
1060 <span class="grey">Kempf &amp; Guttman Informational [Page 19]</span></pre>
1061 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-20" ></span>
1062 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1063
1064
1065 <span class="h3"><a class="selflink" id="section-3.6" href="#section-3.6">3.6</a>. Attribute Types</span>
1066
1067 String encoded attribute values do not include explicit type
1068 information. All UA implementations and those SA and DA
1069 implementations that choose to support type checking should use the
1070 type rules described in [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] in order to convert from the string
1071 representation on the wire to an object typed appropriately.
1072
1073 <span class="h3"><a class="selflink" id="section-3.7" href="#section-3.7">3.7</a>. Removal of Duplicates</span>
1074
1075 The UA implementation SHOULD always collate results to remove
1076 duplicates during synchronous operations and for the Java API. During
1077 asynchronous operation in C, the UA implementation SHOULD forgo
1078 duplicate elimination to reduce memory requirements in the library.
1079 This allows the API library to simply take the returned attribute
1080 value list strings, URL strings, or service type list strings and
1081 call the callback function with it, without any additional
1082 processing. Naturally, the burden of duplicate elimination is thrown
1083 onto the client in this case.
1084
1085 <span class="h3"><a class="selflink" id="section-3.8" href="#section-3.8">3.8</a>. Character Set Encoding</span>
1086
1087 Character string parameters in the Java API are all represented in
1088 Unicode internally because that is the Java-supported character set.
1089 Characters buffer parameters in the C API are represented in UTF-8 to
1090 maintain maximum compatibility on platforms that only support US-
1091 ASCII and not UTF-8. API functions are still required to handle the
1092 full range of UTF-8 characters because the SLP protocol requires it,
1093 but the API implementation can represent the characters internally in
1094 any convenient way. On the wire, all characters are converted to
1095 UTF-8. Inside URLs, characters that are not allowed by URL syntax
1096 [<a href="#ref-2" title="&quot;Uniform Resource Identifiers (URI): Generic Syntax&quot;">2</a>] must be escaped according to the URL escape character convention.
1097 Strings that are included in SLP messages may include SLP reserved
1098 characters and can be escaped by clients through convenience
1099 functions provided by the API. The character encoding used in escapes
1100 is UTF-8.
1101
1102 Due to constraints in SLP, no string parameter passed to the C or
1103 Java API may exceed 64K bytes in length.
1104
1105 <span class="h3"><a class="selflink" id="section-3.9" href="#section-3.9">3.9</a>. Error Semantics</span>
1106
1107 All errors encountered processing SLP messages should be logged. For
1108 synchronous calls, an error is only reported on a call if no
1109 successful replies were received from any SLP framework entity. If
1110 an error occurred among one of several successful replies, then the
1111 error should be logged and the successful replies returned. For
1112 asynchronous calls, an error occurring during correspondence with a
1113
1114
1115
1116 <span class="grey">Kempf &amp; Guttman Informational [Page 20]</span></pre>
1117 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-21" ></span>
1118 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1119
1120
1121 particular remote SLP agent is reported through the first callback
1122 (in the C API) or enumeration method invocation (in the Java API)
1123 after the error occurs, which would normally report the results of
1124 the correspondence. This allows the callback or client code to
1125 determine whether the operation should be terminated or continue. In
1126 some cases, the error returned from the SLP framework may be fatal
1127 (SLP_PARSE_ERROR, etc.). In these cases, the API library terminates
1128 the operation.
1129
1130 Both the Java and C APIs contain language specific error code
1131 mechanisms for returning error information. The names of the error
1132 codes are consistent between the two implementations, however.
1133
1134 The following error codes are returned from a remote agent (DA or SA
1135 server):
1136
1137 LANGUAGE_NOT_SUPPORTED
1138
1139 No DA or SA has service advertisement or attribute information
1140 in the language requested, but at least one DA or SA indicated,
1141 via the LANGUAGE_NOT_SUPPORTED error code, that it might have
1142 information for that service in another language.
1143
1144 PARSE_ERROR
1145
1146 The SLP message was rejected by a remote SLP agent. The API
1147 returns this error only when no information was retrieved, and
1148 at least one SA or DA indicated a protocol error. The data
1149 supplied through the API may be malformed or a may have been
1150 damaged in transit.
1151
1152 INVALID_REGISTRATION
1153
1154 The API may return this error if an attempt to register a
1155 service was rejected by all DAs because of a malformed URL or
1156 attributes. SLP does not return the error if at least one DA
1157 accepted the registration.
1158
1159 AUTHENTICATION_ABSENT
1160
1161 If the SLP framework supports authentication, this error arises
1162 when the UA or SA failed to send an authenticator for requests
1163 or registrations in a protected scope.
1164
1165
1166
1167
1168
1169
1170
1171
1172 <span class="grey">Kempf &amp; Guttman Informational [Page 21]</span></pre>
1173 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-22" ></span>
1174 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1175
1176
1177 INVALID_UPDATE
1178
1179 An update for a non-existing registration was issued, or the
1180 update includes a service type or scope different than that in
1181 the initial registration, etc.
1182
1183 The following errors result from interactions with remote agents or
1184 can occur locally:
1185
1186 AUTHENTICATION_FAILED
1187
1188 If the SLP framework supports authentication, this error arises
1189 when a authentication on an SLP message failed.
1190
1191 SCOPE_NOT_SUPPORTED
1192
1193 The API returns this error if the SA has been configured with
1194 net.slp.useScopes value-list of scopes and the SA request did
1195 not specify one or more of these allowable scopes, and no
1196 others. It may be returned by a DA or SA if the scope included
1197 in a request is not supported by the DA or SA.
1198
1199 REFRESH_REJECTED
1200
1201 The SA attempted to refresh a registration more frequently
1202 than the minimum refresh interval. The SA should call the
1203 appropriate API function to obtain the minimum refresh interval
1204 to use.
1205
1206 The following errors are generated through a program interacting with
1207 the API implementation. They do not involve a remote SLP agent.
1208
1209 NOT_IMPLEMENTED
1210
1211 If an unimplemented feature is used, this error is returned.
1212
1213 NETWORK_INIT_FAILED
1214
1215 If the network cannot initialize properly, this error is
1216 returned.
1217
1218 NETWORK_TIMED_OUT
1219
1220 When no reply can be obtained in the time specified by the
1221 configured timeout interval for a unicast request, this error
1222 is returned.
1223
1224
1225
1226
1227
1228 <span class="grey">Kempf &amp; Guttman Informational [Page 22]</span></pre>
1229 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-23" ></span>
1230 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1231
1232
1233 NETWORK_ERROR
1234
1235 The failure of networking during normal operations causes this
1236 error to be returned.
1237
1238 BUFFER_OVERFLOW
1239
1240 An outgoing request overflowed the maximum network MTU size.
1241 The request should be reduced in size or broken into pieces and
1242 tried again.
1243
1244 MEMORY_ALLOC_FAILED
1245
1246 If the API fails to allocate memory, the operation is aborted
1247 and returns this.
1248
1249 PARAMETER_BAD
1250
1251 If a parameter passed into an interface is bad, this error is
1252 returned.
1253
1254 INTERNAL_SYSTEM_ERROR
1255
1256 A basic failure of the API causes this error to be returned.
1257 This occurs when a system call or library fails. The operation
1258 could not recover.
1259
1260 HANDLE_IN_USE
1261
1262 In the C API, callback functions are not permitted to
1263 recursively call into the API on the same SLPHandle, either
1264 directly or indirectly. If an attempt is made to do so, this
1265 error is returned from the called API function.
1266
1267 TYPE_ERROR
1268
1269 If the API supports type checking of registrations against
1270 service type templates, this error can arise if the attributes
1271 in a registration do not match the service type template for
1272 the service.
1273
1274 Some error codes are handled differently in the Java API. These
1275 differences are discussed in <a href="#section-5">Section 5</a>.
1276
1277 The SLP protocol errors OPTION_NOT_UNDERSTOOD, VERSION_NOT_SUPPORTED,
1278 INTERNAL_ERROR, MSG_NOT_SUPPORTED, AUTHENTICATON_UNKNOWN, and
1279 DA_BUSY_NOW should be handled internally and not surfaced to clients
1280 through the API.
1281
1282
1283
1284 <span class="grey">Kempf &amp; Guttman Informational [Page 23]</span></pre>
1285 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-24" ></span>
1286 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1287
1288
1289 <span class="h3"><a class="selflink" id="section-3.10" href="#section-3.10">3.10</a>. Modular Implementations</span>
1290
1291 Subset implementations that do not support the full range of
1292 functionality are required to nevertheless support every interface in
1293 order to maintain link compatibility between compliant API
1294 implementations and applications. If a particular operation is not
1295 supported, a NOT_IMPLEMENTED error should be returned. The Java API
1296 has some additional conventions for handling subsets. Applications
1297 that are expected to run on a wide variety of platforms should be
1298 prepared for subset API implementations by checking returned error
1299 codes.
1300
1301 <span class="h3"><a class="selflink" id="section-3.11" href="#section-3.11">3.11</a>. Handling Special Service Types</span>
1302
1303 The service types service:directory-agent and service:service-agent
1304 are used internally in the SLP framework to discover DAs and SAs.
1305 The mechanism of DA and SA discovery is not normally exposed to the
1306 API client; however, the client may have interest in discovering DAs
1307 and SAs independently of their role in discovering other services.
1308 For example, a network management application may want to determine
1309 which machines are running SLP DAs. To facilitate that, API
1310 implementations must handle requests to find services and attributes
1311 for these two service types so that API clients obtain the
1312 information they expect.
1313
1314 In particular, if the UA is using a DA, SrvRqst and AttrRqst for
1315 these service types must be multicast and not unicast to the DA, as
1316 is the case for other service types. If the requests are not
1317 multicast, the DA will respond with an empty reply to a request for
1318 services of type service:service-agent and with its URL only to a
1319 request for services of type service:directory-agent. The UA would
1320 therefore not obtain a complete picture of the available DAs and SAs.
1321
1322 <span class="h3"><a class="selflink" id="section-3.12" href="#section-3.12">3.12</a>. Scope Discovery and Handling</span>
1323
1324 Both APIs contain an operation to obtain a list of currently known
1325 scope names. This scope information comes from a variety of places:
1326 DHCP, the net.slp.useScopes property, unicast to DAs configured via
1327 DHCP or the net.slp.DAAddresses property, and active and passive
1328 discovery.
1329
1330 The API is required to be implemented in a way that re-enforces the
1331 administrative and user scoping models described in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. SA clients
1332 only support the administrative scoping model. SAs must know a
1333 priori what DAs they need to register with since there is typically
1334 no human intervention in scope selection for SAs. UAs must support
1335 both administrative and user scoping because an application may
1336 require human intervention in scope selection.
1337
1338
1339
1340 <span class="grey">Kempf &amp; Guttman Informational [Page 24]</span></pre>
1341 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-25" ></span>
1342 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1343
1344
1345 API implementations are required to support administrative scoping in
1346 the following way. Scopes configured by DHCP and scopes of DAs
1347 configured by DHCP have first priority (in that order) and must be
1348 returned if they are available. The net.slp.useScopes property has
1349 second priority, and scopes discovered through the net.slp.useScopes
1350 property must be returned if this property is set and there are no
1351 scopes available from DHCP. If scopes are not available from either
1352 of these sources and the net.slp.DAAddresses property is set, then
1353 the scopes available from the configured DAs must be returned. Note
1354 that if both DAs and scopes are configured, the scopes of the
1355 configured DAs must match the configured scope list; otherwise and
1356 error is signaled and agent execution is terminated. If no
1357 configured scope information is available, then an SA client has
1358 default scope, "DEFAULT", and a UA client employs user scoping.
1359
1360 User scoping is supported in the following way. Scopes discovered
1361 from active DA discovery, and from passive DA discovery all must be
1362 returned. If no information is available from active and passive DA
1363 discovery, then the API library may perform SA discovery, using the
1364 service types in the net.slp.typeHint property to limit the search to
1365 SAs supporting particular service types. If no net.slp.typeHint
1366 property is set, the UA may perform SA discovery without any service
1367 type query. In the absence of any of the above sources of
1368 information, the API must return the default scope, "DEFAULT". Note
1369 that the API must always return some scope information.
1370
1371 SLP requires that SAs must perform their operations in all scopes
1372 currently known to them. [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. The API enforces this constraint by
1373 not requiring the API client to supply any scopes as parameters to
1374 API operations. The API library must obtain all currently known
1375 scopes and use them in SA operations. UA API clients should use a
1376 scope obtained through one of the API operations for finding scopes.
1377 Any other scope name may result in a SCOPE_NOT_SUPPORTED error from a
1378 remote agent. The UA API library can optionally check the scope and
1379 return the error without contacting a remote agent.
1380
1381 <span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. C Language Binding</span>
1382
1383 The C language binding presents a minimal overhead implementation
1384 that maps directly into the protocol. There is one C language
1385 function per protocol request, with the exception of the SLPDereg()
1386 and SLPDelAttrs() functions, which map into different uses of the SLP
1387 deregister request. Parameters are for the most part character
1388 buffers. Memory management is kept simple by having the client
1389 allocate most memory and requiring that client callback functions
1390 copy incoming parameters into memory allocated by the client code.
1391 Any memory returned directly from the API functions is deallocated
1392 using the SLPFree() function.
1393
1394
1395
1396 <span class="grey">Kempf &amp; Guttman Informational [Page 25]</span></pre>
1397 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-26" ></span>
1398 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1399
1400
1401 To conform with standard C practice, all character strings passed to
1402 and returned through the API are null terminated, even though the SLP
1403 protocol does not use null terminated strings. Strings passed as
1404 parameters are UTF-8 but they may still be passed as a C string (a
1405 null terminated sequence of bytes.) Escaped characters must be
1406 encoded by the API client as UTF-8. In the common case of US-ASCII,
1407 the usual one byte per character C strings work. API functions
1408 assist in escaping and unescaping strings.
1409
1410 Unless otherwise noted, parameters to API functions and callbacks are
1411 non-NULL. Some parameters may have other restrictions. If any
1412 parameter fails to satisfy the restrictions on its value, the
1413 operation returns a PARAMETER_BAD error.
1414
1415 <span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Constant Types</span>
1416
1417 <span class="h4"><a class="selflink" id="section-4.1.1" href="#section-4.1.1">4.1.1</a>. URL Lifetimes</span>
1418
1419 <span class="h5"><a class="selflink" id="section-4.1.1.1" href="#section-4.1.1.1">4.1.1.1</a>. Synopsis</span>
1420
1421
1422 typedef enum {
1423 SLP_LIFETIME_DEFAULT = 10800,
1424 SLP_LIFETIME_MAXIMUM = 65535
1425 } SLPURLLifetime;
1426
1427
1428 <span class="h5"><a class="selflink" id="section-4.1.1.2" href="#section-4.1.1.2">4.1.1.2</a>. Description</span>
1429
1430 The SLPURLLifetime enum type contains URL lifetime values, in
1431 seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours,
1432 while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the
1433 maximum size of the lifetime field in SLP messages.
1434
1435 <span class="h4"><a class="selflink" id="section-4.1.2" href="#section-4.1.2">4.1.2</a>. Error Codes</span>
1436
1437 <span class="h5"><a class="selflink" id="section-4.1.2.1" href="#section-4.1.2.1">4.1.2.1</a>. Synopsis</span>
1438
1439
1440 typedef enum {
1441 SLP_LAST_CALL = 1,
1442 SLP_OK = 0,
1443 SLP_LANGUAGE_NOT_SUPPORTED = -1,
1444 SLP_PARSE_ERROR = -2,
1445 SLP_INVALID_REGISTRATION = -3,
1446 SLP_SCOPE_NOT_SUPPORTED = -4,
1447 SLP_AUTHENTICATION_ABSENT = -6,
1448 SLP_AUTHENTICATION_FAILED = -7,
1449
1450
1451
1452 <span class="grey">Kempf &amp; Guttman Informational [Page 26]</span></pre>
1453 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-27" ></span>
1454 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1455
1456
1457 SLP_INVALID_UPDATE = -13,
1458 SLP_REFRESH_REJECTED = -15,
1459 SLP_NOT_IMPLEMENTED = -17,
1460 SLP_BUFFER_OVERFLOW = -18,
1461 SLP_NETWORK_TIMED_OUT = -19,
1462 SLP_NETWORK_INIT_FAILED = -20,
1463 SLP_MEMORY_ALLOC_FAILED = -21,
1464 SLP_PARAMETER_BAD = -22,
1465 SLP_NETWORK_ERROR = -23,
1466 SLP_INTERNAL_SYSTEM_ERROR = -24,
1467 SLP_HANDLE_IN_USE = -25,
1468 SLP_TYPE_ERROR = -26
1469 } SLPError ;
1470
1471
1472 <span class="h5"><a class="selflink" id="section-4.1.2.2" href="#section-4.1.2.2">4.1.2.2</a>. Description</span>
1473
1474 The SLPError enum contains error codes that are returned from API
1475 functions.
1476
1477 The SLP_OK code indicates that the no error occurred during the
1478 operation.
1479
1480 The SLP_LAST_CALL code is passed to callback functions when the API
1481 library has no more data for them and therefore no further calls will
1482 be made to the callback on the currently outstanding operation. The
1483 callback can use this to signal the main body of the client code that
1484 no more data will be forthcoming on the operation, so that the main
1485 body of the client code can break out of data collection loops. On
1486 the last call of a callback during both a synchronous and
1487 asynchronous call, the error code parameter has value SLP_LAST_CALL,
1488 and the other parameters are all NULL. If no results are returned by
1489 an API operation, then only one call is made, with the error
1490 parameter set to SLP_LAST_CALL.
1491
1492 <span class="h4"><a class="selflink" id="section-4.1.3" href="#section-4.1.3">4.1.3</a>. SLPBoolean</span>
1493
1494 <span class="h5"><a class="selflink" id="section-4.1.3.1" href="#section-4.1.3.1">4.1.3.1</a>. Synopsis</span>
1495
1496
1497 typedef enum {
1498 SLP_FALSE = 0,
1499 SLP_TRUE = 1
1500
1501 } SLPBoolean;
1502
1503
1504
1505
1506
1507
1508 <span class="grey">Kempf &amp; Guttman Informational [Page 27]</span></pre>
1509 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-28" ></span>
1510 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1511
1512
1513 <span class="h5"><a class="selflink" id="section-4.1.3.2" href="#section-4.1.3.2">4.1.3.2</a>. Description</span>
1514
1515 The SLPBoolean enum is used as a boolean flag.
1516
1517 <span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. Struct Types</span>
1518
1519 <span class="h4"><a class="selflink" id="section-4.2.1" href="#section-4.2.1">4.2.1</a>. SLPSrvURL</span>
1520
1521 <span class="h5"><a class="selflink" id="section-4.2.1.1" href="#section-4.2.1.1">4.2.1.1</a>. Synopsis</span>
1522
1523
1524 typedef struct srvurl {
1525 char *s_pcSrvType;
1526 char *s_pcHost;
1527 int s_iPort;
1528 char *s_pcNetFamily;
1529 char *s_pcSrvPart;
1530 } SLPSrvURL;
1531
1532
1533 <span class="h5"><a class="selflink" id="section-4.2.1.2" href="#section-4.2.1.2">4.2.1.2</a>. Description</span>
1534
1535 The SLPSrvURL structure is filled in by the SLPParseSrvURL() function
1536 with information parsed from a character buffer containing a service
1537 URL. The fields correspond to different parts of the URL. Note that
1538 the structure is in conformance with the standard Berkeley sockets
1539 struct servent, with the exception that the pointer to an array of
1540 characters for aliases (s_aliases field) is replaced by the pointer
1541 to host name (s_pcHost field).
1542
1543 s_pcSrvType
1544
1545 A pointer to a character string containing the service
1546 type name, including naming authority. The service type
1547 name includes the "service:" if the URL is of the service:
1548 scheme. [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
1549
1550 s_pcHost
1551
1552 A pointer to a character string containing the host
1553 identification information.
1554
1555 s_iPort
1556
1557 The port number, or zero if none. The port is only available
1558 if the transport is IP.
1559
1560
1561
1562
1563
1564 <span class="grey">Kempf &amp; Guttman Informational [Page 28]</span></pre>
1565 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-29" ></span>
1566 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1567
1568
1569 s_pcNetFamily
1570
1571 A pointer to a character string containing the network address
1572 family identifier. Possible values are "ipx" for the IPX
1573 family, "at" for the Appletalk family, and "" (i.e. the empty
1574 string) for the IP address family.
1575
1576 s_pcSrvPart
1577
1578 The remainder of the URL, after the host identification.
1579
1580 The host and port should be sufficient to open a socket to the
1581 machine hosting the service, and the remainder of the URL should
1582 allow further differentiation of the service.
1583
1584 <span class="h4"><a class="selflink" id="section-4.2.2" href="#section-4.2.2">4.2.2</a>. SLPHandle</span>
1585
1586 <span class="h5"><a class="selflink" id="section-4.2.2.1" href="#section-4.2.2.1">4.2.2.1</a>. Synopsis</span>
1587
1588
1589 typedef void* SLPHandle;
1590
1591
1592 The SLPHandle type is returned by SLPOpen() and is a parameter to all
1593 SLP functions. It serves as a handle for all resources allocated on
1594 behalf of the process by the SLP library. The type is opaque, since
1595 the exact nature differs depending on the implementation.
1596
1597 <span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. Callbacks</span>
1598
1599 A function pointer to a callback function specific to a particular
1600 API operation is included in the parameter list when the API function
1601 is invoked. The callback function is called with the results of the
1602 operation in both the synchronous and asynchronous cases. The memory
1603 included in the callback parameters is owned by the API library, and
1604 the client code in the callback must copy out the contents if it
1605 wants to maintain the information longer than the duration of the
1606 current callback call.
1607
1608 In addition to parameters for reporting the results of the operation,
1609 each callback parameter list contains an error code parameter and a
1610 cookie parameter. The error code parameter reports the error status
1611 of the ongoing (for asynchronous) or completed (for synchronous)
1612 operation. The cookie parameter allows the client code that starts
1613 the operation by invoking the API function to pass information down
1614 to the callback without using global variables. The callback returns
1615 an SLPBoolean to indicate whether the API library should continue
1616 processing the operation. If the value returned from the callback is
1617
1618
1619
1620 <span class="grey">Kempf &amp; Guttman Informational [Page 29]</span></pre>
1621 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-30" ></span>
1622 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1623
1624
1625 SLP_TRUE, asynchronous operations are terminated, synchronous
1626 operations ignore the return (since the operation is already
1627 complete).
1628
1629 <span class="h4"><a class="selflink" id="section-4.3.1" href="#section-4.3.1">4.3.1</a>. SLPRegReport</span>
1630
1631 <span class="h5"><a class="selflink" id="section-4.3.1.1" href="#section-4.3.1.1">4.3.1.1</a>. Synopsis</span>
1632
1633
1634 typedef void SLPRegReport(SLPHandle hSLP,
1635 SLPError errCode,
1636 void *pvCookie);
1637
1638
1639 <span class="h5"><a class="selflink" id="section-4.3.1.2" href="#section-4.3.1.2">4.3.1.2</a>. Description</span>
1640
1641 The SLPRegReport callback type is the type of the callback function
1642 to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions.
1643
1644 <span class="h5"><a class="selflink" id="section-4.3.1.3" href="#section-4.3.1.3">4.3.1.3</a>. Parameters</span>
1645
1646 hSLP
1647
1648 The SLPHandle used to initiate the operation.
1649
1650 errCode
1651
1652 An error code indicating if an error occurred during the
1653 operation.
1654
1655 pvCookie
1656
1657 Memory passed down from the client code that called the
1658 original API function, starting the operation. May be NULL.
1659
1660 <span class="h4"><a class="selflink" id="section-4.3.2" href="#section-4.3.2">4.3.2</a>. SLPSrvTypeCallback</span>
1661
1662 <span class="h5"><a class="selflink" id="section-4.3.2.1" href="#section-4.3.2.1">4.3.2.1</a>. Synopsis</span>
1663
1664 typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,
1665 const char* pcSrvTypes,
1666 SLPError errCode,
1667 void *pvCookie);
1668
1669
1670
1671
1672
1673
1674
1675
1676 <span class="grey">Kempf &amp; Guttman Informational [Page 30]</span></pre>
1677 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-31" ></span>
1678 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1679
1680
1681 <span class="h5"><a class="selflink" id="section-4.3.2.2" href="#section-4.3.2.2">4.3.2.2</a>. Description</span>
1682
1683 The SLPSrvTypeCallback type is the type of the callback function
1684 parameter to SLPFindSrvTypes() function. If the hSLP handle
1685 parameter was opened asynchronously, the results returned through the
1686 callback MAY be uncollated. If the hSLP handle parameter was opened
1687 synchronously, then the returned results must be collated and
1688 duplicates eliminated.
1689
1690 <span class="h5"><a class="selflink" id="section-4.3.2.3" href="#section-4.3.2.3">4.3.2.3</a>. Parameters</span>
1691
1692 hSLP
1693
1694 The SLPHandle used to initiate the operation.
1695
1696 pcSrvTypes
1697
1698 A character buffer containing a comma separated, null
1699 terminated list of service types.
1700
1701 errCode
1702
1703 An error code indicating if an error occurred during the
1704 operation. The callback should check this error code before
1705 processing the parameters. If the error code is other than
1706 SLP_OK, then the API library may choose to terminate the
1707 outstanding operation.
1708
1709 pvCookie
1710
1711 Memory passed down from the client code that called the
1712 original API function, starting the operation. May be NULL.
1713
1714 <span class="h5"><a class="selflink" id="section-4.3.2.4" href="#section-4.3.2.4">4.3.2.4</a>. Returns</span>
1715
1716 The client code should return SLP_TRUE if more data is desired,
1717 otherwise SLP_FALSE.
1718
1719 <span class="h4"><a class="selflink" id="section-4.3.3" href="#section-4.3.3">4.3.3</a>. SLPSrvURLCallback</span>
1720
1721 <span class="h5"><a class="selflink" id="section-4.3.3.1" href="#section-4.3.3.1">4.3.3.1</a>. Synopsis</span>
1722
1723
1724 typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP,
1725 const char* pcSrvURL,
1726 unsigned short sLifetime,
1727 SLPError errCode,
1728 void *pvCookie);
1729
1730
1731
1732 <span class="grey">Kempf &amp; Guttman Informational [Page 31]</span></pre>
1733 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-32" ></span>
1734 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1735
1736
1737 <span class="h5"><a class="selflink" id="section-4.3.3.2" href="#section-4.3.3.2">4.3.3.2</a>. Description</span>
1738
1739 The SLPSrvURLCallback type is the type of the callback function
1740 parameter to SLPFindSrvs() function. If the hSLP handle parameter
1741 was opened asynchronously, the results returned through the callback
1742 MAY be uncollated. If the hSLP handle parameter was opened
1743 synchronously, then the returned results must be collated and
1744 duplicates eliminated.
1745
1746 <span class="h5"><a class="selflink" id="section-4.3.3.3" href="#section-4.3.3.3">4.3.3.3</a>. Parameters</span>
1747
1748 hSLP
1749
1750 The SLPHandle used to initiate the operation.
1751
1752 pcSrvURL
1753
1754 A character buffer containing the returned service URL.
1755
1756 sLifetime
1757
1758 An unsigned short giving the life time of the service
1759 advertisement, in seconds. The value must be an unsigned
1760 integer less than or equal to SLP_LIFETIME_MAXIMUM.
1761
1762 errCode
1763
1764 An error code indicating if an error occurred during the
1765 operation. The callback should check this error code before
1766 processing the parameters. If the error code is other than
1767 SLP_OK, then the API library may choose to terminate the
1768 outstanding operation.
1769
1770 pvCookie
1771
1772 Memory passed down from the client code that called the
1773 original API function, starting the operation. May be NULL.
1774
1775 <span class="h5"><a class="selflink" id="section-4.3.3.4" href="#section-4.3.3.4">4.3.3.4</a>. Returns</span>
1776
1777 The client code should return SLP_TRUE if more data is desired,
1778 otherwise SLP_FALSE.
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788 <span class="grey">Kempf &amp; Guttman Informational [Page 32]</span></pre>
1789 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-33" ></span>
1790 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1791
1792
1793 <span class="h4"><a class="selflink" id="section-4.3.4" href="#section-4.3.4">4.3.4</a>. SLPAttrCallback</span>
1794
1795 <span class="h5"><a class="selflink" id="section-4.3.4.1" href="#section-4.3.4.1">4.3.4.1</a>. Synopsis</span>
1796
1797
1798 typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP,
1799 const char* pcAttrList,
1800 SLPError errCode,
1801 void *pvCookie);
1802
1803
1804 <span class="h5"><a class="selflink" id="section-4.3.4.2" href="#section-4.3.4.2">4.3.4.2</a>. Description</span>
1805
1806 The SLPAttrCallback type is the type of the callback function
1807 parameter to SLPFindAttrs() function.
1808
1809 The behavior of the callback differs depending on whether the
1810 attribute request was by URL or by service type. If the
1811 SLPFindAttrs() operation was originally called with a URL, the
1812 callback is called once regardless of whether the handle was opened
1813 asynchronously or synchronously. The pcAttrList parameter contains
1814 the requested attributes as a comma separated list (or is empty if no
1815 attributes matched the original tag list).
1816
1817 If the SLPFindAttrs() operation was originally called with a service
1818 type, the value of pcAttrList and calling behavior depend on whether
1819 the handle was opened asynchronously or synchronously. If the handle
1820 was opened asynchronously, the callback is called every time the API
1821 library has results from a remote agent. The pcAttrList parameter
1822 MAY be uncollated between calls. It contains a comma separated list
1823 with the results from the agent that immediately returned results.
1824 If the handle was opened synchronously, the results must be collated
1825 from all returning agents and the callback is called once, with the
1826 pcAttrList parameter set to the collated result.
1827
1828 <span class="h5"><a class="selflink" id="section-4.3.4.3" href="#section-4.3.4.3">4.3.4.3</a>. Parameters</span>
1829
1830 hSLP
1831
1832 The SLPHandle used to initiate the operation.
1833
1834 pcAttrList
1835
1836 A character buffer containing a comma separated, null
1837 terminated list of attribute id/value assignments, in SLP wire
1838 format; i.e. "(attr-id=attr-value-list)" [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>].
1839
1840
1841
1842
1843
1844 <span class="grey">Kempf &amp; Guttman Informational [Page 33]</span></pre>
1845 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-34" ></span>
1846 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1847
1848
1849 errCode
1850
1851 An error code indicating if an error occurred during the
1852 operation. The callback should check this error code before
1853 processing the parameters. If the error code is other than
1854 SLP_OK, then the API library may choose to terminate the
1855 outstanding operation.
1856
1857 pvCookie
1858
1859 Memory passed down from the client code that called the
1860 original API function, starting the operation. May be NULL.
1861
1862 <span class="h5"><a class="selflink" id="section-4.3.4.4" href="#section-4.3.4.4">4.3.4.4</a>. Returns</span>
1863
1864 The client code should return SLP_TRUE if more data is desired,
1865 otherwise SLP_FALSE.
1866
1867 <span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. Opening and Closing an SLPHandle</span>
1868
1869 <span class="h4"><a class="selflink" id="section-4.4.1" href="#section-4.4.1">4.4.1</a>. SLPOpen</span>
1870
1871 <span class="h5"><a class="selflink" id="section-4.4.1.1" href="#section-4.4.1.1">4.4.1.1</a>. Synopsis</span>
1872
1873 SLPError SLPOpen(const char *pcLang, SLPBoolean isAsync, SLPHandle
1874 *phSLP);
1875
1876 <span class="h5"><a class="selflink" id="section-4.4.1.2" href="#section-4.4.1.2">4.4.1.2</a>. Description</span>
1877
1878 Returns a SLPHandle handle in the phSLP parameter for the language
1879 locale passed in as the pcLang parameter. The client indicates if
1880 operations on the handle are to be synchronous or asynchronous
1881 through the isAsync parameter. The handle encapsulates the language
1882 locale for SLP requests issued through the handle, and any other
1883 resources required by the implementation. However, SLP properties
1884 are not encapsulated by the handle; they are global. The return
1885 value of the function is an SLPError code indicating the status of
1886 the operation. Upon failure, the phSLP parameter is NULL.
1887
1888 An SLPHandle can only be used for one SLP API operation at a time.
1889 If the original operation was started asynchronously, any attempt to
1890 start an additional operation on the handle while the original
1891 operation is pending results in the return of an SLP_HANDLE_IN_USE
1892 error from the API function. The SLPClose() API function terminates
1893 any outstanding calls on the handle. If an implementation is unable
1894 to support a asynchronous( resp. synchronous) operation, due to
1895 memory constraints or lack of threading support, the
1896 SLP_NOT_IMPLEMENTED flag may be returned when the isAsync flag is
1897
1898
1899
1900 <span class="grey">Kempf &amp; Guttman Informational [Page 34]</span></pre>
1901 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-35" ></span>
1902 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1903
1904
1905 SLP_TRUE (resp. SLP_FALSE).
1906
1907 <span class="h5"><a class="selflink" id="section-4.4.1.3" href="#section-4.4.1.3">4.4.1.3</a>. Parameters</span>
1908
1909 pcLang
1910
1911 A pointer to an array of characters containing the <a href="./rfc1766">RFC 1766</a>
1912 Language Tag [<a href="#ref-6" title="&quot;Tags for the Identification of Languages&quot;">6</a>] for the natural language locale of requests
1913 and registrations issued on the handle.
1914
1915 isAsync
1916
1917 An SLPBoolean indicating whether the SLPHandle should be opened
1918 for asynchronous operation or not.
1919
1920 phSLP
1921
1922 A pointer to an SLPHandle, in which the open SLPHandle is
1923 returned. If an error occurs, the value upon return is NULL.
1924
1925 <span class="h4"><a class="selflink" id="section-4.4.2" href="#section-4.4.2">4.4.2</a>. SLPClose</span>
1926
1927 <span class="h5"><a class="selflink" id="section-4.4.2.1" href="#section-4.4.2.1">4.4.2.1</a>. Synopsis</span>
1928
1929
1930 void SLPClose(SLPHandle hSLP);
1931
1932
1933 <span class="h5"><a class="selflink" id="section-4.4.2.2" href="#section-4.4.2.2">4.4.2.2</a>. Description</span>
1934
1935 Frees all resources associated with the handle. If the handle was
1936 invalid, the function returns silently. Any outstanding synchronous
1937 or asynchronous operations are cancelled so their callback functions
1938 will not be called any further.
1939
1940 <span class="h5"><a class="selflink" id="section-4.4.2.3" href="#section-4.4.2.3">4.4.2.3</a>. Parameters</span>
1941
1942 SLPHandle
1943
1944 A SLPHandle handle returned from a call to SLPOpen().
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956 <span class="grey">Kempf &amp; Guttman Informational [Page 35]</span></pre>
1957 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-36" ></span>
1958 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
1959
1960
1961 <span class="h3"><a class="selflink" id="section-4.5" href="#section-4.5">4.5</a>. Protocol API</span>
1962
1963 <span class="h4"><a class="selflink" id="section-4.5.1" href="#section-4.5.1">4.5.1</a>. SLPReg</span>
1964
1965 <span class="h5"><a class="selflink" id="section-4.5.1.1" href="#section-4.5.1.1">4.5.1.1</a>. Synopsis</span>
1966
1967
1968 SLPError SLPReg(SLPHandle hSLP,
1969 const char *pcSrvURL,
1970 const unsigned short usLifetime,
1971 const char *pcSrvType,
1972 const char *pcAttrs
1973 SLPBoolean fresh,
1974 SLPRegReport callback,
1975 void *pvCookie);
1976
1977
1978 <span class="h5"><a class="selflink" id="section-4.5.1.2" href="#section-4.5.1.2">4.5.1.2</a>. Description</span>
1979
1980 Registers the URL in pcSrvURL having the lifetime usLifetime with the
1981 attribute list in pcAttrs. The pcAttrs list is a comma separated
1982 list of attribute assignments in the wire format (including escaping
1983 of reserved characters). The usLifetime parameter must be nonzero
1984 and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is
1985 SLP_TRUE, then the registration is new (the SLP protocol FRESH flag
1986 is set) and the registration replaces any existing registrations.
1987 The pcSrvType parameter is a service type name and can be included
1988 for service URLs that are not in the service: scheme. If the URL is
1989 in the service: scheme, the pcSrvType parameter is ignored. If the
1990 fresh flag is SLP_FALSE, then an existing registration is updated.
1991 Rules for new and updated registrations, and the format for pcAttrs
1992 and pcScopeList can be found in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. Registrations and updates take
1993 place in the language locale of the hSLP handle.
1994
1995 The API library is required to perform the operation in all scopes
1996 obtained through configuration.
1997
1998 <span class="h5"><a class="selflink" id="section-4.5.1.3" href="#section-4.5.1.3">4.5.1.3</a>. Parameters</span>
1999
2000 hSLP
2001
2002 The language specific SLPHandle on which to register the
2003 advertisement.
2004
2005 pcSrvURL
2006
2007 The URL to register. May not be the empty string.
2008
2009
2010
2011
2012 <span class="grey">Kempf &amp; Guttman Informational [Page 36]</span></pre>
2013 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-37" ></span>
2014 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2015
2016
2017 usLifetime
2018
2019 An unsigned short giving the life time of the service
2020 advertisement, in seconds. The value must be an unsigned
2021 integer less than or equal to SLP_LIFETIME_MAXIMUM and greater
2022 than zero.
2023
2024 pcSrvType
2025
2026 The service type. If pURL is a service: URL, then this
2027 parameter is ignored.
2028
2029 pcAttrs
2030
2031 A comma separated list of attribute assignment expressions for
2032 the attributes of the advertisement. Use empty string, "" for
2033 no attributes.
2034
2035 fresh
2036
2037 An SLPBoolean that is SLP_TRUE if the registration is new or
2038 SLP_FALSE if a reregistration.
2039
2040 callback
2041
2042 A callback to report the operation completion status.
2043
2044 pvCookie
2045
2046 Memory passed to the callback code from the client. May be
2047 NULL.
2048
2049 <span class="h5"><a class="selflink" id="section-4.5.1.4" href="#section-4.5.1.4">4.5.1.4</a>. Returns</span>
2050
2051 If an error occurs in starting the operation, one of the SLPError
2052 codes is returned.
2053
2054 <span class="h4"><a class="selflink" id="section-4.5.2" href="#section-4.5.2">4.5.2</a>. SLPDereg</span>
2055
2056 <span class="h5"><a class="selflink" id="section-4.5.2.1" href="#section-4.5.2.1">4.5.2.1</a>. Synopsis</span>
2057
2058
2059 SLPError SLPDereg(SLPHandle hSLP,
2060 const char *pcURL,
2061 SLPRegReport callback,
2062 void *pvCookie);
2063
2064
2065
2066
2067
2068 <span class="grey">Kempf &amp; Guttman Informational [Page 37]</span></pre>
2069 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-38" ></span>
2070 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2071
2072
2073 <span class="h5"><a class="selflink" id="section-4.5.2.2" href="#section-4.5.2.2">4.5.2.2</a>. Description</span>
2074
2075 Deregisters the advertisement for URL pcURL in all scopes where the
2076 service is registered and all language locales. The deregistration
2077 is not just confined to the locale of the SLPHandle, it is in all
2078 locales. The API library is required to perform the operation in all
2079 scopes obtained through configuration.
2080
2081 <span class="h5"><a class="selflink" id="section-4.5.2.3" href="#section-4.5.2.3">4.5.2.3</a>. Parameters</span>
2082
2083 hSLP
2084
2085 The language specific SLPHandle to use for deregistering.
2086
2087 pcURL
2088
2089 The URL to deregister. May not be the empty string.
2090
2091 callback
2092
2093 A callback to report the operation completion status.
2094
2095 pvCookie
2096
2097 Memory passed to the callback code from the client. May be
2098 NULL.
2099
2100 <span class="h5"><a class="selflink" id="section-4.5.2.4" href="#section-4.5.2.4">4.5.2.4</a>. Returns</span>
2101
2102 If an error occurs in starting the operation, one of the SLPError
2103 codes is returned.
2104
2105 <span class="h4"><a class="selflink" id="section-4.5.3" href="#section-4.5.3">4.5.3</a>. SLPDelAttrs</span>
2106
2107 <span class="h5"><a class="selflink" id="section-4.5.3.1" href="#section-4.5.3.1">4.5.3.1</a>. Synopsis</span>
2108
2109
2110 SLPError SLPDelAttrs(SLPHandle hSLP,
2111 const char *pcURL,
2112 const char *pcAttrs,
2113 SLPRegReport callback,
2114 void *pvCookie);
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124 <span class="grey">Kempf &amp; Guttman Informational [Page 38]</span></pre>
2125 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-39" ></span>
2126 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2127
2128
2129 <span class="h5"><a class="selflink" id="section-4.5.3.2" href="#section-4.5.3.2">4.5.3.2</a>. Description</span>
2130
2131 Delete the selected attributes in the locale of the SLPHandle. The
2132 API library is required to perform the operation in all scopes
2133 obtained through configuration.
2134
2135 <span class="h5"><a class="selflink" id="section-4.5.3.3" href="#section-4.5.3.3">4.5.3.3</a>. Parameters</span>
2136
2137 hSLP
2138
2139 The language specific SLPHandle to use for deleting attributes.
2140
2141 pcURL
2142
2143 The URL of the advertisement from which the attributes should
2144 be deleted. May not be the empty string.
2145
2146 pcAttrs
2147
2148 A comma separated list of attribute ids for the attributes to
2149 deregister. See Section 9.8 in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for a description of the
2150 list format. May not be the empty string.
2151
2152 callback
2153
2154 A callback to report the operation completion status.
2155
2156 pvCookie
2157
2158 Memory passed to the callback code from the client. May be
2159 NULL.
2160
2161 <span class="h5"><a class="selflink" id="section-4.5.3.4" href="#section-4.5.3.4">4.5.3.4</a>. Returns</span>
2162
2163 If an error occurs in starting the operation, one of the SLPError
2164 codes is returned.
2165
2166 <span class="h4"><a class="selflink" id="section-4.5.4" href="#section-4.5.4">4.5.4</a>. SLPFindSrvTypes</span>
2167
2168 <span class="h5"><a class="selflink" id="section-4.5.4.1" href="#section-4.5.4.1">4.5.4.1</a>. Synopsis</span>
2169
2170
2171 SLPError SLPFindSrvTypes(SLPHandle hSLP,
2172 const char *pcNamingAuthority,
2173 const char *pcScopeList,
2174 SLPSrvTypeCallback callback,
2175 void *pvCookie);
2176
2177
2178
2179
2180 <span class="grey">Kempf &amp; Guttman Informational [Page 39]</span></pre>
2181 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-40" ></span>
2182 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2183
2184
2185 The SLPFindSrvType() function issues an SLP service type request for
2186 service types in the scopes indicated by the pcScopeList. The
2187 results are returned through the callback parameter. The service
2188 types are independent of language locale, but only for services
2189 registered in one of scopes and for the indicated naming authority.
2190
2191 If the naming authority is "*", then results are returned for all
2192 naming authorities. If the naming authority is the empty string,
2193 i.e. "", then the default naming authority, "IANA", is used. "IANA"
2194 is not a valid naming authority name, and it is a PARAMETER_BAD error
2195 to include it explicitly.
2196
2197 The service type names are returned with the naming authority intact.
2198 If the naming authority is the default (i.e. empty string) then it
2199 is omitted, as is the separating ".". Service type names from URLs
2200 of the service: scheme are returned with the "service:" prefix
2201 intact. [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] See [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for more information on the syntax of service
2202 type names.
2203
2204 <span class="h5"><a class="selflink" id="section-4.5.4.2" href="#section-4.5.4.2">4.5.4.2</a>. Parameters</span>
2205
2206 hSLP
2207
2208 The SLPHandle on which to search for types.
2209
2210 pcNamingAuthority
2211
2212 The naming authority to search. Use "*" for all naming
2213 authorities and the empty string, "", for the default naming
2214 authority.
2215
2216 pcScopeList
2217
2218 A pointer to a char containing comma separated list of scope
2219 names to search for service types. May not be the empty
2220 string, "".
2221
2222 callback
2223
2224 A callback function through which the results of the operation
2225 are reported.
2226
2227 pvCookie
2228
2229 Memory passed to the callback code from the client. May be
2230 NULL.
2231
2232
2233
2234
2235
2236 <span class="grey">Kempf &amp; Guttman Informational [Page 40]</span></pre>
2237 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-41" ></span>
2238 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2239
2240
2241 <span class="h5"><a class="selflink" id="section-4.5.4.3" href="#section-4.5.4.3">4.5.4.3</a>. Returns</span>
2242
2243 If an error occurs in starting the operation, one of the SLPError
2244 codes is returned.
2245
2246 <span class="h4"><a class="selflink" id="section-4.5.5" href="#section-4.5.5">4.5.5</a>. SLPFindSrvs</span>
2247
2248 <span class="h5"><a class="selflink" id="section-4.5.5.1" href="#section-4.5.5.1">4.5.5.1</a>. Synopsis</span>
2249
2250
2251 SLPError SLPFindSrvs(SLPHandle hSLP,
2252 const char *pcServiceType,
2253 const char *pcScopeList,
2254 const char *pcSearchFilter,
2255 SLPSrvURLCallback callback,
2256 void *pvCookie);
2257
2258
2259 <span class="h5"><a class="selflink" id="section-4.5.5.2" href="#section-4.5.5.2">4.5.5.2</a>. Description</span>
2260
2261 Issue the query for services on the language specific SLPHandle and
2262 return the results through the callback. The parameters determine
2263 the results
2264
2265 <span class="h5"><a class="selflink" id="section-4.5.5.3" href="#section-4.5.5.3">4.5.5.3</a>. Parameters</span>
2266
2267 hSLP
2268
2269 The language specific SLPHandle on which to search for
2270 services.
2271
2272 pcServiceType
2273
2274 The Service Type String, including authority string if any, for
2275 the request, such as can be discovered using SLPSrvTypes().
2276 This could be, for example "service:printer:lpr" or
2277 "service:nfs". May not be the empty string.
2278
2279 pcScopeList
2280
2281 A pointer to a char containing comma separated list of scope
2282 names. May not be the empty string, "".
2283
2284 pcSearchFilter
2285
2286 A query formulated of attribute pattern matching expressions in
2287 the form of a LDAPv3 Search Filter, see [<a href="#ref-4" title="&quot;The String Representation of LDAP Search Filters&quot;">4</a>]. If this filter
2288 is empty, i.e. "", all services of the requested type in the
2289
2290
2291
2292 <span class="grey">Kempf &amp; Guttman Informational [Page 41]</span></pre>
2293 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-42" ></span>
2294 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2295
2296
2297 specified scopes are returned.
2298
2299 callback
2300
2301 A callback function through which the results of the operation
2302 are reported.
2303
2304 pvCookie
2305
2306 Memory passed to the callback code from the client. May be
2307 NULL.
2308
2309 <span class="h5"><a class="selflink" id="section-4.5.5.4" href="#section-4.5.5.4">4.5.5.4</a>. Returns</span>
2310
2311 If an error occurs in starting the operation, one of the SLPError
2312 codes is returned.
2313
2314 <span class="h4"><a class="selflink" id="section-4.5.6" href="#section-4.5.6">4.5.6</a>. SLPFindAttrs</span>
2315
2316 <span class="h5"><a class="selflink" id="section-4.5.6.1" href="#section-4.5.6.1">4.5.6.1</a>. Synopsis</span>
2317
2318
2319 SLPError SLPFindAttrs(SLPHandle hSLP,
2320 const char *pcURLOrServiceType,
2321 const char *pcScopeList,
2322 const char *pcAttrIds,
2323 SLPAttrCallback callback,
2324 void *pvCookie);
2325
2326
2327 <span class="h5"><a class="selflink" id="section-4.5.6.2" href="#section-4.5.6.2">4.5.6.2</a>. Description</span>
2328
2329 This function returns service attributes matching the attribute ids
2330 for the indicated service URL or service type. If pcURLOrServiceType
2331 is a service URL, the attribute information returned is for that
2332 particular advertisement in the language locale of the SLPHandle.
2333
2334 If pcURLOrServiceType is a service type name (including naming
2335 authority if any), then the attributes for all advertisements of that
2336 service type are returned regardless of the language of registration.
2337 Results are returned through the callback.
2338
2339 The result is filtered with an SLP attribute request filter string
2340 parameter, the syntax of which is described in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]. If the filter
2341 string is the empty string, i.e. "", all attributes are returned.
2342
2343
2344
2345
2346
2347
2348 <span class="grey">Kempf &amp; Guttman Informational [Page 42]</span></pre>
2349 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-43" ></span>
2350 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2351
2352
2353 <span class="h5"><a class="selflink" id="section-4.5.6.3" href="#section-4.5.6.3">4.5.6.3</a>. Parameters</span>
2354
2355 hSLP
2356
2357 The language specific SLPHandle on which to search for
2358 attributes.
2359
2360 pcURLOrServiceType
2361
2362 The service URL or service type. See [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for URL and service
2363 type syntax. May not be the empty string.
2364
2365 pcScopeList
2366
2367 A pointer to a char containing a comma separated list of scope
2368 names. May not be the empty string, "".
2369
2370 pcAttrIds
2371
2372 The filter string indicating which attribute values to return.
2373 Use empty string, "", to indicate all values. Wildcards
2374 matching all attribute ids having a particular prefix or suffix
2375 are also possible. See [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for the exact format of the filter
2376 string.
2377
2378 callback
2379
2380 A callback function through which the results of the operation
2381 are reported.
2382
2383 pvCookie
2384
2385 Memory passed to the callback code from the client. May be
2386 NULL.
2387
2388 <span class="h5"><a class="selflink" id="section-4.5.6.4" href="#section-4.5.6.4">4.5.6.4</a>. Returns</span>
2389
2390 If an error occurs in starting the operation, one of the SLPError
2391 codes is returned.
2392
2393 <span class="h3"><a class="selflink" id="section-4.6" href="#section-4.6">4.6</a>. Miscellaneous Functions</span>
2394
2395 <span class="h4"><a class="selflink" id="section-4.6.1" href="#section-4.6.1">4.6.1</a>. SLPGetRefreshInterval</span>
2396
2397 <span class="h5"><a class="selflink" id="section-4.6.1.1" href="#section-4.6.1.1">4.6.1.1</a>. Synopsis</span>
2398
2399
2400 unsigned short SLPGetRefreshInterval();
2401
2402
2403
2404 <span class="grey">Kempf &amp; Guttman Informational [Page 43]</span></pre>
2405 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-44" ></span>
2406 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2407
2408
2409 <span class="h5"><a class="selflink" id="section-4.6.1.2" href="#section-4.6.1.2">4.6.1.2</a>. Description</span>
2410
2411 Returns the maximum across all DAs of the min-refresh-interval
2412 attribute. This value satisfies the advertised refresh interval
2413 bounds for all DAs, and, if used by the SA, assures that no refresh
2414 registration will be rejected. If no DA advertises a min-refresh-
2415 interval attribute, a value of 0 is returned.
2416
2417 <span class="h5"><a class="selflink" id="section-4.6.1.3" href="#section-4.6.1.3">4.6.1.3</a>. Returns</span>
2418
2419 If no error, the maximum refresh interval value allowed by all DAs (a
2420 positive integer). If no DA advertises a min-refresh-interval
2421 attribute, returns 0. If an error occurs, returns an SLP error code.
2422
2423 <span class="h4"><a class="selflink" id="section-4.6.2" href="#section-4.6.2">4.6.2</a>. SLPFindScopes</span>
2424
2425 <span class="h5"><a class="selflink" id="section-4.6.2.1" href="#section-4.6.2.1">4.6.2.1</a>. Synopsis</span>
2426
2427
2428 SLPError SLPFindScopes(SLPHandle hSLP,
2429 char** ppcScopeList);
2430
2431
2432 <span class="h5"><a class="selflink" id="section-4.6.2.2" href="#section-4.6.2.2">4.6.2.2</a>. Description</span>
2433
2434 Sets ppcScopeList parameter to a pointer to a comma separated list
2435 including all available scope values. The list of scopes comes from
2436 a variety of sources: the configuration file's net.slp.useScopes
2437 property, unicast to DAs on the net.slp.DAAddresses property, DHCP,
2438 or through the DA discovery process. If there is any order to the
2439 scopes, preferred scopes are listed before less desirable scopes.
2440 There is always at least one name in the list, the default scope,
2441 "DEFAULT".
2442
2443 <span class="h5"><a class="selflink" id="section-4.6.2.3" href="#section-4.6.2.3">4.6.2.3</a>. Parameters</span>
2444
2445 hSLP
2446
2447 The SLPHandle on which to search for scopes.
2448
2449 ppcScopeList
2450
2451 A pointer to char pointer into which the buffer pointer is
2452 placed upon return. The buffer is null terminated. The memory
2453 should be freed by calling SLPFree().
2454
2455
2456
2457
2458
2459
2460 <span class="grey">Kempf &amp; Guttman Informational [Page 44]</span></pre>
2461 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-45" ></span>
2462 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2463
2464
2465 <span class="h5"><a class="selflink" id="section-4.6.2.4" href="#section-4.6.2.4">4.6.2.4</a>. Returns</span>
2466
2467 If no error occurs, returns SLP_OK, otherwise, the appropriate error
2468 code.
2469
2470 <span class="h4"><a class="selflink" id="section-4.6.3" href="#section-4.6.3">4.6.3</a>. SLPParseSrvURL</span>
2471
2472 <span class="h5"><a class="selflink" id="section-4.6.3.1" href="#section-4.6.3.1">4.6.3.1</a>. Synopsis</span>
2473
2474
2475 SLPError SLPParseSrvURL(char *pcSrvURL
2476 SLPSrvURL** ppSrvURL);
2477
2478
2479 <span class="h5"><a class="selflink" id="section-4.6.3.2" href="#section-4.6.3.2">4.6.3.2</a>. Description</span>
2480
2481 Parses the URL passed in as the argument into a service URL structure
2482 and returns it in the ppSrvURL pointer. If a parse error occurs,
2483 returns SLP_PARSE_ERROR. The input buffer pcSrvURL is destructively
2484 modified during the parse and used to fill in the fields of the
2485 return structure. The structure returned in ppSrvURL should be freed
2486 with SLPFreeURL(). If the URL has no service part, the s_pcSrvPart
2487 string is the empty string, "", i.e. not NULL. If pcSrvURL is not a
2488 service: URL, then the s_pcSrvType field in the returned data
2489 structure is the URL's scheme, which might not be the same as the
2490 service type under which the URL was registered. If the transport is
2491 IP, the s_pcTransport field is the empty string. If the transport is
2492 not IP or there is no port number, the s_iPort field is zero.
2493
2494 <span class="h5"><a class="selflink" id="section-4.6.3.3" href="#section-4.6.3.3">4.6.3.3</a>. Parameters</span>
2495
2496 pcSrvURL
2497
2498 A pointer to a character buffer containing the null terminated
2499 URL string to parse. It is destructively modified to produce
2500 the output structure.
2501
2502 ppSrvURL
2503
2504 A pointer to a pointer for the SLPSrvURL structure to receive
2505 the parsed URL. The memory should be freed by a call to
2506 SLPFree() when no longer needed.
2507
2508 <span class="h5"><a class="selflink" id="section-4.6.3.4" href="#section-4.6.3.4">4.6.3.4</a>. Returns</span>
2509
2510 If no error occurs, the return value is SLP_OK. Otherwise, the
2511 appropriate error code is returned.
2512
2513
2514
2515
2516 <span class="grey">Kempf &amp; Guttman Informational [Page 45]</span></pre>
2517 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-46" ></span>
2518 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2519
2520
2521 <span class="h4"><a class="selflink" id="section-4.6.4" href="#section-4.6.4">4.6.4</a>. SLPEscape</span>
2522
2523 <span class="h5"><a class="selflink" id="section-4.6.4.1" href="#section-4.6.4.1">4.6.4.1</a>. Synopsis</span>
2524
2525
2526 SLPError SLPEscape(const char* pcInbuf,
2527 char** ppcOutBuf,
2528 SLPBoolean isTag);
2529
2530
2531 <span class="h5"><a class="selflink" id="section-4.6.4.2" href="#section-4.6.4.2">4.6.4.2</a>. Description</span>
2532
2533 Process the input string in pcInbuf and escape any SLP reserved
2534 characters. If the isTag parameter is SLPTrue, then look for bad tag
2535 characters and signal an error if any are found by returning the
2536 SLP_PARSE_ERROR code. The results are put into a buffer allocated by
2537 the API library and returned in the ppcOutBuf parameter. This buffer
2538 should be deallocated using SLPFree() when the memory is no longer
2539 needed.
2540
2541 <span class="h5"><a class="selflink" id="section-4.6.4.3" href="#section-4.6.4.3">4.6.4.3</a>. Parameters</span>
2542
2543 pcInbuf
2544
2545 Pointer to he input buffer to process for escape characters.
2546
2547 ppcOutBuf
2548
2549 Pointer to a pointer for the output buffer with the SLP
2550 reserved characters escaped. Must be freed using SLPFree()
2551 when the memory is no longer needed.
2552
2553 isTag
2554
2555 When true, the input buffer is checked for bad tag characters.
2556
2557 <span class="h5"><a class="selflink" id="section-4.6.4.4" href="#section-4.6.4.4">4.6.4.4</a>. Returns</span>
2558
2559 Return SLP_PARSE_ERROR if any characters are bad tag characters and
2560 the isTag flag is true, otherwise SLP_OK, or the appropriate error
2561 code if another error occurs.
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572 <span class="grey">Kempf &amp; Guttman Informational [Page 46]</span></pre>
2573 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-47" ></span>
2574 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2575
2576
2577 <span class="h4"><a class="selflink" id="section-4.6.5" href="#section-4.6.5">4.6.5</a>. SLPUnescape</span>
2578
2579 <span class="h5"><a class="selflink" id="section-4.6.5.1" href="#section-4.6.5.1">4.6.5.1</a>. Synopsis</span>
2580
2581
2582 SLPError SLPUnescape(const char* pcInbuf,
2583 char** ppcOutBuf,
2584 SLPBoolean isTag);
2585
2586
2587 <span class="h5"><a class="selflink" id="section-4.6.5.2" href="#section-4.6.5.2">4.6.5.2</a>. Description</span>
2588
2589 Process the input string in pcInbuf and unescape any SLP reserved
2590 characters. If the isTag parameter is SLPTrue, then look for bad tag
2591 characters and signal an error if any are found with the
2592 SLP_PARSE_ERROR code. No transformation is performed if the input
2593 string is an opaque. The results are put into a buffer allocated by
2594 the API library and returned in the ppcOutBuf parameter. This buffer
2595 should be deallocated using SLPFree() when the memory is no longer
2596 needed.
2597
2598 <span class="h5"><a class="selflink" id="section-4.6.5.3" href="#section-4.6.5.3">4.6.5.3</a>. Parameters</span>
2599
2600 pcInbuf
2601
2602 Pointer to he input buffer to process for escape characters.
2603
2604 ppcOutBuf
2605
2606 Pointer to a pointer for the output buffer with the SLP
2607 reserved characters escaped. Must be freed using SLPFree()
2608 when the memory is no longer needed.
2609
2610 isTag
2611
2612 When true, the input buffer is checked for bad tag characters.
2613
2614 <span class="h5"><a class="selflink" id="section-4.6.5.4" href="#section-4.6.5.4">4.6.5.4</a>. Returns</span>
2615
2616 Return SLP_PARSE_ERROR if any characters are bad tag characters and
2617 the isTag flag is true, otherwise SLP_OK, or the appropriate error
2618 code if another error occurs.
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628 <span class="grey">Kempf &amp; Guttman Informational [Page 47]</span></pre>
2629 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-48" ></span>
2630 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2631
2632
2633 <span class="h4"><a class="selflink" id="section-4.6.6" href="#section-4.6.6">4.6.6</a>. SLPFree</span>
2634
2635 <span class="h5"><a class="selflink" id="section-4.6.6.1" href="#section-4.6.6.1">4.6.6.1</a>. Synopsis</span>
2636
2637
2638 void SLPFree(void* pvMem);
2639
2640
2641 <span class="h5"><a class="selflink" id="section-4.6.6.2" href="#section-4.6.6.2">4.6.6.2</a>. Description</span>
2642
2643 Frees memory returned from SLPParseSrvURL(), SLPFindScopes(),
2644 SLPEscape(), and SLPUnescape().
2645
2646 <span class="h5"><a class="selflink" id="section-4.6.6.3" href="#section-4.6.6.3">4.6.6.3</a>. Parameters</span>
2647
2648 pvMem
2649
2650 A pointer to the storage allocated by the SLPParseSrvURL(),
2651 SLPEscape(), SLPUnescape(), or SLPFindScopes() function.
2652 Ignored if NULL.
2653
2654 <span class="h4"><a class="selflink" id="section-4.6.7" href="#section-4.6.7">4.6.7</a>. SLPGetProperty</span>
2655
2656 <span class="h5"><a class="selflink" id="section-4.6.7.1" href="#section-4.6.7.1">4.6.7.1</a>. Synopsis</span>
2657
2658
2659 const char* SLPGetProperty(const char* pcName);
2660
2661
2662 <span class="h5"><a class="selflink" id="section-4.6.7.2" href="#section-4.6.7.2">4.6.7.2</a>. Description</span>
2663
2664 Returns the value of the corresponding SLP property name. The
2665 returned string is owned by the library and MUST NOT be freed.
2666
2667 <span class="h5"><a class="selflink" id="section-4.6.7.3" href="#section-4.6.7.3">4.6.7.3</a>. Parameters</span>
2668
2669 pcName
2670
2671 Null terminated string with the property name, from
2672 <a href="#section-2.1">Section 2.1</a>.
2673
2674 <span class="h5"><a class="selflink" id="section-4.6.7.4" href="#section-4.6.7.4">4.6.7.4</a>. Returns</span>
2675
2676 If no error, returns a pointer to a character buffer containing the
2677 property value. If the property was not set, returns the default
2678 value. If an error occurs, returns NULL. The returned string MUST
2679 NOT be freed.
2680
2681
2682
2683
2684 <span class="grey">Kempf &amp; Guttman Informational [Page 48]</span></pre>
2685 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-49" ></span>
2686 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2687
2688
2689 <span class="h4"><a class="selflink" id="section-4.6.8" href="#section-4.6.8">4.6.8</a>. SLPSetProperty</span>
2690
2691 <span class="h5"><a class="selflink" id="section-4.6.8.1" href="#section-4.6.8.1">4.6.8.1</a>. Synopsis</span>
2692
2693
2694 void SLPSetProperty(const char *pcName,
2695 const char *pcValue);
2696
2697
2698 <span class="h5"><a class="selflink" id="section-4.6.8.2" href="#section-4.6.8.2">4.6.8.2</a>. Description</span>
2699
2700 Sets the value of the SLP property to the new value. The pcValue
2701 parameter should be the property value as a string.
2702
2703 <span class="h5"><a class="selflink" id="section-4.6.8.3" href="#section-4.6.8.3">4.6.8.3</a>. Parameters</span>
2704
2705 pcName
2706
2707 Null terminated string with the property name, from
2708 <a href="#section-2.1">Section 2.1</a>.
2709
2710 pcValue
2711
2712 Null terminated string with the property value, in UTF-8
2713 character encoding.
2714
2715 <span class="h3"><a class="selflink" id="section-4.7" href="#section-4.7">4.7</a>. Implementation Notes</span>
2716
2717 <span class="h4"><a class="selflink" id="section-4.7.1" href="#section-4.7.1">4.7.1</a>. Refreshing Registrations</span>
2718
2719 Clients indicate that they want URLs to be automatically refreshed by
2720 setting the usLifetime parameter in the SLPReg() function call to
2721 SLP_LIFETIME_MAXIMUM. This will cause the API implementation to
2722 refresh the URL before it times out. Although using
2723 SLP_LIFETIME_MAXIMUM to designate automatic reregistration means that
2724 a transient URL can't be registered for the maximum lifetime, little
2725 hardship is likely to occur, since service URL lifetimes are measured
2726 in seconds and the client can simply use a lifetime of
2727 SLP_LIFETIME_MAXIMUM - 1 if a transient URL near the maximum lifetime
2728 is desired. API implementations MUST provide this facility.
2729
2730 <span class="h4"><a class="selflink" id="section-4.7.2" href="#section-4.7.2">4.7.2</a>. Syntax for String Parameters</span>
2731
2732 Query strings, attribute registration lists, attribute deregistration
2733 lists, scope lists, and attribute selection lists follow the syntax
2734 described in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for the appropriate requests. The API directly
2735 reflects the strings passed in from clients into protocol requests,
2736 and directly reflects out strings returned from protocol replies to
2737
2738
2739
2740 <span class="grey">Kempf &amp; Guttman Informational [Page 49]</span></pre>
2741 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-50" ></span>
2742 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2743
2744
2745 clients. As a consequence, clients are responsible for formatting
2746 request strings, including escaping and converting opaque values to
2747 escaped byte encoded strings. Similarly, on output, clients are
2748 required to unescape strings and convert escaped string encoded
2749 opaques to binary. The functions SLPEscape() and SLPUnescape() can
2750 be used for escaping SLP reserved characters, but perform no opaque
2751 processing.
2752
2753 Opaque values consist of a character buffer containing a UTF-8-
2754 encoded string, the first characters of which are the nonUTF-8
2755 encoding '\ff'. Subsequent characters are the escaped values for the
2756 original bytes in the opaque. The escape convention is relatively
2757 simple. An escape consists of a backslash followed by the two
2758 hexadecimal digits encoding the byte. An example is '\2c' for the
2759 byte 0x2c. Clients handle opaque processing themselves, since the
2760 algorithm is relatively simple and uniform.
2761
2762 <span class="h4"><a class="selflink" id="section-4.7.3" href="#section-4.7.3">4.7.3</a>. Client Side Syntax Checking</span>
2763
2764 Client side API implementations may do syntax checking of scope
2765 names, naming authority names, and service type names, but are not
2766 required to do so. Since the C API is designed to be a thin layer
2767 over the protocol, some low memory SA implementations may find
2768 extensive syntax checking on the client side to be burdensome. If
2769 syntax checking uncovers an error in a parameter, the
2770 SLP_PARAMETER_BAD error must be returned. If any parameter is NULL
2771 and is required to be nonNULL, SLP_PARAMETER_BAD is returned.
2772
2773 <span class="h4"><a class="selflink" id="section-4.7.4" href="#section-4.7.4">4.7.4</a>. System Properties</span>
2774
2775 The system properties established in the configuration file are
2776 accessible through the SLPGetProperty() and SLPSetProperty()
2777 functions. The SLPSetProperty() function only modifies properties in
2778 the running process, not in the configuration file. Properties are
2779 global to the process, affecting all threads and all handles created
2780 with SLPOpen. Errors are checked when the property is used and, as
2781 with parsing the configuration file, are logged. Program execution
2782 continues without interruption by substituting the default for the
2783 erroneous parameter. With the exception of net.slp.locale,
2784 net.slp.typeHint, and net.slp.maxResults, clients of the API should
2785 rarely be required to override these properties, since they reflect
2786 properties of the SLP network that are not of concern to individual
2787 agents. If changes are required, system administrators should modify
2788 the configuration file.
2789
2790
2791
2792
2793
2794
2795
2796 <span class="grey">Kempf &amp; Guttman Informational [Page 50]</span></pre>
2797 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-51" ></span>
2798 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2799
2800
2801 <span class="h4"><a class="selflink" id="section-4.7.5" href="#section-4.7.5">4.7.5</a>. Memory Management</span>
2802
2803 The only API functions returning memory specifically requiring
2804 deallocation on the part of the client are SLPParseSrvURL(),
2805 SLPFindScopes(), SLPEscape(), and SLPUnescape(). This memory should
2806 be freed using SLPFree() when no longer needed. Character strings
2807 returned via the SLPGetProperty() function should NOT be freed, they
2808 are owned by the SLP library.
2809
2810 Memory passed to callbacks belongs to the library and MUST NOT be
2811 retained by the client code. Otherwise, crashes are possible.
2812 Clients are required to copy data out of the callback parameters. No
2813 other use of the parameter memory in callback parameters is allowed.
2814
2815 <span class="h4"><a class="selflink" id="section-4.7.6" href="#section-4.7.6">4.7.6</a>. Asynchronous and Incremental Return Semantics</span>
2816
2817 If a handle parameter to an API function was opened asynchronously,
2818 API function calls on the handle check the other parameters, open the
2819 appropriate operation and return immediately. In an error occurs in
2820 the process of starting the operation, an error code is returned. If
2821 the handle parameter was opened synchronously, the API function call
2822 blocks until all results are available, and returns only after the
2823 results are reported through the callback function. The return code
2824 indicates whether any errors occurred both starting and during the
2825 operation.
2826
2827 The callback function is called whenever the API library has results
2828 to report. The callback code is required to check the error code
2829 parameter before looking at the other parameters. If the error code
2830 is not SLP_OK, the other parameters may be invalid. The API library
2831 has the option of terminating any outstanding operation on which an
2832 error occurs. The callback code can similarly indicate that the
2833 operation should be terminated by passing back SLP_FALSE. Callback
2834 functions are not permitted to recursively call into the API on the
2835 same SLPHandle. If an attempt is made to recursively call into the
2836 API, the API function returns SLP_HANDLE_IN_USE. Prohibiting
2837 recursive callbacks on the same handle simplifies implementation of
2838 thread safe code, since locks held on the handle will not be in place
2839 during a second outcall on the handle. On the other hand, it means
2840 that handle creation should be fairly lightweight so a client program
2841 can easily support multiple outstanding calls.
2842
2843 The total number of results received can be controlled by setting the
2844 net.slp.maxResults parameter.
2845
2846 On the last call to a callback, whether asynchronous or synchronous,
2847 the status code passed to the callback has value SLP_LAST_CALL. There
2848 are four reasons why the call can terminate:
2849
2850
2851
2852 <span class="grey">Kempf &amp; Guttman Informational [Page 51]</span></pre>
2853 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-52" ></span>
2854 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2855
2856
2857 DA reply received
2858
2859 A reply from a DA has been received and therefore nothing more
2860 is expected.
2861
2862 Multicast terminated
2863
2864 The multicast convergence time has elapsed and the API library
2865 multicast code is giving up.
2866
2867 Multicast null results
2868
2869 Nothing new has been received during multicast for a while and
2870 the API library multicast code is giving up on that (as an
2871 optimization).
2872
2873 Maximum results
2874
2875 The user has set the net.slp.maxResults property and that
2876 number of replies has been collected and returned
2877
2878 <span class="h3"><a class="selflink" id="section-4.8" href="#section-4.8">4.8</a>. Example</span>
2879
2880 This example illustrates how to discover a mailbox.
2881
2882 A POP3 server registers itself with the SLP framework. The
2883 attributes it registers are "USER", a list of all users whose mail is
2884 available through the POP3 server.
2885
2886 The POP3 server code is the following:
2887
2888 SLPHandle slph;
2889 SLPRegReport errCallback = POPRegErrCallback;
2890
2891 /* Create an English SLPHandle, asynchronous processing. */
2892
2893 SLPError err = SLPOpen("en", SLP_TRUE, &amp;slph);
2894
2895 if( err != SLP_OK ) {
2896
2897 /* Deal with error. */
2898
2899 }
2900
2901 /* Create the service: URL and attribute parameters. */
2902
2903 const char* surl = "service:pop3://mail.netsurf.de"; /* the URL */
2904
2905
2906
2907
2908 <span class="grey">Kempf &amp; Guttman Informational [Page 52]</span></pre>
2909 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-53" ></span>
2910 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2911
2912
2913 const char *pcAttrs = "(user=zaphod,trillian,roger,marvin)"
2914
2915 /* Perform the registration. */
2916
2917 err = SLPReg(slph,
2918 surl,
2919 SLP_LIFETIME_DEFAULT,
2920 ppcAttrs,
2921 errCallback,
2922 NULL);
2923
2924 if (err != SLP_OK ) {
2925
2926 /*Deal with error.*/
2927
2928 }
2929
2930
2931 The errCallback reports any errors:
2932
2933 void
2934 POPRegErrCallback(SLPHandle hSLP,
2935 SLPError errCode,
2936 unsigned short usLifetime,
2937 void* pvCookie) {
2938
2939 if( errCode != SLP_OK ) {
2940
2941 /* Report error through a dialog, message, etc. */
2942
2943 }
2944
2945 /*Use lifetime interval to update periodically. */
2946
2947 }
2948
2949 The POP3 client locates the server for the user with the following
2950 code:
2951
2952 /*
2953 * The client calls SLPOpen(), exactly as above.
2954 */
2955
2956 const char *pcSrvType = "service:pop3"; /* the service type */
2957 const char *pcScopeList = "default"; /* the scope */
2958 const char *pcFilter = "(user=roger)"; /* the search filter */
2959 SLPSrvURLCallback srvCallback = /* the callback */
2960 POPSrvURLCallback;
2961
2962
2963
2964 <span class="grey">Kempf &amp; Guttman Informational [Page 53]</span></pre>
2965 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-54" ></span>
2966 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
2967
2968
2969 err = SLPFindSrvs(slph,
2970 pcSrvType, pcScopeList, pcFilter,
2971 srvCallback, NULL);
2972
2973 if( err != SLP_OK ) {
2974
2975 /* Deal with error. */
2976
2977 }
2978
2979 Within the callback, the client code can use the returned POP
2980 service:
2981
2982 SLPBoolean
2983 POPSrvURLCallback(SLPHandle hSLP,
2984 const char* pcSrvURL,
2985 unsigned short sLifetime,
2986 SLPError errCode,
2987 void* pvCookie) {
2988
2989 if( errCode != SLP_OK ) {
2990
2991 /* Deal with error. */
2992
2993 }
2994
2995 SLPSrvURL* pSrvURL;
2996
2997 errCode = SLPParseSrvURL(pcSrvURL, &amp;pSrvURL);
2998
2999 if (err != SLP_OK ) {
3000
3001 /* Deal with error. */
3002
3003 } else {
3004
3005 /* get the server's address */
3006
3007 struct hostent *phe = gethostbyname(pSrvURL.s_pcHost);
3008
3009 /* use hostname in pSrvURL to connect to the POP3 server
3010 * . . .
3011 */
3012
3013 SLPFreeSrvURL((void*)pSrvURL); /* Free the pSrvURL storage */
3014 }
3015
3016 return SLP_FALSE; /* Done! */
3017
3018
3019
3020 <span class="grey">Kempf &amp; Guttman Informational [Page 54]</span></pre>
3021 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-55" ></span>
3022 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3023
3024
3025 }
3026
3027 A client that wanted to discover all the users receiving mail at the
3028 server uses with the following query:
3029
3030 /*
3031 * The client calls SLPOpen(), exactly as above. We assume the
3032 * service: URL was retrieved into surl.
3033 */
3034
3035 const char *pcScopeList = "default"; /* the scope */
3036 const char *pcAttrFilter = "use"; /* the attribute filter */
3037 SLPAttrCallback attrCallBack = /* the callback */
3038 POPUsersCallback
3039
3040
3041 err =
3042 SLPFindAttrs(slph,
3043 surl,
3044 pcScopeList, pcAttrFilter,
3045 attrCallBack, NULL);
3046
3047 if( err != SLP_OK ) {
3048
3049 /* Deal with error. */
3050
3051 }
3052
3053 The callback processes the attributes:
3054
3055 SLPBoolean
3056 POPUsersCallback(const char* pcAttrList,
3057 SLPError errCode,
3058 void* pvCookie) {
3059
3060 if( errCode != SLP_OK ) {
3061
3062 /* Deal with error. */
3063
3064 } else {
3065
3066 /* Parse attributes. */
3067
3068 }
3069
3070 return SLP_FALSE; /* Done! */
3071
3072 }
3073
3074
3075
3076 <span class="grey">Kempf &amp; Guttman Informational [Page 55]</span></pre>
3077 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-56" ></span>
3078 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3079
3080
3081 <span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Java Language Binding</span>
3082
3083 <span class="h3"><a class="selflink" id="section-5.1" href="#section-5.1">5.1</a>. Introduction</span>
3084
3085 The Java API is designed to model the various SLP entities in classes
3086 and objects. APIs are provided for SA, UA, and service type template
3087 access capabilities. The ServiceLocationManager class contains
3088 methods that return instances of objects implementing SA and UA
3089 capability. Each of these is modeled in an interface. The Locator
3090 interface provides UA capability and the Advertiser interface
3091 provides SA capability. The TemplateRegistry abstract class contains
3092 methods that return objects for template introspection and attribute
3093 type checking. The ServiceURL, ServiceType, and
3094 ServiceLocationAttribute classes model the basic SLP concepts. A
3095 concrete subclass instance of TemplateRegistry is returned by a class
3096 method.
3097
3098 All SLP classes and interfaces are located within a single package.
3099 The package name should begin with the name of the implementation and
3100 conclude with the suffix "slp". Thus, the name for a hypothetical
3101 implementation from the University of Michigan would look like:
3102
3103 edu.umich.slp
3104
3105 This follows the Java convention of prepending the top level DNS
3106 domain name for the organization implementing the package onto the
3107 organization's name and using that as the package prefix.
3108
3109 <span class="h3"><a class="selflink" id="section-5.2" href="#section-5.2">5.2</a>. Exceptions and Errors</span>
3110
3111 Most parameters to API methods are required to be non-null. The API
3112 description indicates if a null parameter is acceptable, or if other
3113 restrictions constrain a parameter. When parameters are checked for
3114 validity (such as not being null) or their syntax is checked, an
3115 error results in the RuntimeException subclass
3116 IllegalArgumentException being thrown. Clients of the API are
3117 reminded that IllegalArgumentException, derived from
3118 RuntimeException, is unchecked by the compiler. Clients should thus
3119 be careful to include try/catch blocks for it if the relevant
3120 parameters could be erroneous.
3121
3122 Standard Java practice is to encode every exceptional condition as a
3123 separate subclass of Exception. Because of the relatively high cost
3124 in code size of Exception subclasses, the API contains only a single
3125 Exception subclass with different conditions being determined by an
3126 integer error code property. A subset, appropriate to Java, of the
3127 error codes described in <a href="#section-3">Section 3</a> are available as constants on the
3128 ServiceLocationException class. The subset excludes error codes such
3129
3130
3131
3132 <span class="grey">Kempf &amp; Guttman Informational [Page 56]</span></pre>
3133 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-57" ></span>
3134 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3135
3136
3137 as MEMORY_ALLOC_FAILED.
3138
3139 <span class="h4"><a class="selflink" id="section-5.2.1" href="#section-5.2.1">5.2.1</a>. Class ServiceLocationException</span>
3140
3141 <span class="h5"><a class="selflink" id="section-5.2.1.1" href="#section-5.2.1.1">5.2.1.1</a>. Synopsis</span>
3142
3143
3144 public class ServiceLocationException
3145 extends Exception
3146
3147
3148 <span class="h5"><a class="selflink" id="section-5.2.1.2" href="#section-5.2.1.2">5.2.1.2</a>. Description</span>
3149
3150 The ServiceLocationException class is thrown by all methods when
3151 exceptional conditions occur in the SLP framework. The error code
3152 property determines the exact nature of the condition, and an
3153 optional message may provide more information.
3154
3155 <span class="h5"><a class="selflink" id="section-5.2.1.3" href="#section-5.2.1.3">5.2.1.3</a>. Fields</span>
3156
3157
3158 public static final short LANGUAGE_NOT_SUPPORTED = 1
3159 public static final short PARSE_ERROR = 2
3160 public static final short INVALID_REGISTRATION = 3
3161 public static final short SCOPE_NOT_SUPPORTED = 4
3162 public static final short AUTHENTICATION_ABSENT = 6
3163 public static final short AUTHENTICATION_FAILED = 7
3164 public static final short INVALID_UPDATE = 13
3165 public static final short REFRESH_REJECTED = 15
3166 public static final short NOT_IMPLEMENTED = 16
3167 public static final short NETWORK_INIT_FAILED 17
3168 public static final short NETWORK_TIMED_OUT = 18
3169 public static final short NETWORK_ERROR = 19
3170 public static final short INTERNAL_SYSTEM_ERROR = 20
3171 public static final short TYPE_ERROR = 21
3172 public static final short BUFFER_OVERFLOW = 22
3173
3174
3175 <span class="h5"><a class="selflink" id="section-5.2.1.4" href="#section-5.2.1.4">5.2.1.4</a>. Instance Methods</span>
3176
3177
3178 public short getErrorCode()
3179
3180
3181 Return the error code. The error code takes on one of the static
3182 field values.
3183
3184
3185
3186
3187
3188 <span class="grey">Kempf &amp; Guttman Informational [Page 57]</span></pre>
3189 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-58" ></span>
3190 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3191
3192
3193 <span class="h3"><a class="selflink" id="section-5.3" href="#section-5.3">5.3</a>. Basic Data Structures</span>
3194
3195 <span class="h4"><a class="selflink" id="section-5.3.1" href="#section-5.3.1">5.3.1</a>. Interface ServiceLocationEnumeration</span>
3196
3197
3198 public interface ServiceLocationEnumeration
3199 extends Enumeration
3200
3201
3202 <span class="h5"><a class="selflink" id="section-5.3.1.1" href="#section-5.3.1.1">5.3.1.1</a>. Description</span>
3203
3204 The ServiceLocationEnumeration class is the return type for all
3205 Locator SLP operations. The Java API library may implement this
3206 class to block until results are available from the SLP operation, so
3207 that the client can achieve asynchronous operation by retrieving
3208 results from the enumeration in a separate thread. Clients use the
3209 superclass nextElement() method if they are unconcerned with SLP
3210 exceptions.
3211
3212 <span class="h5"><a class="selflink" id="section-5.3.1.2" href="#section-5.3.1.2">5.3.1.2</a>. Instance Methods</span>
3213
3214
3215 public abstract Object next() throws ServiceLocationException
3216
3217 Return the next value or block until it becomes available.
3218
3219 Throws:
3220
3221 ServiceLocationException
3222
3223 Thrown if the SLP operation encounters an error.
3224
3225 NoSuchElementException
3226
3227 If there are no more elements to return.
3228
3229
3230 <span class="h4"><a class="selflink" id="section-5.3.2" href="#section-5.3.2">5.3.2</a>. Class ServiceLocationAttribute</span>
3231
3232 <span class="h5"><a class="selflink" id="section-5.3.2.1" href="#section-5.3.2.1">5.3.2.1</a>. Synopsis</span>
3233
3234
3235 public class ServiceLocationAttribute
3236 extends Object implements Serializable
3237
3238
3239
3240
3241
3242
3243
3244 <span class="grey">Kempf &amp; Guttman Informational [Page 58]</span></pre>
3245 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-59" ></span>
3246 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3247
3248
3249 <span class="h5"><a class="selflink" id="section-5.3.2.2" href="#section-5.3.2.2">5.3.2.2</a>. Description</span>
3250
3251 The ServiceLocationAttribute class models SLP attributes. Instances
3252 of this class are returned by Locator.findAttributes() and are
3253 communicated along with register/deregister requests.
3254
3255 <span class="h5"><a class="selflink" id="section-5.3.2.3" href="#section-5.3.2.3">5.3.2.3</a>. Constructors</span>
3256
3257
3258 public ServiceLocationAttribute(String id,Vector values)
3259
3260
3261 Construct a service location attribute. Errors in the id or values
3262 vector result in an IllegalArgumentException.
3263
3264 Parameters:
3265
3266 id
3267
3268 The attribute name. The String can consist of any Unicode
3269 character.
3270
3271 values
3272
3273 A Vector of one or more attribute values. Vector contents
3274 must be uniform in type and one of Integer, String, Boolean,
3275 or byte[]. If the attribute is a keyword attribute, then the
3276 parameter should be null. String values can consist of any
3277 Unicode character.
3278
3279
3280 <span class="h5"><a class="selflink" id="section-5.3.2.4" href="#section-5.3.2.4">5.3.2.4</a>. Class Methods</span>
3281
3282
3283 public static String escapeId(String id)
3284
3285
3286 Returns an escaped version of the id parameter, suitable for
3287 inclusion in a query. Any reserved characters as specified in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>]
3288 are escaped using UTF-8 encoding. If any characters in the tag are
3289 illegal, throws IllegalArgumentException.
3290
3291 Parameters:
3292
3293 id
3294
3295 The attribute id to escape. ServiceLocationException is thrown
3296 if any characters are illegal for an attribute tag.
3297
3298
3299
3300 <span class="grey">Kempf &amp; Guttman Informational [Page 59]</span></pre>
3301 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-60" ></span>
3302 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3303
3304
3305 public static String escapeValue(Object value)
3306
3307
3308 Returns a String containing the escaped value parameter as a string,
3309 suitable for inclusion in a query. If the parameter is a string,
3310 any reserved characters as specified in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] are escaped using UTF-8
3311 encoding. If the parameter is a byte array, then the escaped string
3312 begins with the nonUTF-8 sequence `\ff` and the rest of the string
3313 consists of the escaped bytes, which is the encoding for opaques.
3314 If the value parameter is a Boolean or Integer, then the returned
3315 string contains the object converted into a string. If the value
3316 is any type other than String, Integer, Boolean or byte[], an
3317 IllegalArgumentException is thrown.
3318
3319 Parameters:
3320
3321 value
3322
3323 The attribute value to be converted into a string and escaped.
3324
3325
3326 <span class="h5"><a class="selflink" id="section-5.3.2.5" href="#section-5.3.2.5">5.3.2.5</a>. Instance Methods</span>
3327
3328
3329 public Vector getValues()
3330
3331
3332 Returns a cloned vector of attribute values, or null if the attribute
3333 is a keyword attribute. If the attribute is single-valued, then the
3334 vector contains only one object.
3335
3336
3337 public String getId()
3338
3339
3340 Returns the attribute's name.
3341
3342
3343 public boolean equals(Object o)
3344
3345
3346 Overrides Object.equals(). Two attributes are equal if their
3347 identifiers are equal and their value vectors contain the same number
3348 of equal values as determined by the Object equals() method. Values
3349 having byte[] type are equal if the contents of all byte arrays in
3350 both attribute vectors match. Note that the SLP string matching
3351 algorithm [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] MUST NOT be used for comparing attribute identifiers or
3352 string values.
3353
3354
3355
3356 <span class="grey">Kempf &amp; Guttman Informational [Page 60]</span></pre>
3357 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-61" ></span>
3358 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3359
3360
3361 public String toString()
3362
3363
3364 Overrides Object.toString(). The string returned contains a
3365 formatted representation of the attribute, giving the attribute's
3366 id, values, and the Java type of the values. The returned string is
3367 suitable for debugging purposes, but is not in SLP wire format.
3368
3369
3370 public int hashCode()
3371
3372
3373 Overrides Object.hashCode(). Hashes on the attribute's identifier.
3374
3375
3376 <span class="h4"><a class="selflink" id="section-5.3.3" href="#section-5.3.3">5.3.3</a>. Class ServiceType</span>
3377
3378 <span class="h5"><a class="selflink" id="section-5.3.3.1" href="#section-5.3.3.1">5.3.3.1</a>. Synopsis</span>
3379
3380
3381 public class ServiceType extends Object implements Serializable
3382
3383
3384 <span class="h5"><a class="selflink" id="section-5.3.3.2" href="#section-5.3.3.2">5.3.3.2</a>. Description</span>
3385
3386 The ServiceType object models the SLP service type. It parses a
3387 string based service type specifier into its various components, and
3388 contains property accessors to return the components. URL schemes,
3389 protocol service types, and abstract service types are all handled.
3390
3391 <span class="h5"><a class="selflink" id="section-5.3.3.3" href="#section-5.3.3.3">5.3.3.3</a>. Constructors</span>
3392
3393
3394 public ServiceType(String type)
3395
3396
3397 Construct a service type object from the service type specifier.
3398 Throws IllegalArgumentException if the type name is syntactically
3399 incorrect.
3400
3401 Parameters:
3402
3403 type
3404
3405 The service type name as a String. If the service type is from
3406 a service: URL, the "service:" prefix must be intact.
3407
3408
3409
3410
3411
3412 <span class="grey">Kempf &amp; Guttman Informational [Page 61]</span></pre>
3413 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-62" ></span>
3414 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3415
3416
3417 <span class="h5"><a class="selflink" id="section-5.3.3.4" href="#section-5.3.3.4">5.3.3.4</a>. Methods</span>
3418
3419
3420 public boolean isServiceURL()
3421
3422
3423 Returns true if the type name contains the "service:" prefix.
3424
3425
3426 public boolean isAbstractType()
3427
3428
3429 Returns true if the type name is for an abstract type.
3430
3431
3432 public boolean isNADefault()
3433
3434 Returns true if the naming authority is the default, i.e. is the
3435 empty string.
3436
3437
3438 public String getConcreteTypeName()
3439
3440
3441 Returns the concrete type name in an abstract type, or the empty
3442 string if the service type is not abstract. For example, if the type
3443 name is "service:printing:ipp", the method returns "ipp". If the
3444 type name is "service:ftp", the method returns "".
3445
3446
3447 public String getPrincipleTypeName()
3448
3449
3450 Returns the abstract type name for an abstract type, the protocol
3451 name in a protocol type, or the URL scheme for a generic URL. For
3452 example, in the abstract type name "service:printing:ipp", the method
3453 returns "printing". In the protocol type name "service:ftp", the
3454 method returns "ftp".
3455
3456
3457 public String getAbstractTypeName()
3458
3459
3460 If the type is an abstract type, returns the fully formatted abstract
3461 type name including the "service:" and naming authority but without
3462 the concrete type name or intervening colon. If not an abstract
3463 type, returns the empty string. For example, in the abstract type
3464 name "service:printing:ipp", the method returns "service:printing".
3465
3466
3467
3468 <span class="grey">Kempf &amp; Guttman Informational [Page 62]</span></pre>
3469 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-63" ></span>
3470 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3471
3472
3473 public String getNamingAuthority()
3474
3475
3476 Return the naming authority name, or the empty string if the naming
3477 authority is the default.
3478
3479
3480 public boolean equals(Object obj)
3481
3482
3483 Overrides Object.equals(). The two objects are equal if they are
3484 both ServiceType objects and the components of both are equal.
3485
3486
3487 public String toString()
3488
3489
3490 Returns the fully formatted type name, including the "service:" if
3491 the type was originally from a service: URL.
3492
3493
3494 public int hashCode()
3495
3496
3497 Overrides Object.hashCode(). Hashes on the string value of the
3498 "service" prefix, naming authority, if any, abstract and concrete
3499 type names for abstract types, protocol type name for protocol types,
3500 and URL scheme for generic URLs.
3501
3502
3503 <span class="h4"><a class="selflink" id="section-5.3.4" href="#section-5.3.4">5.3.4</a>. Class ServiceURL</span>
3504
3505 <span class="h5"><a class="selflink" id="section-5.3.4.1" href="#section-5.3.4.1">5.3.4.1</a>. Synopsis</span>
3506
3507
3508 public class ServiceURL extends Object implements Serializable
3509
3510
3511 <span class="h5"><a class="selflink" id="section-5.3.4.2" href="#section-5.3.4.2">5.3.4.2</a>. Description</span>
3512
3513 The ServiceURL object models the advertised SLP service URL. It can
3514 be either a service: URL or a regular URL. These objects are
3515 returned from service lookup requests, and describe the registered
3516 services. This class should be a subclass of java.net.URL but can't
3517 since that class is final.
3518
3519
3520
3521
3522
3523
3524 <span class="grey">Kempf &amp; Guttman Informational [Page 63]</span></pre>
3525 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-64" ></span>
3526 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3527
3528
3529 <span class="h5"><a class="selflink" id="section-5.3.4.3" href="#section-5.3.4.3">5.3.4.3</a>. Class Variables</span>
3530
3531
3532 public static final int NO_PORT = 0
3533
3534
3535 Indicates that no port information is required or was returned for
3536 this URL.
3537
3538
3539 public static final int LIFETIME_NONE = 0
3540
3541
3542 Indicates that the URL has a zero lifetime. This value is never
3543 returned from the API, but can be used to create a ServiceURL object
3544 to deregister, delete attributes, or find attributes.
3545
3546
3547 public static final int LIFETIME_DEFAULT = 10800
3548
3549
3550 The default URL lifetime (3 hours) in seconds.
3551
3552
3553 public static final int LIFETIME_MAXIMUM = 65535
3554
3555
3556 The maximum URL lifetime (about 18 hours) in seconds.
3557
3558
3559 public static final int LIFETIME_PERMANENT = -1
3560
3561
3562 Indicates that the API implementation should continuously re-register
3563 the URL until the application exits.
3564
3565
3566 <span class="h5"><a class="selflink" id="section-5.3.4.4" href="#section-5.3.4.4">5.3.4.4</a>. Constructors</span>
3567
3568
3569 public ServiceURL(String URL,int lifetime)
3570
3571
3572 Construct a service URL object having the specified lifetime.
3573
3574
3575
3576
3577
3578
3579
3580 <span class="grey">Kempf &amp; Guttman Informational [Page 64]</span></pre>
3581 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-65" ></span>
3582 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3583
3584
3585 Parameters:
3586
3587 URL
3588
3589 The URL as a string. Must be either a service: URL or a valid
3590 generic URL according to <a href="./rfc2396">RFC 2396</a> [<a href="#ref-2" title="&quot;Uniform Resource Identifiers (URI): Generic Syntax&quot;">2</a>].
3591
3592 lifetime
3593
3594 The service advertisement lifetime in seconds. This value may
3595 be between LIFETIME_NONE and LIFETIME_MAXIMUM.
3596
3597
3598 <span class="h5"><a class="selflink" id="section-5.3.4.5" href="#section-5.3.4.5">5.3.4.5</a>. Methods</span>
3599
3600
3601 public ServiceType getServiceType()
3602
3603
3604 Returns the service type object representing the service type name of
3605 the URL.
3606
3607
3608 public final void setServiceType(ServiceType type)
3609 throws ServiceLocationException
3610
3611
3612 Set the service type name to the object. Ignored if the URL is a
3613 service: URL.
3614
3615 Parameters:
3616
3617 type
3618
3619 The service type object.
3620
3621
3622 public String getTransport()
3623
3624
3625 Get the network layer transport identifier. If the transport is IP,
3626 an empty string, "", is returned.
3627
3628
3629 public String getHost()
3630
3631
3632
3633
3634
3635
3636 <span class="grey">Kempf &amp; Guttman Informational [Page 65]</span></pre>
3637 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-66" ></span>
3638 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3639
3640
3641 Returns the host identifier. For IP, this will be the machine name
3642 or IP address.
3643
3644
3645 public int getPort()
3646
3647
3648 Returns the port number, if any. For non-IP transports, always
3649 returns NO_PORT.
3650
3651
3652 public String getURLPath()
3653
3654
3655 Returns the URL path description, if any.
3656
3657
3658 public int getLifetime()
3659
3660
3661 Returns the service advertisement lifetime. This will be a positive
3662 int between LIFETIME_NONE and LIFETIME_MAXIMUM.
3663
3664
3665 public boolean equals(Object obj)
3666
3667
3668 Compares the object to the ServiceURL and returns true if the two are
3669 the same. Two ServiceURL objects are equal if their current service
3670 types match and they have the same host, port, transport, and URL
3671 path.
3672
3673
3674 public String toString()
3675
3676
3677 Returns a formatted string with the URL. Overrides Object.toString().
3678 The returned URL has the original service type or URL scheme, not the
3679 current service type.
3680
3681
3682 public int hashCode()
3683
3684
3685 Overrides Object.hashCode(). Hashes on the current service type,
3686 transport, host, port, and URL part.
3687
3688
3689
3690
3691
3692 <span class="grey">Kempf &amp; Guttman Informational [Page 66]</span></pre>
3693 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-67" ></span>
3694 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3695
3696
3697 <span class="h3"><a class="selflink" id="section-5.4" href="#section-5.4">5.4</a>. SLP Access Interfaces</span>
3698
3699 <span class="h4"><a class="selflink" id="section-5.4.1" href="#section-5.4.1">5.4.1</a>. Interface Advertiser</span>
3700
3701 <span class="h5"><a class="selflink" id="section-5.4.1.1" href="#section-5.4.1.1">5.4.1.1</a>. Synopsis</span>
3702
3703
3704 public interface Advertiser
3705
3706
3707 <span class="h5"><a class="selflink" id="section-5.4.1.2" href="#section-5.4.1.2">5.4.1.2</a>. Description</span>
3708
3709 The Advertiser is the SA interface, allowing clients to register new
3710 service instances with SLP, to change the attributes of existing
3711 services, and to deregister service instances. New registrations and
3712 modifications of attributes are made in the language locale with
3713 which the Advertiser was created, deregistrations of service
3714 instances are made for all locales.
3715
3716 <span class="h5"><a class="selflink" id="section-5.4.1.3" href="#section-5.4.1.3">5.4.1.3</a>. Instance Methods</span>
3717
3718
3719 public abstract Locale getLocale()
3720
3721
3722 Return the language locale with which this object was created.
3723
3724
3725 public abstract void register(ServiceURL URL,
3726 Vector attributes)
3727 throws ServiceLocationException
3728
3729 Register a new service with SLP having the given attributes.
3730
3731 The API library is required to perform the operation in all
3732 scopes obtained through configuration.
3733
3734
3735 Parameters:
3736
3737 URL
3738
3739 The URL for the service.
3740
3741 attributes
3742
3743 A vector of ServiceLocationAttribute objects describing the
3744 service.
3745
3746
3747
3748 <span class="grey">Kempf &amp; Guttman Informational [Page 67]</span></pre>
3749 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-68" ></span>
3750 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3751
3752
3753 public abstract void deregister(ServiceURL URL)
3754 throws ServiceLocationException
3755
3756
3757 Deregister a service from the SLP framework. This has the effect
3758 of deregistering the service from every language locale. The API
3759 library is required to perform the operation in all scopes obtained
3760 through configuration.
3761
3762 Parameters:
3763
3764 URL
3765
3766 The URL for the service.
3767
3768
3769 public abstract void
3770 addAttributes(ServiceURL URL,
3771 Vector attributes)
3772 throws ServiceLocationException
3773
3774
3775 Update the registration by adding the given attributes. The API
3776 library is required to perform the operation in all scopes obtained
3777 through configuration.
3778
3779 Parameters:
3780
3781 URL
3782
3783 The URL for the service.
3784
3785 attributes
3786
3787 A Vector of ServiceLocationAttribute objects to add to the
3788 existing registration. Use an empty vector to update the URL
3789 alone. May not be null.
3790
3791
3792 public abstract void
3793 deleteAttributes(ServiceURL URL,
3794 Vector attributeIds)
3795 throws ServiceLocationException
3796
3797
3798 Delete the attributes from a URL for the locale with which the
3799 Advertiser was created. The API library is required to perform the
3800 operation in all scopes obtained through configuration.
3801
3802
3803
3804 <span class="grey">Kempf &amp; Guttman Informational [Page 68]</span></pre>
3805 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-69" ></span>
3806 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3807
3808
3809 Parameters:
3810
3811 URL
3812
3813 The URL for the service.
3814
3815 attributeIds
3816
3817 A vector of Strings indicating the ids of the attributes
3818 to remove. The strings may be attribute ids or they
3819 may be wildcard patterns to match ids. See [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for the
3820 syntax of wildcard patterns. The strings may include SLP
3821 reserved characters, they will be escaped by the API before
3822 transmission. May not be the empty vector or null.
3823
3824
3825 <span class="h4"><a class="selflink" id="section-5.4.2" href="#section-5.4.2">5.4.2</a>. Interface Locator</span>
3826
3827 <span class="h5"><a class="selflink" id="section-5.4.2.1" href="#section-5.4.2.1">5.4.2.1</a>. Synopsis</span>
3828
3829
3830 public interface Locator
3831
3832
3833 <span class="h5"><a class="selflink" id="section-5.4.2.2" href="#section-5.4.2.2">5.4.2.2</a>. Description</span>
3834
3835 The Locator is the UA interface, allowing clients to query the SLP
3836 framework about existing service types, services instances, and about
3837 the attributes of an existing service instance or service type.
3838 Queries for services and attributes are made in the locale with which
3839 the Locator was created, queries for service types are independent of
3840 locale.
3841
3842 <span class="h5"><a class="selflink" id="section-5.4.2.3" href="#section-5.4.2.3">5.4.2.3</a>. Instance Methods</span>
3843
3844
3845 public abstract Locale getLocale()
3846
3847
3848 Return the language locale with which this object was created.
3849
3850
3851 public abstract ServiceLocationEnumeration
3852 findServiceTypes(String namingAuthority,
3853 Vector scopes)
3854 throws ServiceLocationException
3855
3856
3857
3858
3859
3860 <span class="grey">Kempf &amp; Guttman Informational [Page 69]</span></pre>
3861 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-70" ></span>
3862 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3863
3864
3865 Returns an enumeration of ServiceType objects giving known service
3866 types for the given scopes and given naming authority. If no service
3867 types are found, an empty enumeration is returned.
3868
3869 Parameters:
3870
3871 namingAuthority
3872
3873 The naming authority. Use "" for the default naming authority
3874 and "*" for all naming authorities.
3875
3876 scopes
3877
3878 A Vector of scope names. The vector should be selected from
3879 the results of a findScopes() API invocation. Use "DEFAULT"
3880 for the default scope.
3881
3882
3883 public abstract ServiceLocationEnumeration
3884 findServices(ServiceType type,
3885 Vector scopes,
3886 String searchFilter)
3887 throws ServiceLocationException
3888
3889
3890 Returns a vector of ServiceURL objects for services matching the
3891 query, and having a matching type in the given scopes. If no
3892 services are found, an empty enumeration is returned.
3893
3894 Parameters:
3895
3896 type
3897
3898 The SLP service type of the service.
3899
3900 scopes
3901
3902 A Vector of scope names. The vector should be selected from
3903 the results of a findScopes() API invocation. Use "DEFAULT"
3904 for the default scope.
3905
3906 searchFilter
3907
3908 An LDAPv3 [<a href="#ref-4" title="&quot;The String Representation of LDAP Search Filters&quot;">4</a>] string encoded query. If the filter is empty,
3909 i.e. "", all services of the requested type in the specified
3910 scopes are returned. SLP reserved characters must be escaped
3911 in the query. Use ServiceLocationAttribute.escapeId() and
3912 ServiceLocationAttribute.escapeValue() to construct the query.
3913
3914
3915
3916 <span class="grey">Kempf &amp; Guttman Informational [Page 70]</span></pre>
3917 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-71" ></span>
3918 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3919
3920
3921 public abstract ServiceLocationEnumeration
3922 findAttributes(ServiceURL URL,
3923 Vector scopes,
3924 Vector attributeIds)
3925 throws ServiceLocationException
3926
3927
3928 For the URL and scope, return a Vector of ServiceLocationAttribute
3929 objects whose ids match the String patterns in the attributeIds
3930 Vector. The request is made in the language locale of the Locator.
3931 If no attributes match, an empty enumeration is returned.
3932
3933 Parameters:
3934
3935 URL
3936
3937 The URL for which the attributes are desired.
3938
3939 scopes
3940
3941 A Vector of scope names. The vector should be selected from
3942 the results of a findScopes() API invocation. Use "DEFAULT"
3943 for the default scope.
3944
3945 attributeIds
3946
3947 A Vector of String patterns identifying the desired attributes.
3948 An empty vector means return all attributes. As described
3949 in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>], the patterns may include wildcards to match substrings.
3950 The strings may include SLP reserved characters, they will be
3951 escaped by the API before transmission.
3952
3953
3954 public abstract ServiceLocationEnumeration
3955 findAttributes(ServiceType type,
3956 Vector scopes,
3957 Vector attributeIds)
3958 throws ServiceLocationException
3959
3960
3961 For the type and scope, return a Vector of all ServiceLocationAttribute
3962 objects whose ids match the String patterns in the attributeIds
3963 Vector regardless of the Locator's locale. The request is made
3964 independent of language locale. If no attributes are found, an empty
3965 vector is returned.
3966
3967
3968
3969
3970
3971
3972 <span class="grey">Kempf &amp; Guttman Informational [Page 71]</span></pre>
3973 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-72" ></span>
3974 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
3975
3976
3977 Parameters:
3978
3979 serviceType
3980
3981 The service type.
3982
3983 scopes
3984
3985 A Vector of scope names. The vector should be selected from
3986 the results of a findScopes() API invocation. Use "DEFAULT"
3987 for the default scope.
3988
3989 attributeIds
3990
3991 A Vector of String patterns identifying the desired
3992 attributes. An empty vector means return all attributes.
3993 As described in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>], the patterns may include wildcards to
3994 match all prefixes or suffixes. The patterns may include SLP
3995 reserved characters, they will be escaped by the API before
3996 transmission.
3997
3998 <span class="h3"><a class="selflink" id="section-5.5" href="#section-5.5">5.5</a>. The Service Location Manager</span>
3999
4000 <span class="h4"><a class="selflink" id="section-5.5.1" href="#section-5.5.1">5.5.1</a>. Class ServiceLocationManager</span>
4001
4002 <span class="h5"><a class="selflink" id="section-5.5.1.1" href="#section-5.5.1.1">5.5.1.1</a>. Synopsis</span>
4003
4004
4005 public class ServiceLocationManager
4006 extends Object
4007
4008
4009 <span class="h5"><a class="selflink" id="section-5.5.1.2" href="#section-5.5.1.2">5.5.1.2</a>. Description</span>
4010
4011 The ServiceLocationManager manages access to the service location
4012 framework. Clients obtain the Locator and Advertiser objects for UA
4013 and SA, and a Vector of known scope names from the
4014 ServiceLocationManager.
4015
4016 <span class="h5"><a class="selflink" id="section-5.5.1.3" href="#section-5.5.1.3">5.5.1.3</a>. Class Methods</span>
4017
4018
4019 public static int getRefreshInterval()
4020 throws ServiceLocationException
4021
4022
4023
4024
4025
4026
4027
4028 <span class="grey">Kempf &amp; Guttman Informational [Page 72]</span></pre>
4029 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-73" ></span>
4030 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4031
4032
4033 Returns the maximum across all DAs of the min-refresh-interval
4034 attribute. This value satisfies the advertised refresh interval
4035 bounds for all DAs, and, if used by the SA, assures that no
4036 refresh registration will be rejected. If no DA advertises a
4037 min-refresh-interval attribute, a value of 0 is returned.
4038
4039
4040 public static Vector findScopes()
4041 throws ServiceLocationException
4042
4043
4044 Returns an Vector of strings with all available scope names. The
4045 list of scopes comes from a variety of sources, see <a href="#section-2.1">Section 2.1</a> for
4046 the scope discovery algorithm. There is always at least one string
4047 in the Vector, the default scope, "DEFAULT".
4048
4049
4050 public static Locator
4051 getLocator(Locale locale)
4052 throws ServiceLocationException
4053
4054
4055 Return a Locator object for the given language Locale. If the
4056 implementation does not support UA functionality, returns null.
4057
4058 Parameters:
4059
4060 locale
4061
4062 The language locale of the Locator. The default SLP locale is
4063 used if null.
4064
4065
4066 public static Advertiser
4067 getAdvertiser(Locale locale)
4068 throws ServiceLocationException
4069
4070
4071 Return an Advertiser object for the given language locale. If the
4072 implementation does not support SA functionality, returns null.
4073
4074 Parameters:
4075
4076 locale
4077
4078 The language locale of the Advertiser. The default SLP locale
4079 is used if null.
4080
4081
4082
4083
4084 <span class="grey">Kempf &amp; Guttman Informational [Page 73]</span></pre>
4085 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-74" ></span>
4086 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4087
4088
4089 <span class="h3"><a class="selflink" id="section-5.6" href="#section-5.6">5.6</a>. Service Template Introspection</span>
4090
4091 <span class="h4"><a class="selflink" id="section-5.6.1" href="#section-5.6.1">5.6.1</a>. Abstract Class TemplateRegistry</span>
4092
4093 <span class="h5"><a class="selflink" id="section-5.6.1.1" href="#section-5.6.1.1">5.6.1.1</a>. Synopsis</span>
4094
4095
4096 public abstract class TemplateRegistry
4097
4098
4099 <span class="h5"><a class="selflink" id="section-5.6.1.2" href="#section-5.6.1.2">5.6.1.2</a>. Description</span>
4100
4101 Subclasses of the TemplateRegistry abstract class provide access to
4102 service location templates [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>]. Classes implementing
4103 TemplateRegistry perform a variety of functions. They manage the
4104 registration and access of service type template documents. They
4105 create attribute verifiers from service templates, for verification
4106 of attributes and introspection on template documents. Note that
4107 clients of the Advertiser are not required to verify attributes
4108 before registering (though they may get a TYPE_ERROR if the
4109 implementation supports type checking and there is a mismatch with
4110 the template).
4111
4112 <span class="h5"><a class="selflink" id="section-5.6.1.3" href="#section-5.6.1.3">5.6.1.3</a>. Class Methods</span>
4113
4114
4115 public static TemplateRegistry getTemplateRegistry();
4116
4117
4118 Returns the distinguished TemplateRegistry object for performing
4119 operations on and with service templates. Returns null if the
4120 implementation doesn't support TemplateRegistry functionality.
4121
4122 <span class="h5"><a class="selflink" id="section-5.6.1.4" href="#section-5.6.1.4">5.6.1.4</a>. Instance Methods</span>
4123
4124
4125 public abstract void
4126 registerServiceTemplate(ServiceType type,
4127 String documentURL,
4128 Locale locale,
4129 String version)
4130 throws ServiceLocationException
4131
4132
4133 Register the service template with the template registry.
4134
4135
4136
4137
4138
4139
4140 <span class="grey">Kempf &amp; Guttman Informational [Page 74]</span></pre>
4141 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-75" ></span>
4142 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4143
4144
4145 Parameters:
4146
4147 type
4148
4149 The service type.
4150
4151 documentURL
4152
4153 A string containing the URL of the template document. May not
4154 be the empty string.
4155
4156 locale
4157
4158 A Locale object containing the language locale of the template.
4159
4160 version
4161
4162 The version number identifier of template document.
4163
4164
4165 public abstract void
4166
4167
4168 deregisterServiceTemplate(ServiceType type,
4169 Locale locale,
4170 String version)
4171 throws ServiceLocationException
4172
4173
4174 Deregister the template for the service type.
4175
4176 Parameters:
4177
4178 type
4179
4180 The service type.
4181
4182 locale
4183
4184 A Locale object containing the language locale of the template.
4185
4186 version
4187
4188 A String containing the version number. Use null to indicate
4189 the latest version.
4190
4191
4192
4193
4194
4195
4196 <span class="grey">Kempf &amp; Guttman Informational [Page 75]</span></pre>
4197 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-76" ></span>
4198 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4199
4200
4201 public abstract
4202 String findTemplateURL(ServiceType type,
4203 Locale locale,
4204 String version)
4205 throws ServiceLocationException
4206
4207
4208 Returns the URL for the template document.
4209
4210 Parameters:
4211
4212 type
4213
4214 The service type.
4215
4216 locale
4217
4218 A Locale object containing the language locale of the template.
4219
4220 version
4221
4222 A String containing the version number. Use null to indicate
4223 the latest version.
4224
4225
4226 public abstract
4227 ServiceLocationAttributeVerifier
4228 attributeVerifier(String documentURL)
4229 throws ServiceLocationException
4230
4231
4232 Reads the template document URL and returns an attribute verifier
4233 for the service type. The attribute verifier can be used for
4234 verifying that registration attributes match the template, and for
4235 introspection on the template definition.
4236
4237 Parameters:
4238
4239 documentURL
4240
4241 A String containing the template document's URL. May not be the
4242 empty string.
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252 <span class="grey">Kempf &amp; Guttman Informational [Page 76]</span></pre>
4253 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-77" ></span>
4254 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4255
4256
4257 <span class="h4"><a class="selflink" id="section-5.6.2" href="#section-5.6.2">5.6.2</a>. Interface ServiceLocationAttributeVerifier</span>
4258
4259 <span class="h5"><a class="selflink" id="section-5.6.2.1" href="#section-5.6.2.1">5.6.2.1</a>. Synopsis</span>
4260
4261
4262 public interface ServiceLocationAttributeVerifier
4263
4264
4265 <span class="h5"><a class="selflink" id="section-5.6.2.2" href="#section-5.6.2.2">5.6.2.2</a>. Description</span>
4266
4267 The ServiceLocationAttributeVerifier provides access to service
4268 templates. Classes implementing this interface parse SLP template
4269 definitions, provide information on attribute definitions for service
4270 types, and verify whether a ServiceLocationAttribute object matches a
4271 template for a particular service type. Clients obtain
4272 ServiceLocationAttributeVerifier objects for specific SLP service
4273 types through the TemplateRegistry.
4274
4275 <span class="h5"><a class="selflink" id="section-5.6.2.3" href="#section-5.6.2.3">5.6.2.3</a>. Instance Methods</span>
4276
4277
4278 public abstract ServiceType getServiceType()
4279
4280
4281 Returns the SLP service type for which this is the verifier.
4282
4283
4284 public abstract Locale getLocale()
4285
4286
4287 Return the language locale of the template.
4288
4289
4290 public abstract String getVersion()
4291
4292
4293 Return the template version number identifier.
4294
4295
4296 public abstract String getURLSyntax()
4297
4298
4299 Return the URL syntax expression for the service: URL.
4300
4301
4302 public abstract String getDescription()
4303
4304
4305
4306
4307
4308 <span class="grey">Kempf &amp; Guttman Informational [Page 77]</span></pre>
4309 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-78" ></span>
4310 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4311
4312
4313 Return the descriptive help text for the template.
4314
4315
4316 public abstract ServiceLocationAttributeDescriptor
4317 getAttributeDescriptor(String attrId)
4318
4319
4320 Return the ServiceLocationAttributeDescriptor for the attribute
4321 having the named id. If no such attribute exists in this template,
4322 return null. This method is primarily for GUI tools to display
4323 attribute information. Programmatic verification of attributes
4324 should use the verifyAttribute() method.
4325
4326
4327 public abstract Enumeration
4328 getAttributeDescriptors()
4329
4330
4331 Returns an Enumeration allowing introspection on the attribute
4332 definition in the service template. The Enumeration returns
4333 ServiceLocationAttributeDescriptor objects for the attributes.
4334 This method is primarily for GUI tools to display attribute
4335 information. Programmatic verification of attributes should use the
4336 verifyAttribute() method.
4337
4338
4339 public abstract void
4340 verifyAttribute(
4341 ServiceLocationAttribute attribute)
4342 throws ServiceLocationException
4343
4344
4345 Verify that the attribute matches the template definition. If the
4346 attribute doesn't match, ServiceLocationException is thrown with the
4347 error code as ServiceLocationException.PARSE_ERROR.
4348
4349 Parameters:
4350
4351 attribute
4352
4353 The ServiceLocationAttribute object to be verified.
4354
4355
4356 public abstract void
4357 verifyRegistration(
4358 Vector attributeVector)
4359 throws ServiceLocationException
4360
4361
4362
4363
4364 <span class="grey">Kempf &amp; Guttman Informational [Page 78]</span></pre>
4365 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-79" ></span>
4366 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4367
4368
4369 Verify that the Vector of ServiceLocationAttribute objects matches
4370 the template for this service type. The vector must contain all the
4371 required attributes, and all attributes must match their template
4372 definitions. If the attributes don't match, ServiceLocationException
4373 is thrown with the error code as ServiceLocationException.PARSE_ERROR
4374
4375 Parameters:
4376
4377 attributeVector
4378
4379 A Vector of ServiceLocationAttribute objects for the
4380 registration.
4381
4382
4383 <span class="h4"><a class="selflink" id="section-5.6.3" href="#section-5.6.3">5.6.3</a>. Interface ServiceLocationAttributeDescriptor</span>
4384
4385 <span class="h5"><a class="selflink" id="section-5.6.3.1" href="#section-5.6.3.1">5.6.3.1</a>. Synopsis</span>
4386
4387
4388 public interface
4389 ServiceLocationAttributeDescriptor
4390
4391
4392 <span class="h5"><a class="selflink" id="section-5.6.3.2" href="#section-5.6.3.2">5.6.3.2</a>. Description</span>
4393
4394 The ServiceLocationAttributeDescriptor interface provides
4395 introspection on a template attribute definition. Classes
4396 implementing the ServiceLocationAttributeDescriptor interface return
4397 information on a particular service location attribute definition
4398 from the service template. This information is primarily for GUI
4399 tools. Programmatic attribute verification should be done through
4400 the ServiceLocationAttributeVerifier.
4401
4402 <span class="h5"><a class="selflink" id="section-5.6.3.3" href="#section-5.6.3.3">5.6.3.3</a>. Instance Methods</span>
4403
4404
4405 public abstract String getId()
4406
4407
4408 Return a String containing the attribute's id.
4409
4410
4411 public abstract String getValueType()
4412
4413
4414 Return a String containing the fully package-qualified Java type of
4415 the attribute. SLP types are translated into Java types as follows:
4416
4417
4418
4419
4420 <span class="grey">Kempf &amp; Guttman Informational [Page 79]</span></pre>
4421 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-80" ></span>
4422 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4423
4424
4425 STRING
4426
4427 "java.lang.String"
4428
4429 INTEGER
4430
4431 "java.lang.Integer"
4432
4433 BOOLEAN
4434
4435 "java.lang.Boolean"
4436
4437 OPAQUE
4438
4439 "[B" (i.e. array of byte, byte[])
4440
4441 KEYWORD
4442
4443 empty string, ""
4444
4445
4446 public abstract String getDescription()
4447
4448
4449 Return a String containing the attribute's help text.
4450
4451
4452 public abstract Enumeration
4453 getAllowedValues()
4454
4455
4456 Return an Enumeration of allowed values for the attribute type.
4457 For keyword attributes returns null. For no allowed values (i.e.
4458 unrestricted) returns an empty Enumeration.
4459
4460
4461 public abstract Enumeration
4462 getDefaultValues()
4463
4464
4465 Return an Enumeration of default values for the attribute type.
4466 For keyword attributes returns null. For no allowed values (i.e.
4467 unrestricted) returns an empty Enumeration.
4468
4469
4470 public abstract boolean
4471 getRequiresExplicitMatch()
4472
4473
4474
4475
4476 <span class="grey">Kempf &amp; Guttman Informational [Page 80]</span></pre>
4477 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-81" ></span>
4478 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4479
4480
4481 Returns true if the "X"" flag is set, indicating that the attribute
4482 should be included in an any Locator.findServices() request search
4483 filter.
4484
4485
4486 public abstract boolean getIsMultivalued()
4487
4488
4489 Returns true if the "M" flag is set.
4490
4491
4492 public abstract boolean getIsOptional()
4493
4494
4495 Returns true if the "O"" flag is set.
4496
4497
4498 public abstract boolean getIsLiteral()
4499
4500
4501 Returns true if the "L" flag is set.
4502
4503
4504 public abstract boolean getIsKeyword()
4505
4506
4507 Returns true if the attribute is a keyword attribute.
4508
4509
4510 <span class="h3"><a class="selflink" id="section-5.7" href="#section-5.7">5.7</a>. Implementation Notes</span>
4511
4512 <span class="h4"><a class="selflink" id="section-5.7.1" href="#section-5.7.1">5.7.1</a>. Refreshing Registrations</span>
4513
4514 A special lifetime constant, ServiceURL.LIFETIME_PERMANENT, is used
4515 by clients to indicate that the URL should be automatically refreshed
4516 until the application exits. The API implementation should interpret
4517 this flag as indicating that the URL lifetime is
4518 ServiceURL.LIFETIME_MAXIMUM, and MUST arrange for automatic refresh
4519 to occur.
4520
4521 <span class="h4"><a class="selflink" id="section-5.7.2" href="#section-5.7.2">5.7.2</a>. Parsing Alternate Transports in ServiceURL</span>
4522
4523 The ServiceURL class is designed to handle multiple transports. The
4524 standard API performs no additional processing on transports other
4525 than IP except to separate out the host identifier and the URL path.
4526 However, implementations are free to subclass ServiceURL and support
4527 additional methods that provide more detailed parsing of alternate
4528 transport information. For IP transport, the port number, if any, is
4529
4530
4531
4532 <span class="grey">Kempf &amp; Guttman Informational [Page 81]</span></pre>
4533 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-82" ></span>
4534 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4535
4536
4537 returned from the getPort() method. For non-IP transports, the
4538 getPort() method returns NO_PORT.
4539
4540 <span class="h4"><a class="selflink" id="section-5.7.3" href="#section-5.7.3">5.7.3</a>. String Attribute Values</span>
4541
4542 In general, translation between Java types for attribute values and
4543 the SLP on-the-wire string is straightforward. However, there are
4544 two corner cases. If the Java attribute value type is String and the
4545 value of the string has an on-the-wire representation that is
4546 inferred by SLP as an integer, the registered attribute value may not
4547 be what the API client intended. A similar problem could result if
4548 the Java attribute value is the string "true" or "false", in which
4549 case the on-the-wire representation is inferred to boolean. To
4550 handle these corner cases, the Java API prepends a space onto the
4551 string. So, for example, if the string attribute value is "123", the
4552 Java API transforms the value to "123 ", which will have an on-the-
4553 wire representation that is inferred by SLP to be string. Since
4554 appended and prepended spaces have no effect on query handling, this
4555 procedure should cause no problem with queries. API clients need to
4556 be aware, however, that the transformation is occurring.
4557
4558 <span class="h4"><a class="selflink" id="section-5.7.4" href="#section-5.7.4">5.7.4</a>. Client Side Syntax Checking</span>
4559
4560 The syntax of scope names, service type names, naming authority
4561 names, and URLs is described in [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] and [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>]. The various methods and
4562 classes taking String parameters for these entities SHOULD type check
4563 the parameters for syntax errors on the client side, and throw an
4564 IllegalArgumentException if an error occurs. In addition, character
4565 escaping SHOULD be implemented before network transmission for
4566 escapable characters in attribute ids and String values. This
4567 reduces the number of error messages transmitted. The
4568 ServiceLocationAttribute class provides methods for clients to obtain
4569 escaped attribute id and value strings to facilitate query
4570 construction.
4571
4572 <span class="h4"><a class="selflink" id="section-5.7.5" href="#section-5.7.5">5.7.5</a>. Language Locale Handling</span>
4573
4574 The Locator and Advertiser interfaces are created with a Locale
4575 parameter. The language locale with which these objects are created
4576 is used in all SLP requests issued through the object. If the Locale
4577 parameter is null, the default SLP locale is used. The default SLP
4578 locale is determined by, first, checking the net.slp.locale System
4579 property. If that is unset, then the default SLP locale [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] is used,
4580 namely "en". Note that the default SLP locale may not be the same as
4581 the default Java locale.
4582
4583
4584
4585
4586
4587
4588 <span class="grey">Kempf &amp; Guttman Informational [Page 82]</span></pre>
4589 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-83" ></span>
4590 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4591
4592
4593 <span class="h4"><a class="selflink" id="section-5.7.6" href="#section-5.7.6">5.7.6</a>. Setting SLP System Properties</span>
4594
4595 SLP system properties that are originally set in the configuration
4596 file can be overridden programmatically in API clients by simply
4597 invoking the System.getProperties() operation to get a copy of the
4598 system properties, modifying or adding the SLP property in question,
4599 then using System.setProperties() to set the properties to the
4600 modified Property object. Program execution continues without
4601 interruption by substituting the default for the erroneous parameter.
4602 Errors are checked when the property is used and are logged.
4603
4604 The SLP configuration file cannot be read with the
4605 java.util.Properties file reader because there are some syntactic
4606 differences. The SLP configuration file syntax defines a different
4607 escape convention for non-ASCII characters than the Java syntax.
4608 However, after the file has been read, the properties are stored and
4609 retrieved from java.util.Properties objects.
4610
4611 Properties are global for a process, affecting all threads and all
4612 Locator and Advertiser objects obtained through the
4613 ServiceLocationManager. With the exception of the net.slp.locale,
4614 net.slp.typeHint, and net.slp.maxResults properties, clients should
4615 rarely be required to override these properties, since they reflect
4616 properties of the SLP network that are not of concern to individual
4617 agents. If changes are required, system administrators should modify
4618 the configuration file.
4619
4620 <span class="h4"><a class="selflink" id="section-5.7.7" href="#section-5.7.7">5.7.7</a>. Multithreading</span>
4621
4622 Thread-safe operation is relatively easy to achieve in Java. By
4623 simply making each method in the classes implementing the Locator and
4624 Advertiser interfaces synchronized, and by synchronizing access to
4625 any shared data structures within the class, the Locator and
4626 Advertiser interfaces are made safe. Alternatively, finer grained
4627 synchronization is also possible within the classes implementing
4628 Advertiser and Locator.
4629
4630 <span class="h4"><a class="selflink" id="section-5.7.8" href="#section-5.7.8">5.7.8</a>. Modular Implementations</span>
4631
4632 While, at first glance, the API may look rather heavyweight, the
4633 design has been carefully arranged so that modular implementations
4634 that provide only SA, only UA, or only service template access
4635 capability, or any combination of the three, are possible.
4636
4637 Because the objects returned from the
4638 ServiceLocationManager.getLocator() and
4639 ServiceLocationManager.getAdvertiser() operations are interfaces, and
4640 because the objects returned through those interfaces are in the set
4641
4642
4643
4644 <span class="grey">Kempf &amp; Guttman Informational [Page 83]</span></pre>
4645 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-84" ></span>
4646 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4647
4648
4649 of base data structures, an implementation is free to omit either UA
4650 or SA capability by simply returning null from the instance creation
4651 operation if the classes implementing the missing function cannot be
4652 dynamically linked. API clients are encouraged to check for such a
4653 contingency, and to signal an exception if it occurs. Similarly, the
4654 TemplateRegistry concrete subclass can simply be omitted from an
4655 implementation that only supports UA and/or SA clients, and the
4656 TemplateRegistry.getRegistry() method can return null. In this way,
4657 the API implementation can be tailored for the particular memory
4658 requirements at hand.
4659
4660 In addition, if an implementation only supports the minimal subset of
4661 SLP [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>], the unsupported Locator and Advertiser interface operations
4662 can throw an exception with ServiceLocationException.NOT_IMPLEMENTED
4663 as the error code. This supports better source portability between
4664 low and high memory platforms.
4665
4666 <span class="h4"><a class="selflink" id="section-5.7.9" href="#section-5.7.9">5.7.9</a>. Asynchronous and Incremental Return Semantics</span>
4667
4668 The Java API contains no specific support for asynchronous operation.
4669 Incremental return is not needed for the Advertiser because service
4670 registrations can be broken up into pieces when large. Asynchronous
4671 return is also not needed because clients can always issue the
4672 Advertiser operation in a separate thread if the calling thread can't
4673 block.
4674
4675 The Locator can be implemented either synchronously or
4676 asynchronously. Since the return type for Locator calls is
4677 ServiceLocationEnumeration, a Java API implementation that supports
4678 asynchronous semantics can implement ServiceLocationEnumeration to
4679 dole results out as they come in, blocking when no results are
4680 available. If the client code needs to support other processing
4681 while the results are trickling in, the call into the enumeration to
4682 retrieve the results can be done in a separate thread.
4683
4684 Unlike the C case, collation semantics for return of attributes when
4685 an attribute request by service type is made require that the API
4686 collate returned values so that only one attribute having a collation
4687 of all returned values appear to the API client. In practice, this
4688 may limit the amount of asynchronous processing possible with the
4689 findAttributes() method. This requirement is imposed because memory
4690 management is much easier in Java and so implementing collation as
4691 part of the API should not be as difficult as in C, and it saves the
4692 client from having to do the collation.
4693
4694
4695
4696
4697
4698
4699
4700 <span class="grey">Kempf &amp; Guttman Informational [Page 84]</span></pre>
4701 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-85" ></span>
4702 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4703
4704
4705 <span class="h3"><a class="selflink" id="section-5.8" href="#section-5.8">5.8</a>. Example</span>
4706
4707 In this example, a printer server advertises its availability to
4708 clients. Additionally, the server advertises a service template for
4709 use by client software in validating service requests:
4710
4711
4712 //Get the Advertiser and TemplateRegistry.
4713
4714 Advertiser adv = null;
4715 TemplateRegistry tr = null
4716
4717 try {
4718
4719 adv = ServiceLocationManager.getAdvertiser("en");
4720
4721 tr = TemplateRegistry.getTemplateRegistry();
4722
4723 } catch( ServiceLocationException ex ) { } //Deal with error.
4724
4725 if( adv == null ) {
4726
4727 //Serious error as printer can't be registered
4728 // if the implementation doesn't support SA
4729 // functionality.
4730
4731 }
4732
4733 //Get the printer's attributes, from a file or
4734 // otherwise. We assume that the attributes
4735 // conform to the template, otherwise, we
4736 // could register the template here and verify
4737 // them.
4738
4739 Vector attributes = getPrinterAttributes();
4740
4741 //Create the service: URL for the printer.
4742
4743 ServiceURL printerURL =
4744 new ServiceURL(
4745 "service:printer:lpr://printshop/color2",
4746 ServiceURL.LIFETIME_MAXIMUM);
4747
4748 try {
4749
4750 //Register the printer.
4751
4752 adv.register(printerURL, attributes);
4753
4754
4755
4756 <span class="grey">Kempf &amp; Guttman Informational [Page 85]</span></pre>
4757 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-86" ></span>
4758 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4759
4760
4761 //If the template registry is available,
4762 // register the printer's template.
4763
4764 if( tr != null ) {
4765 tr.registerServiceTemplate(
4766 new ServiceType("service:printer:lpr"),
4767 "<a href="http://shop.arv/printer/printer-lpr.slp">http://shop.arv/printer/printer-lpr.slp</a>",
4768 new Locale("en",""),
4769 "1.0");
4770
4771 }
4772
4773 } catch( ServiceLocationException ex ) { } //Deal with error.
4774
4775
4776 Suppose a client is looking for color printer. The following code is
4777 used to issue a request for printer advertisements:
4778
4779
4780 Locator loc = null;
4781 TemplateRegistry tr = null;
4782
4783 try {
4784
4785 loc = ServiceLocationManager.getLocator("en");
4786
4787 } catch( ServiceLocationException ex ) { } //Deal with error.
4788
4789 if( loc == null ) {
4790
4791 //Serious error as client can't be located
4792 // if the implementation doesn't support
4793 // UA functionality.
4794
4795 }
4796
4797 //We want a color printer that does CMYK
4798 // and prints at least 600 dpi.
4799
4800 String query = "(&amp;(marker-type=CMYK)(resolution=600))";
4801
4802 //Get scopes.
4803
4804 Vector scopes = ServiceLocationManager.findScopes();
4805
4806 Enumeration services;
4807
4808 try {
4809
4810
4811
4812 <span class="grey">Kempf &amp; Guttman Informational [Page 86]</span></pre>
4813 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-87" ></span>
4814 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4815
4816
4817 services =
4818 loc.findServices(new ServiceType("service:printer"),scopes,query);
4819
4820 } catch { } //Deal with error.
4821
4822 if (services.hasMoreElements() ) {
4823
4824 //Printers can now be used.
4825 ServiceURL surl = (ServiceURL) services.next();
4826
4827 Socket sock = new Socket(surl.getHost, surl.getPort());
4828
4829 // Use the Socket...
4830
4831 }
4832
4833
4834 <span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Internationalization Considerations</span>
4835
4836 <span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. service URL</span>
4837
4838 The service URL itself must be encoded using the rules set forth in
4839 [<a href="#ref-2" title="&quot;Uniform Resource Identifiers (URI): Generic Syntax&quot;">2</a>]. The character set encoding is limited to specific ranges within
4840 the UTF-8 character set [<a href="#ref-3" title="&quot;UTF-8, a transformation format of ISO 10646&quot;">3</a>].
4841
4842 The attribute information associated with the service URL must be
4843 expressed in UTF-8. See [<a href="#ref-8" title="&quot;Service Templates and Service: Schemes&quot;">8</a>] for attribute internationalization
4844 guidelines.
4845
4846 <span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Character Set Encoding</span>
4847
4848 Configuration and serialized registration files are encoded in the
4849 UTF-8 character set [<a href="#ref-3" title="&quot;UTF-8, a transformation format of ISO 10646&quot;">3</a>]. This is fully compatible with US-ASCII
4850 character values. C platforms that do not support UTF-8 are required
4851 to check the top bit of input bytes to determine whether the incoming
4852 character is multibyte. If it is, the character should be dealt with
4853 accordingly. This should require no additional implementation
4854 effort, since the SLP wire protocol requires that strings are encoded
4855 as UTF-8. C platforms without UTF-8 support need to supply their own
4856 support, if only in the form of multibyte string handling.
4857
4858 At the API level, the character encoding is specified to be Unicode
4859 for Java and UTF-8 for C. Unicode is the default in Java. For C, the
4860 standard US-ASCII 8 bits per character, null terminated C strings are
4861 a subset of the UTF-8 character set, and so work in the API. Because
4862 the C API is very simple, the API library needs to do a minimum of
4863 processing on UTF-8 strings. The strings primarily just need to be
4864 reflected into the outgoing SLP messages, and reflected out of the
4865
4866
4867
4868 <span class="grey">Kempf &amp; Guttman Informational [Page 87]</span></pre>
4869 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-88" ></span>
4870 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4871
4872
4873 API from incoming SLP messages.
4874
4875 <span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a>. Language Tagging</span>
4876
4877 All SLP requests and registrations are tagged to indicate in which
4878 language the strings included are encoded. This allows multiple
4879 languages to be supported. It also presents the possibility that
4880 error conditions result when a request is made in a language that is
4881 not supported. In this case, an error is only returned when there is
4882 data available, but not obtainable in the language requested.
4883
4884 The dialect portion of the Language Tag is used on 'best effort'
4885 basis for matching strings by SLP. Dialects that match are preferred
4886 over those which don't. Dialects that do not match will not prevent
4887 string matching or comparisons from occurring.
4888
4889 <span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Security Considerations</span>
4890
4891 Security is handled within the API library and is not exposed to API
4892 clients except in the form of exceptions. The
4893 net.slp.securityEnabled, property determines whether an SA client's
4894 messages are signed, but a UA client should be prepared for an
4895 authentication exception at any time, because it may contact a DA
4896 with authenticated advertisements.
4897
4898 An adversary could delete valid service advertisements, provide false
4899 service information and deny UAs knowledge of existing services
4900 unless the mechanisms in SLP for authenticating SLP messages are
4901 used. These mechanisms allow DAAdverts, SAAdverts, Service URLs and
4902 Service Attributes to be verified using digital cryptography. For
4903 this reason, all SLP agents should be configured to use SLP SPIs.
4904 See [<a href="#ref-7" title="&quot;Service Location Protocol, Version 2&quot;">7</a>] for a description of how this mechanism works.
4905
4906 <span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Acknowledgements</span>
4907
4908 The authors would like to thank Don Provan for his pioneering work
4909 during the initial stages of API definition.
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924 <span class="grey">Kempf &amp; Guttman Informational [Page 88]</span></pre>
4925 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-89" ></span>
4926 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4927
4928
4929 <span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. References</span>
4930
4931 [<a id="ref-1">1</a>] Bradner, S., "Key Words for Use in RFCs to Indicate
4932 Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
4933
4934 [<a id="ref-2">2</a>] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
4935 Resource Identifiers (URI): Generic Syntax", <a href="./rfc2396">RFC 2396</a>,
4936 August 1998.
4937
4938 [<a id="ref-3">3</a>] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
4939 <a href="./rfc2279">RFC 2279</a>, January 1998.
4940
4941 [<a id="ref-4">4</a>] Howes, T., "The String Representation of LDAP Search Filters",
4942 <a href="./rfc2254">RFC 2254</a> December 1997.
4943
4944 [<a id="ref-5">5</a>] Crocker, D. and P. Overell, "Augmented BNF for Syntax
4945 Specifications: ABNF", <a href="./rfc2234">RFC 2234</a>, November 1997.
4946
4947 [<a id="ref-6">6</a>] Alvestrand, H., "Tags for the Identification of Languages",
4948 <a href="./rfc1766">RFC 1766</a>, March 1995.
4949
4950 [<a id="ref-7">7</a>] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service
4951 Location Protocol, Version 2", <a href="./rfc2608">RFC 2608</a>, June 1999.
4952
4953 [<a id="ref-8">8</a>] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and
4954 Service: Schemes", <a href="./rfc2609">RFC 2609</a>, June 1999.
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980 <span class="grey">Kempf &amp; Guttman Informational [Page 89]</span></pre>
4981 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-90" ></span>
4982 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
4983
4984
4985 <span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>. Authors' Addresses</span>
4986
4987 Questions about this memo can be directed to:
4988
4989 James Kempf
4990 Sun Microsystems
4991 901 San Antonio Rd.
4992 Palo Alto, CA, 94303
4993 USA
4994
4995 Phone: +1 650 786 5890
4996 Fax: +1 650 786 6445
4997 EMail: [email protected]
4998
4999
5000 Erik Guttman
5001 Sun Microsystems
5002 Bahnstr. 2
5003 74915 Waibstadt
5004 Germany
5005
5006 Phone: +49 7263 911 701
5007 EMail: [email protected]
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036 <span class="grey">Kempf &amp; Guttman Informational [Page 90]</span></pre>
5037 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-91" ></span>
5038 <span class="grey"><a href="./rfc2614">RFC 2614</a> Service Location API June 1999</span>
5039
5040
5041 <span class="h2"><a class="selflink" id="section-11" href="#section-11">11</a>. Full Copyright Statement</span>
5042
5043 Copyright (C) The Internet Society (1999). All Rights Reserved.
5044
5045 This document and translations of it may be copied and furnished to
5046 others, and derivative works that comment on or otherwise explain it
5047 or assist in its implementation may be prepared, copied, published
5048 and distributed, in whole or in part, without restriction of any
5049 kind, provided that the above copyright notice and this paragraph are
5050 included on all such copies and derivative works. However, this
5051 document itself may not be modified in any way, such as by removing
5052 the copyright notice or references to the Internet Society or other
5053 Internet organizations, except as needed for the purpose of
5054 developing Internet standards in which case the procedures for
5055 copyrights defined in the Internet Standards process must be
5056 followed, or as required to translate it into languages other than
5057 English.
5058
5059 The limited permissions granted above are perpetual and will not be
5060 revoked by the Internet Society or its successors or assigns.
5061
5062 This document and the information contained herein is provided on an
5063 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
5064 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
5065 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
5066 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
5067 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
5068
5069 Acknowledgement
5070
5071 Funding for the RFC Editor function is currently provided by the
5072 Internet Society.
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092 Kempf &amp; Guttman Informational [Page 91]
5093 </pre>