idnits 2.17.1 

draft-ietf-svrloc-api-09.txt:

  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

  ** Looks like you're using RFC 2026 boilerplate.  This must be updated to
     follow RFC 3978/3979, as updated by RFC 4748.


  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

  ** Missing expiration date.  The document expiration date should appear on
     the first and last page.

  ** The document seems to lack a 1id_guidelines paragraph about
     Internet-Drafts being working documents. 

  ** The document seems to lack a 1id_guidelines paragraph about the list of
     current Internet-Drafts -- however, there's a paragraph with a matching
     beginning. Boilerplate error?

  ** The document seems to lack a 1id_guidelines paragraph about the list of
     Shadow Directories -- however, there's a paragraph with a matching
     beginning. Boilerplate error?

  == No 'Intended status' indicated for this document; assuming Proposed
     Standard


  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

  ** The document seems to lack an IANA Considerations section.  (See Section
     2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
     when there are no actions for IANA.)

  ** The document seems to lack separate sections for Informative/Normative
     References.  All references will be assumed normative when checking for
     downward references.

  ** There are 5 instances of too long lines in the document, the longest one
     being 6 characters in excess of 72.

  == There are 49 instances of lines with non-RFC2606-compliant FQDNs in the
     document.

  == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses
     in the document.  If these are example addresses, they should be changed.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
     match the current year

  == Line 1301 has weird spacing: '...    int   s_iP...'

  == Line 1649 has weird spacing: '...PHandle   hSLP...'

  == Line 1654 has weird spacing: '...Boolean  fresh...'

  == Line 1730 has weird spacing: '...PHandle  hSLP,...'

  == Line 1771 has weird spacing: '...PHandle   hSLP...'

  == (4 more instances...)

  -- The document seems to lack a disclaimer for pre-RFC5378 work, but may
     have content which was first submitted before 10 November 2008.  If you
     have contacted all the original authors and they are all willing to grant
     the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
     this comment.  If not, you may need to add the pre-RFC5378 disclaimer. 
     (See the Legal Provisions document at
     https://trustee.ietf.org/license-info for more information.)

  -- Couldn't find a document date in the document -- date freshness check
     skipped.

  -- Found something which looks like a code comment -- if you have code
     sections in the document, please surround them with '<CODE BEGINS>' and
     '<CODE ENDS>' lines.


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

     (See RFCs 3967 and 4897 for information about using normative references
     to lower-maturity documents in RFCs)

  ** Obsolete normative reference: RFC 2396 (ref. '2') (Obsoleted by RFC 3986)

  ** Obsolete normative reference: RFC 2279 (ref. '3') (Obsoleted by RFC 3629)

  ** Obsolete normative reference: RFC 2254 (ref. '4') (Obsoleted by RFC
     4510, RFC 4515)

  ** Obsolete normative reference: RFC 2234 (ref. '5') (Obsoleted by RFC 4234)

  ** Obsolete normative reference: RFC 1766 (ref. '6') (Obsoleted by RFC
     3066, RFC 3282)

  == Outdated reference: A later version (-15) exists of
     draft-ietf-svrloc-protocol-v2-12


     Summary: 13 errors (**), 0 flaws (~~), 11 warnings (==), 3 comments (--).

     Run idnits with the --verbose option for more detailed information about
     the items above.

--------------------------------------------------------------------------------

1	Service Location Working Group                               James Kempf
2	INTERNET DRAFT                                              Erik Guttman
3	5 April  1999                                           Sun Microsystems

5	                      An API for Service Location
6	                      draft-ietf-svrloc-api-09.txt

8	Status of This Memo

10	   This document is a submission by the Service Location Working Group
11	   of the Internet Engineering Task Force (IETF).  Comments should be
12	   submitted to the srvloc@srvloc.org mailing list.

14	   Distribution of this memo is unlimited.

16	   This document is an Internet-Draft and is in full conformance with
17	   all provisions of Section 10 of RFC2026.  Internet-Drafts are working
18	   documents of the Internet Engineering Task Force (IETF), its areas,
19	   and its working groups.  Note that other groups may also distribute
20	   working documents as Internet-Drafts.

22	   Internet-Drafts are draft documents valid for a maximum of six months
23	   and may be updated, replaced, or obsoleted by other documents at
24	   any time.  It is inappropriate to use Internet-Drafts as reference
25	   material or to cite them other than as "work in progress."

27	   The list of current Internet-Drafts can be accessed at:

29	      http://www.ietf.org/ietf/1id-abstracts.txt

31	   The list of Internet-Draft Shadow Directories can be accessed at:

33	      http://www.ietf.org/shadow.html.

35	Abstract

37	   The Service Location Protocol (SLP) provides a new way for clients to
38	   dynamically discovery network services.  With SLP, it is simple to
39	   offer highly available services that require no user configuration or
40	   assistance from network administrators prior to use.  This document
41	   describes standardized APIs for SLP in C and Java.  The APIs are
42	   modular and are designed to allow implementations to offer just the
43	   feature set needed.  In addition, standardized file formats for
44	   configuration and serialized registrations are defined, allowing SLP
45	   agents to set network and other parameters in a portable way.  The
46	   serialized file format allows legacy services to be registered with
47	   SLP directory agents in cases where modifying the legacy service
48	   program code is difficult or impossible, and to portably exchange a
49	   registration database.

51	                                Contents

53	Status of This Memo                                                    i

55	Abstract                                                              ii

57	 1. Introduction                                                       1
58	     1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . .    1
59	     1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . .    2

61	 2. File Formats                                                       4
62	     2.1. Configuration File Format . . . . . . . . . . . . . . . .    5
63	           2.1.1. DA configuration  . . . . . . . . . . . . . . . .    6
64	           2.1.2. Static Scope Configuration  . . . . . . . . . . .    7
65	           2.1.3. Tracing and Logging . . . . . . . . . . . . . . .    8
66	           2.1.4. Serialized Proxy Registrations  . . . . . . . . .    9
67	           2.1.5. Network Configuration Properties  . . . . . . . .    9
68	           2.1.6. SA Configuration  . . . . . . . . . . . . . . . .   11
69	           2.1.7. UA Configuration  . . . . . . . . . . . . . . . .   12
70	           2.1.8. Security  . . . . . . . . . . . . . . . . . . . .   13
71	     2.2. Multihomed Machines . . . . . . . . . . . . . . . . . . .   13
72	     2.3. Serialized Registration File  . . . . . . . . . . . . . .   14
73	     2.4. Processing Serialized Registration and Configuration Files  15

75	 3. Binding Independent Implementation Considerations                 16
76	     3.1. Multithreading  . . . . . . . . . . . . . . . . . . . . .   16
77	     3.2. Asynchronous and Incremental  . . . . . . . . . . . . . .   16
78	     3.3. Type Checking for Service Types . . . . . . . . . . . . .   16
79	     3.4. Refreshing Registrations  . . . . . . . . . . . . . . . .   17
80	     3.5. Configuration File Processing . . . . . . . . . . . . . .   17
81	     3.6. Attribute Types . . . . . . . . . . . . . . . . . . . . .   17
82	     3.7. Removal of Duplicates . . . . . . . . . . . . . . . . . .   17
83	     3.8. Character Set Encoding  . . . . . . . . . . . . . . . . .   18
84	     3.9. Error Semantics . . . . . . . . . . . . . . . . . . . . .   18
85	    3.10. Modular Implementations . . . . . . . . . . . . . . . . .   21
86	    3.11. Handling Special Service Types  . . . . . . . . . . . . .   21
87	    3.12. Scope Discovery and Handling  . . . . . . . . . . . . . .   22

89	 4. C Language Binding                                                23
90	     4.1. Constant Types  . . . . . . . . . . . . . . . . . . . . .   24
91	           4.1.1. URL Lifetimes . . . . . . . . . . . . . . . . . .   24
92	           4.1.2. Error Codes . . . . . . . . . . . . . . . . . . .   24
93	           4.1.3. SLPBoolean  . . . . . . . . . . . . . . . . . . .   25
94	     4.2. Struct Types  . . . . . . . . . . . . . . . . . . . . . .   26
95	           4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . . .   26
96	           4.2.2. SLPHandle . . . . . . . . . . . . . . . . . . . .   27

98	     4.3. Callbacks . . . . . . . . . . . . . . . . . . . . . . . .   27
99	           4.3.1. SLPRegReport  . . . . . . . . . . . . . . . . . .   28
100	           4.3.2. SLPSrvTypeCallback  . . . . . . . . . . . . . . .   28
101	           4.3.3. SLPSrvURLCallback . . . . . . . . . . . . . . . .   29
102	           4.3.4. SLPAttrCallback . . . . . . . . . . . . . . . . .   31
103	     4.4. Opening and Closing an SLPHandle  . . . . . . . . . . . .   32
104	           4.4.1. SLPOpen . . . . . . . . . . . . . . . . . . . . .   32
105	           4.4.2. SLPClose  . . . . . . . . . . . . . . . . . . . .   33
106	     4.5. Protocol API  . . . . . . . . . . . . . . . . . . . . . .   34
107	           4.5.1. SLPReg  . . . . . . . . . . . . . . . . . . . . .   34
108	           4.5.2. SLPDereg  . . . . . . . . . . . . . . . . . . . .   35
109	           4.5.3. SLPDelAttrs . . . . . . . . . . . . . . . . . . .   36
110	           4.5.4. SLPFindSrvTypes . . . . . . . . . . . . . . . . .   37
111	           4.5.5. SLPFindSrvs . . . . . . . . . . . . . . . . . . .   39
112	           4.5.6. SLPFindAttrs  . . . . . . . . . . . . . . . . . .   40
113	     4.6. Miscellaneous Functions . . . . . . . . . . . . . . . . .   42
114	           4.6.1. SLPGetRefreshInterval . . . . . . . . . . . . . .   42
115	           4.6.2. SLPFindScopes . . . . . . . . . . . . . . . . . .   42
116	           4.6.3. SLPParseSrvURL  . . . . . . . . . . . . . . . . .   43
117	           4.6.4. SLPEscape . . . . . . . . . . . . . . . . . . . .   44
118	           4.6.5. SLPUnescape . . . . . . . . . . . . . . . . . . .   45
119	           4.6.6. SLPFree . . . . . . . . . . . . . . . . . . . . .   46
120	           4.6.7. SLPGetProperty  . . . . . . . . . . . . . . . . .   46
121	           4.6.8. SLPSetProperty  . . . . . . . . . . . . . . . . .   47
122	     4.7. Implementation Notes  . . . . . . . . . . . . . . . . . .   48
123	           4.7.1. Refreshing Registrations  . . . . . . . . . . . .   48
124	           4.7.2. Syntax for String Parameters  . . . . . . . . . .   48
125	           4.7.3. Client Side Syntax Checking . . . . . . . . . . .   48
126	           4.7.4. System Properties . . . . . . . . . . . . . . . .   49
127	           4.7.5. Memory Management . . . . . . . . . . . . . . . .   49
128	           4.7.6. Asynchronous and Incremental Return Semantics . .   49
129	     4.8. Example . . . . . . . . . . . . . . . . . . . . . . . . .   50

131	 5. Java Language Binding                                             54
132	     5.1. Introduction  . . . . . . . . . . . . . . . . . . . . . .   54
133	     5.2. Exceptions and Errors . . . . . . . . . . . . . . . . . .   55
134	           5.2.1. Class ServiceLocationException  . . . . . . . . .   55
135	     5.3. Basic Data Structures . . . . . . . . . . . . . . . . . .   56
136	           5.3.1. Interface ServiceLocationEnumeration  . . . . . .   56
137	           5.3.2. Class ServiceLocationAttribute  . . . . . . . . .   57
138	           5.3.3. Class ServiceType . . . . . . . . . . . . . . . .   59
139	           5.3.4. Class ServiceURL  . . . . . . . . . . . . . . . .   62
140	     5.4. SLP Access Interfaces . . . . . . . . . . . . . . . . . .   65
141	           5.4.1. Interface Advertiser  . . . . . . . . . . . . . .   65
142	           5.4.2. Interface Locator . . . . . . . . . . . . . . . .   67
143	     5.5. The Service Location Manager  . . . . . . . . . . . . . .   71
144	           5.5.1. Class ServiceLocationManager  . . . . . . . . . .   71
145	     5.6. Service Template Introspection  . . . . . . . . . . . . .   72
146	           5.6.1. Abstract Class TemplateRegistry . . . . . . . . .   72
147	           5.6.2. Interface ServiceLocationAttributeVerifier  . . .   75
148	           5.6.3. Interface ServiceLocationAttributeDescriptor  . .   77
149	     5.7. Implementation Notes  . . . . . . . . . . . . . . . . . .   80
150	           5.7.1. Refreshing Registrations  . . . . . . . . . . . .   80
151	           5.7.2. Parsing Alternate Transports in ServiceURL  . . .   80
152	           5.7.3. String Attribute Values . . . . . . . . . . . . .   80
153	           5.7.4. Client Side Syntax Checking . . . . . . . . . . .   80
154	           5.7.5. Language Locale Handling  . . . . . . . . . . . .   81
155	           5.7.6. Setting SLP System Properties . . . . . . . . . .   81
156	           5.7.7. Multithreading  . . . . . . . . . . . . . . . . .   82
157	           5.7.8. Modular Implementations . . . . . . . . . . . . .   82
158	           5.7.9. Asynchronous and Incremental Return Semantics . .   82
159	     5.8. Example . . . . . . . . . . . . . . . . . . . . . . . . .   83

161	 6. Internationalization Considerations                               85
162	     6.1. service URL . . . . . . . . . . . . . . . . . . . . . . .   85
163	     6.2. Character Set Encoding  . . . . . . . . . . . . . . . . .   86
164	     6.3. Language Tagging  . . . . . . . . . . . . . . . . . . . .   86

166	 7. Security Considerations                                           86

168	 8. Acknowledgements                                                  87

170	 9. Full Copyright Statement                                          89

172	1. Introduction

174	   The Service Location API is designed for standardized access to the
175	   Service Location Protocol (SLP). The APIs allow client and service
176	   programs to be be written or modified in a very simple manner to
177	   provide dynamic service discovery and selection.  Bindings in the
178	   C and Java languages are defined in this document.  In addition,
179	   standardized formats for configuration files and for serialized
180	   registration files are presented.  These files allow SLP agents
181	   to configure network parameters, to register legacy services that
182	   have not been SLP enabled, and to portably exchange registration
183	   databases.

185	1.1. Goals

187	   The overall goal of the API is to enable source portability of
188	   applications that use the API between different implementations of
189	   SLP. The result should facilitate the adoption of SLP, and conversion
190	   of clients and service programs to SLP.

192	   The goals of the C binding are to create a minimal but complete
193	   access to the functionality of the SLP protocol, allowing for simple
194	   memory management and limited code size.

196	   The Java API provides for modular implementations (where unneeded
197	   features can be omitted) and an object oriented interface to the
198	   complete set of SLP data and functionality.

200	   The standardized configuration file and serialized file formats
201	   provide a simple syntax with complete functional coverage of
202	   the protocol, but without system dependent properties and secure
203	   information.

205	1.2. Terminology

207	   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
208	   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
209	   document are to be interpreted as described in RFC 2119  [1].

211	      Service Location Protocol (SLP)

213	         The underlying protocol allowing dynamic and scalable service
214	         discovery.  This protocol is specified in the Service Location
215	         Protocol Version 2 [7].

217	      SLP framework

219	         When a 'Service Location framework' is mentioned, it refers to
220	         both the SLP implementation and interface implementation; i.e.
221	         whatever provides the SLP functionality to user level programs.
222	         This includes remote agents.

224	      Directory Agent (DA)

226	         A service that automatically gathers service advertisements
227	         from SAs in order to provide them to UAs.

229	      User Agent (UA)

231	         This is the Service Location process or library that allows
232	         SLP requests to be made on behalf of a client process.  UAs
233	         automatically direct requests to DAs when they exist.  In their
234	         absence, UAs make requests to SAs.

236	      Service Agent (SA)

238	         This is the Service Location process or library that allows
239	         service software to register and deregister itself with the SLP
240	         framework.  SAs respond to UA service requests, detect DAs and
241	         register service advertisements with them.

243	      SA Server

245	         Many operating system platforms only allow a single process to
246	         listen on a particular port number.  Since SAs are required
247	         to listen on a multicast address for SLP service requests,
248	         implementations of the SLP framework on such platforms that
249	         want to support multiple SAs on one machine need to arrange for
250	         a single process to do the listening while the advertising SAs
251	         communicate with that process through another mechanism.  The
252	         single listening process is called an SA server.  SA servers
253	         share many characteristics with DAs, but they are not the same.

255	      Service Advertisement

257	         A URL possibly combined with service attributes.  These are
258	         made available to UAs by SAs, either directly or via a DA.

260	      Locale

262	         The language localization that applies to strings passed into
263	         or returned from the SLP API. The Locale is expressed using a
264	         Language Tag [6].  All attribute strings are associated with a
265	         particular locale.  The locale is completely orthogonal to the
266	         ANSI C locale.  The SLP locale is mapped into the Java locale
267	         in the Java API.

269	      Service Template

271	         A document that describes the syntax of the URL for a given
272	         service type and a definition of all service attributes
273	         including the meaning, defaults, and constraints on values the
274	         attributes may take.  See [8] for more information on service
275	         templates.

277	      The service:  URL

279	         A service of a particular type announces its availability
280	         with a service:  URL that includes its service access point
281	         (domain name or IP address, and possibly its port number) and
282	         optionally basic configuration parameters.  The syntax of the
283	         service:  URL is defined in the service template.  Other URL's
284	         can be used in service advertisements if desired.

286	      Service Attributes

288	         The attributes associated with a given service.  The values
289	         that can be assigned to service attributes are defined by the
290	         service template.

292	      Scope

294	         A string used to control the availability of service
295	         advertisements.  Every SLP Agent is configured with one or more
296	         scope strings.  Scopes are assigned by site administrators to
297	         group services for many purposes, but chiefly as a means of
298	         scalability.  DAs store only services advertised having a scope
299	         string matching the scopes with which they are configured.

301	      Naming Authority (NA)

303	         This is a 'suffix' to the service type string.  It completely
304	         changes the meaning of the service type.  NAs are used
305	         for private definitions of well known Service Types and
306	         experimental Service Type extensions.  The default NA is
307	         "IANA", which must not be explicitly included.  Service types
308	         with the IANA naming authority are registered with the Internet
309	         Assigned Numbers Authority (see [8] for more information on the
310	         registration procedure).

312	2. File Formats

314	   This section describes the configuration and serialized registration
315	   file formats.  Both files are defined in the UTF-8 character set [3].

317	   Attribute tags and values in the serialized registration file
318	   require SLP reserved characters to be escaped.  The SLP reserved
319	   characters are `(', `)', `,', `\', `!', `<', `=', `>', `~' and
320	   control characters (characters with UTF codes less than 0x0020 and
321	   the character 0x007f, which is US-ASCII DEL). The escapes are formed
322	   exactly as for the wire protocol, i.e.  a backslash followed by two
323	   hex digits representing the character.  For example, the escape
324	   for ',' is '\2c'.  In addition, the characters `\n', `\r', `\t',
325	   and `_' are prohibited from attribute tags by the SLP wire syntax
326	   grammar. [7]

328	   In serialized registration files, escaped strings beginning with
329	   `\ff`, an encoding for a nonUTF-8 character, are treated as opaques.
330	   Exactly as in the wire protocol, syntactically correct opaque
331	   encodings consist of a string beginning with `\ff` and containing
332	   *only* escaped characters that are transformed to bytes.  Such
333	   strings are only syntactically correct in the serialized registration
334	   file as attribute values.  In other cases, whenever an escape is
335	   encountered and the character is not an SLP reserved character, an
336	   error is signaled.

338	   Escaped characters in URLs in serialized registration files use the
339	   URL escape convention. [2].

341	   Property names and values in the configuration file have a few
342	   reserved characters that are involved in file's lexical definition.
343	   The characters '.'  and '=' are reserved in property names and
344	   must be escape.  The characters ',', '(', and ')' are reserved in
345	   property values and must be escaped.  In addition, scope names in the
346	   net.slp.useScopes property use the SLP wire format escape convention
347	   for SLP reserved characters.  This simplifies implementation, since
348	   the same code can be used to unescape scope names as is used in
349	   processing the serialized registration file or for formatting wire
350	   messages.

352	   On platforms that only support US-ASCII and not UTF-8, the upper
353	   bit of bytes incoming from the configuration and registration
354	   files determines whether the character is US-ASCII or not US-ASCII.
355	   According to the standard UTF-8 encoding, the upper bit is zero if
356	   the character is US-ASCII and one if the character is multibyte
357	   and thus not US-ASCII. Platforms without intrinsic UTF-8 support
358	   are required to parse the multibyte character and store it in an
359	   appropriate internal format.  Support for UTF-8 is required to
360	   implement the SLP protocol (see [7]), and can therefore be used in
361	   file processing as well.

363	   The location and name of the configuration file is system-dependent,
364	   but implementations of the API are encouraged to locate it together
365	   with other configuration files and name it consistently.

367	2.1. Configuration File Format

369	   The configuration file format consists of a newline delimited list
370	   of zero or more property definitions.  Each property definition
371	   corresponds to a particular configurable SLP, network, or other
372	   parameter in one or more of the three SLP agents.  The file format
373	   grammar in ABNF [5] syntax is:

375	      config-file   =  line-list
376	      line-list     =  line / line line-list
377	      line          =  property-line / comment-line
378	      comment-line  =  ( "#" / ";" ) 1*allchar newline
379	      property-line =  property newline
380	      property      =  tag "=" value-list
381	      tag           =  prop / prop "." tag
382	      prop          =  1*tagchar
383	      value-list    =  value / value "," value-list
384	      value         =  int / bool /
385	                       "(" value-list ")" / string
386	      int           =  1*DIGIT
387	      bool          =  "true" / "false" / "TRUE" / "FALSE"
388	      newline       =  CR / ( CRLF )
389	      string        =  1*stringchar
390	      tagchar       =  DIGIT / ALPHA / tother / escape
391	      tother        =  %x21-%x2d / %x2f /
392	                       %x3a / %x3c-%x40 /
393	                       %x5b-%x60 / %7b-%7e
394	                       ; i.e., all characters except `.',
395	                       ; and `='.
396	      stringchar    =  DIGIT / ALPHA / sother / escape
397	      sother        =  %x21-%x29 / %x2a-%x2b /
398	                       %x2d-%x2f / %x3a-%x40 /
399	                       %x5b-%x60 / %7b-%7e
400	                       ; i.e., all characters except `,'
401	      allchar       =  DIGIT / ALPHA / HTAB / SP
402	      escape        =  "\" HEXDIG HEXDIG
403	                       ; Used for reserved characters

405	   With the exception of net.slp.useScopes, net.slp.DAAddresses,
406	   and net.slp.isBroadcastOnly, all other properties can be changed
407	   through property accessors in the C and Java APIs.  The property
408	   accessors only change the property values in the running agent
409	   program and do not affect the values in the configuration file.  The
410	   net.slp.useScopes and net.slp.DAAddresses properties are read-only
411	   because they control the agent's view of the scopes and DAs and
412	   are therefore critical to the function of the API scope discovery
413	   algorithm.  Attempts to modify them are unlikely to yield productive
414	   results, and could harm the ability of the agent to find scopes and
415	   use DAs.  The net.slp.isBroadcastOnly property is read-only because
416	   the API library needs to configure networking upon start up and
417	   changing this property might invalidate the configuration.  Whether
418	   the local network uses broadcast or multicast is not likely to change
419	   during the course of the program's execution.

421	   The properties break down into the following subsections describes an
422	   area and its properties.

424	2.1.1. DA configuration

426	   Important configuration properties for DAs are included in this
427	   section.  These are:

429	      net.slp.isDA

431	         A boolean indicating if the SLP server is to act as a DA. If
432	         false, not run as a DA. Default is false.

434	      net.slp.DAHeartBeat

436	         A 32 bit integer giving the number of seconds for the
437	         DA heartbeat.  Default is 3 hours (10800 seconds).  This
438	         property corresponds to the protocol specification parameter
439	         CONFIG_DA_BEAT [7].  Ignored if isDA is false.

441	      net.slp.DAAttributes

443	         A comma-separated list of parenthesized attribute/value list
444	         pairs that the DA must advertise in DAAdverts.  The property
445	         must be in the SLP attribute list wire format, including
446	         escapes for reserved characters. [7]

448	2.1.2. Static Scope Configuration

450	   These properties allow various aspects of scope handling to be
451	   configured.

453	      net.slp.useScopes

455	         A value-list of strings indicating the only scopes a UA or SA
456	         is allowed to use when making requests or registering, or the
457	         scopes a DA must support.  If not present for the DA and SA,
458	         then in the absence of scope information from DHCP, the default
459	         scope "DEFAULT" is used.  If not present for the UA, and there
460	         is no scope information available from DHCP, then the user
461	         scoping model is in force.  Active and passive DA discovery
462	         or SA discovery are used for scope discovery, and the scope
463	         "DEFAULT" is used if no other information is available.  If a
464	         DA or SA gets another scope in a request, a SCOPE_NOT_SUPPORTED
465	         error should be returned, unless the request was multicast, in
466	         which case it should be dropped.  If a DA gets another scope in
467	         a registration, a SCOPE_NOT_SUPPORTED error must be returned.
468	         Unlike other properties, this property is "read-only", so
469	         attempts to change it after the configuration file has been
470	         read are ignored.  See Section 3.12 for the algorithm the API
471	         uses in determining what scope information to present.

473	      net.slp.DAAddresses

475	         A value-list of IP addresses or DNS resolvable host names
476	         giving the SLPv2 DAs to use for statically configured UAs and
477	         SAs.  Ignored by DAs (unless the DA is also an SA server).
478	         Default is none.  Unlike other properties, this property is
479	         "read-only", so attempts to change it after the configuration
480	         file has been read are ignored.

482	         The following grammar describes the property:

484	               addr-list     =  addr / addr "," addr-list
485	               addr          =  fqdn / hostnumber
486	               fqdn          =  ALPHA / ALPHA *[ anum / "-" ] anum
487	               anum          =  ALPHA / DIGIT
488	               hostnumber    =  1*3DIGIT 3("." 1*3DIGIT)

490	         An example is:

492	                sawah,mandi,sambal

494	         IP addresses can be used instead of host names in networks
495	         where DNS is not deployed, but network administrators are
496	         reminded that using IP addresses will complicate machine
497	         renumbering, since the SLP configuration property files
498	         in statically configured networks will have to be changed.
499	         Similarly, if host names are used, implementors must be careful
500	         that a name service is available before SLP starts, in other
501	         words, SLP cannot be used to find the name service.

503	2.1.3. Tracing and Logging

505	   This section allows tracing and logging information to be printed by
506	   the various agents.

508	      net.slp.traceDATraffic

510	         A boolean controlling printing of messages about traffic with
511	         DAs.  Default is false.

513	      net.slp.traceMsg

515	         A boolean controlling printing of details on SLP messages.
516	         The fields in all incoming messages and outgoing replies are
517	         printed.  Default is false.

519	      net.slp.traceDrop

521	         A boolean controlling printing details when a SLP message is
522	         dropped for any reason.  Default is false.

524	      net.slp.traceReg

526	         A boolean controlling dumps of all registered services upon
527	         registration and deregistration.  If true, the contents
528	         of the DA or SA server are dumped after a registration or
529	         deregistration occurs.  Default is false.

531	2.1.4. Serialized Proxy Registrations

533	   These properties control the reading and writing of serialized
534	   registrations.

536	      net.slp.serializedRegURL

538	         A string containing a URL pointing to a document containing
539	         serialized registrations that should be processed when the DA
540	         or SA server starts up.  Default is none.

542	2.1.5. Network Configuration Properties

544	   The properties in this section allow various network configuration
545	   properties to be set.

547	      net.slp.isBroadcastOnly

549	         A boolean indicating if broadcast should be used instead of
550	         multicast.  Like the net.slp.useScopes and net.slp.DAAddresses
551	         properties, this property is "read-only", so attempts to change
552	         it after the configuration file has been read are ignored.
553	         Default is false.

555	      net.slp.passiveDADetection

557	         A boolean indicating whether passive DA detection should be
558	         used.  Default is true.

560	      net.slp.multicastTTL

562	         A positive integer less than or equal to 255, giving the
563	         multicast TTL. Default is 255.

565	      net.slp.DAActiveDiscoveryInterval

567	         A 16 bit positive integer giving the number of seconds
568	         between DA active discovery queries.  Default is 900 seconds
569	         (15 minutes).  This property corresponds to the protocol
570	         specification parameter CONFIG_DA_FIND [7].  If the property is
571	         set to zero, active discovery is turned off.  This is useful
572	         when the DAs available are explicitly restricted to those
573	         obtained from DHCP or the net.slp.DAAddresses property.

575	      net.slp.multicastMaximumWait

577	         A 32 bit integer giving the maximum amount of time to perform
578	         multicast, in milliseconds.  Default is 15000 ms (15 sec.).
579	         This property corresponds to the CONFIG_MC_MAX parameter in the
580	         protocol specification [7].

582	      net.slp.multicastTimeouts

584	         A value-list of 32 bit integers used as timeouts, in
585	         milliseconds, to implement the multicast convergence
586	         algorithm.  Each value specifies the time to wait before
587	         sending the next request, or until nothing new has
588	         been learned from two successive requests.  Default
589	         is:  3000,3000,3000,3000,3000.  In a fast network the
590	         aggressive values of 1000,1250,1500,2000,4000 allow better
591	         performance.  This property corresponds to the CONFIG_MC_RETRY
592	         parameter in the protocol specification [7].  Note that the
593	         net.slp.DADiscoveryTimeouts property must be used for active DA
594	         discovery.

596	      net.slp.DADiscoveryTimeouts

598	         A value-list of 32 bit integers used as timeouts, in
599	         milliseconds, to implement the multicast convergence algorithm
600	         during active DA discovery.  Each value specifies the time
601	         to wait before sending the next request, or until nothing
602	         new has been learned from two successive requests.  This
603	         property corresponds to the protocol specification parameter
604	         CONFIG_RETRY [7].  Default is:  2000,2000,2000,2000,3000,4000.

606	      net.slp.datagramTimeouts

608	         A value-list of 32 bit integers used as timeouts, in
609	         milliseconds, to implement unicast datagram transmission to
610	         DAs.  The nth value gives the time to block waiting for a reply
611	         on the nth try to contact the DA. The sum of these values is
612	         the protocol specification property CONFIG_RETRY_MAX [7].

614	      net.slp.randomWaitBound

616	         A 32 bit integer giving the maximum value for all random
617	         wait parameters, in milliseconds.  Default is 1000 (1
618	         sec.).  This value corresponds to the protocol specification
619	         parameters CONFIG_START_WAIT, CONFIG_REG_PASSIVE, and
620	         CONFIG_REG_ACTIVE [7].

622	      net.slp.MTU

624	         A 16 bit integer giving the network packet MTU, in bytes.
625	         This is the maximum size of any datagram to send, but the
626	         implementation might receive a larger datagram.  The maximum
627	         size includes IP, and UDP or TCP headers.  Default is 1400.

629	      net.slp.interfaces

631	         Value-list of strings giving the IP addresses of network
632	         interfaces on which the DA or SA should listen on port 427 for
633	         multicast, unicast UDP, and TCP messages.  Default is empty,
634	         i.e.  use the default network interface.  The grammar for this
635	         property is:

637	               addr-list     =  hostnumber / hostnumber "," addr-list
638	               hostnumber    =  1*3DIGIT 3("." 1*3DIGIT)

640	         An example is:

642	                  195.42.42.42,195.42.142.1,195.42.120.1

644	         The example machine has three interfaces on which the DA should
645	         listen.

647	         Note that since this property only takes IP addresses, it will
648	         need to be changed if the network is renumbered.

650	2.1.6. SA Configuration

652	   This section contains configuration properties for the SA. These
653	   properties are typically set programmatically by the SA, since they
654	   are specific to each SA.

656	      net.slp.SAAttributes

658	         A comma-separated list of parenthesized attribute/value list
659	         pairs that the SA must advertise in SAAdverts.  The property
660	         must be in the SLP attribute list wire format, including
661	         escapes for reserved characters. [7]

663	2.1.7. UA Configuration

665	   This section contains configuration properties for the UA. These
666	   properties can be set either programmatically by the UA or in the
667	   configuration file.

669	      net.slp.locale

671	         A RFC 1766 Language Tag [6] for the language locale.  Setting
672	         this property causes the property value to become the default
673	         locale for SLP messages.  Default is "en".  This property is
674	         also used for SA and DA configuration.

676	      net.slp.maxResults

678	         A 32 bit integer giving the maximum number of results to
679	         accumulate and return for a synchronous request before the
680	         timeout, or the maximum number of results to return through a
681	         callback if the request results are reported asynchronously.
682	         Positive integers and -1 are legal values.  If -1, indicates
683	         that all results should be returned.  Default value is -1.

685	         DAs and SAs always return all results that match the
686	         request.  This configuration value applies only to UAs, that
687	         filter incoming results and only return as many values as
688	         net.slp.maxResults indicates.

690	      net.slp.typeHint

692	         A value-list of service type names.  In the absence of any
693	         DAs, UAs perform SA discovery for finding scopes.  These SA
694	         discovery requests may contain a request for service types as
695	         an attribute.

697	         The API implementation will use the service type names supplied
698	         by this property to discover only those SAs (and their scopes)
699	         which support the desired service type or types.  For example,
700	         if net.slp.typeHint is set to "service:imap,service:pop3" then
701	         SA discovery requests will include the search filter:

703	                (|(service-type=service:imap)(service-type=service:pop3))

705	         The API library can also use unicast to contact the discovered
706	         SAs for subsequent requests for these service types, to
707	         optimize network access.

709	2.1.8. Security

711	   The property in this section allows security for all agents to be set
712	   on or off.  When the property is true, then the agent must include
713	   security information on all SLP messages transacted by that agent.
714	   Since security policy must be set network wide to be effective, a
715	   single property controls security for all agents.  Key management
716	   and management of SLP SPI strings [7] are implementation and policy
717	   dependent.

719	      net.slp.securityEnabled

721	         A boolean indicating whether the agent should enable
722	         security for URLs, attribute lists, DAAdverts, and SAAdverts.
723	         Each agent is responsible for interpreting the property
724	         appropriately.  Default is false.

726	2.2. Multihomed Machines

728	   On multihomed machines, the bandwidth and latency characteristics on
729	   different network interfaces may differ considerably, to the point
730	   where different configuration properties are necessary to achieve
731	   optimal performance.  The net.slp.interfaces property indicates which
732	   network interfaces are SLP enabled.  An API library implementation
733	   may support configuration customization on a per network interface
734	   basis by allowing the interface IP address to be appended to the
735	   property name.  In that case, the values of the property are only
736	   used for that particular interface, the generic property (or defaults
737	   if no generic property is set) applies to all others.

739	   For example, if a configuration has the following properties:

741	      net.slp.interfaces=125.196.42.41,125.196.42.42,125.196.42.43
742	      net.slp.multicastTTL.125.196.42.42=1

744	   then the network interface on subnet 42 is restricted to a TTL of 1,
745	   while the interfaces on the other subnets have the default multicast
746	   radius, 255.

748	   The net.slp.interfaces property must only be set if there is no
749	   routing between the interfaces.  If the property is set, the DA
750	   (if any) and SAs should advertise with the IP address or host name
751	   appropriate to the interface on the interfaces in the list.  If
752	   packets are routed between the interfaces, then the DA and SAs should
753	   only advertise on the default interface.  The property should also
754	   be set if broadcast is used rather than multicast on the subnets
755	   connected to the interfaces.  Note that even if unicast packets are
756	   not routed between the interfaces, multicast may be routed through
757	   another router.  The danger in listening for multicast on multiple
758	   interfaces when multicast packets are routed is that the DA or SA
759	   may receive the same multicast request via more than one interface.
760	   Since the IP address is different on each interface, the DA or SA
761	   cannot identify the request as having already being answered via
762	   the previous responder's list.  The requesting agent will end up
763	   getting URLs that refer to the same DA or service but have different
764	   addresses or host names.

766	2.3. Serialized Registration File

768	   The serialized registration file contains a group of registrations
769	   that a DA or SA server (if one exists) registers when it starts up.
770	   These registrations are primarily for older service programs that do
771	   not internally support SLP and cannot be converted, and for portably
772	   exchanging registrations between SLP implementations.  The character
773	   encoding of the registrations is required to be UTF-8.

775	   The syntax of the serialized registration file, in ABNF format [5],
776	   is as follows:

778	      ser-file      =  reg-list
779	      reg-list      =  reg / reg reg-list
780	      reg           =  creg / ser-reg
781	      creg          =  comment-line ser-reg
782	      comment-line  =  ( "#" / ";" ) 1*allchar newline
783	      ser-reg       =  url-props [slist] [attr-list] newline
784	      url-props     =  surl "," lang "," ltime [ "," type ] newline
785	      surl          =  ;The registration's URL. See
786	                       ; [8] for syntax.
787	      lang          =  1*8ALPHA [ "-" 1*8ALPHA ]
788	                       ;RFC 1766 Language Tag see [6].
789	      ltime         =  1*5DIGIT
790	                       ; A positive 16-bit integer
791	                       ; giving the lifetime
792	                       ; of the registration.
793	      type          =  ; The service type name, see [7]
794	                       ; and [8] for syntax.

796	      slist         =  "scopes" "=" scope-list newline
797	      scope-list    =  scope-name / scope-name "," scope-list
798	      scope         =  ; See grammar of [7] for
799	                       ; scope-name syntax.
800	      attr-list     =  attr-def / attr-def attr-list
801	      attr-def      =  ( attr / keyword ) newline
802	      keyword       =  attr-id
803	      attr          =  attr-id "=" attr-val-list
804	      attr-id       =  ;Attribute id, see [7] for syntax.
805	      attr-val-list =  attr-val / attr-val "," attr-val-list
806	      attr-val      =  ;Attribute value, see [7] for syntax.
807	      allchar       =  char / WSP
808	      char          =  DIGIT / ALPHA / other
809	      other         =  %x21-%x2f / %x3a-%x40 /
810	                       %x5b-%x60 / %7b-%7e
811	                       ; All printable, nonwhitespace US-ASCII
812	                       ; characters.
813	      newline       =  CR / ( CRLF )

815	   The syntax for scope names, attribute tags, and attribute values
816	   requires escapes for special characters as specified in [7].  DAs
817	   and SA servers that process serialized registrations must handle
818	   them exactly as if they were registered by an SA. In the url-props
819	   production, the type token is optional.  If the type token is present
820	   for a service:  URL, a warning is signaled and the type name is
821	   ignored.  If the maximum lifetime is specified (65535 sec.), the
822	   registration is taken to be permanent, and is continually refreshed
823	   by the DA or SA server until it exits.  Scopes can be included in a
824	   registration by including an attribute definition with tag "scopes"
825	   followed by a comma separated list of scope names immediately after
826	   the url-props production.  If the optional scope list is present,
827	   the registrations are made in the indicated scopes; otherwise, they
828	   are registered in the scopes with which the DA or SA server was
829	   configured through the net.slp.useScopes property.

831	   If the scope list contains scopes that are not in the
832	   net.slp.useScopes property (provided that property is set) or
833	   are not specified by DHCP, the API library should reject the
834	   registration and issue a warning message.

836	2.4. Processing Serialized Registration and Configuration Files

838	   Implementations are encouraged to make processing of configuration
839	   and serialized files as transparent as possible to clients of
840	   the API. At the latest, errors must be caught when the relevant
841	   configuration item is used.  At the earliest, errors may be caught
842	   when the relevant file is loaded into the executing agent.  Errors
843	   should be reported by logging to the appropriate platform logging
844	   file, error output, or log device, and the default value substituted.
845	   Serialized registration file entries should be caught and reported
846	   when the file is loaded.

848	   Configuration file loading must be complete prior to the initiation
849	   of the first networking connection.  Serialized registration must be
850	   complete before the DA accepts the first network request.

852	3. Binding Independent Implementation Considerations

854	   This section discusses a number of implementation considerations
855	   independent of language binding, with language specific notes where
856	   applicable.

858	3.1. Multithreading

860	   Implementations of both the C and Java APIs are required to make API
861	   calls thread-safe.  Access to data structures shared between threads
862	   must be co-ordinated to avoid corruption or invalid access.  One way
863	   to achieve this goal is to allow only one thread at a time in the
864	   implementing library.  Performance in such an implementation suffers,
865	   however.  Therefore, where possible, implementations are encouraged
866	   to allow multiple threads within the SLP API library.

868	3.2. Asynchronous and Incremental

870	   The APIs are designed to encourage implementations supporting
871	   asynchronous and incremental client interaction.  The goal is to
872	   allow large numbers of returned service URLs, service types, and
873	   attributes without requiring the allocation of huge chunks of memory.
874	   The particular design features to support this goal differ in the two
875	   language bindings.

877	3.3. Type Checking for Service Types

879	   Service templates [8] allow SLP registrations to be type checked for
880	   correctness.  Implementations of the API are free to make use of
881	   service type information for type checking, but are not required to
882	   do so.  If a type error occurs, the registration should terminate
883	   with TYPE_ERROR.

885	3.4. Refreshing Registrations

887	   SLP advertisements carry an explicit lifetime with them.  After
888	   the lifetime expires, the DA flushes the registration from its
889	   cache.  In some cases, an application may want to have the URL
890	   continue being registered for the entire time during which the
891	   application is executing.  The API includes provision for clients
892	   to indicate whether they want URLs to be automatically refreshed.
893	   Implementations of the SA API must provide this automatic refreshing
894	   capability.  Note that a client which uses this facility should
895	   explicitly deregister the service URL before exiting, since the API
896	   implementation may not be able to assure that the URL is deregistered
897	   when the application exits, although it will time out in the DA
898	   eventually.

900	3.5. Configuration File Processing

902	   DAs, SAs and UAs processing the configuration file, and DAs and SA
903	   servers processing the serialized registration file are required
904	   to log any errors using whatever underlying error mechanism is
905	   appropriate for the platform.  Examples include writing error
906	   messages to the standard output, writing to a system logging device,
907	   or displaying the errors to a logging window.  After the error is
908	   reported, the offending property must be set to the default and
909	   program execution continued.  An agent MUST NOT fail if a file format
910	   error occurs.

912	3.6. Attribute Types

914	   String encoded attribute values do not include explicit type
915	   information.  All UA implementations and those SA and DA
916	   implementations that choose to support type checking should use the
917	   type rules described in [8] in order to convert from the string
918	   representation on the wire to an object typed appropriately.

920	3.7. Removal of Duplicates

922	   The UA implementation SHOULD always collate results to remove
923	   duplicates during synchronous operations and for the Java API. During
924	   asynchronous operation in C, the UA implementation SHOULD forgo
925	   duplicate elimination to reduce memory requirements in the library.
926	   This allows the API library to simply take the returned attribute
927	   value list strings, URL strings, or service type list strings
928	   and call the callback function with it, without any additional
929	   processing.  Naturally, the burden of duplicate elimination is thrown
930	   onto the client in this case.

932	3.8. Character Set Encoding

934	   Character string parameters in the Java API are all represented in
935	   Unicode internally because that is the Java-supported character
936	   set.  Characters buffer parameters in the C API are represented
937	   in UTF-8 to maintain maximum compatibility on platforms that only
938	   support US-ASCII and not UTF-8.  API functions are still required to
939	   handle the full range of UTF-8 characters because the SLP protocol
940	   requires it, but the API implementation can represent the characters
941	   internally in any convenient way.  On the wire, all characters are
942	   converted to UTF-8.  Inside URLs, characters that are not allowed by
943	   URL syntax [2] must be escaped according to the URL escape character
944	   convention.  Strings that are included in SLP messages may include
945	   SLP reserved characters and can be escaped by clients through
946	   convenience functions provided by the API. The character encoding
947	   used in escapes is UTF-8.

949	   Due to constraints in SLP, no string parameter passed to the C or
950	   Java API may exceed 64K bytes in length.

952	3.9. Error Semantics

954	   All errors encountered processing SLP messages should be logged.
955	   For synchronous calls, an error is only reported on a call if no
956	   successful replies were received from any SLP framework entity.  If
957	   an error occurred among one of several successful replies, then the
958	   error should be logged and the successful replies returned.  For
959	   asynchronous calls, an error occurring during correspondence with a
960	   particular remote SLP agent is reported through the first callback
961	   (in the C API) or enumeration method invocation (in the Java API)
962	   after the error occurs, which would normally report the results of
963	   the correspondence.  This allows the callback or client code to
964	   determine whether the operation should be terminated or continue.  In
965	   some cases, the error returned from the SLP framework may be fatal
966	   (SLP_PARSE_ERROR, etc.).  In these cases, the API library terminates
967	   the operation.

969	   Both the Java and C APIs contain language specific error code
970	   mechanisms for returning error information.  The names of the error
971	   codes are consistent between the two implementations, however.

973	   The following error codes are returned from a remote agent (DA or SA
974	   server):

976	      LANGUAGE_NOT_SUPPORTED

978	         No DA or SA has service advertisement or attribute information
979	         in the language requested, but at least one DA or SA indicated,
980	         via the LANGUAGE_NOT_SUPPORTED error code, that it might have
981	         information for that service in another language.

983	      PARSE_ERROR

985	         The SLP message was rejected by a remote SLP agent.  The API
986	         returns this error only when no information was retrieved, and
987	         at least one SA or DA indicated a protocol error.  The data
988	         supplied through the API may be malformed or a may have been
989	         damaged in transit.

991	      INVALID_REGISTRATION

993	         The API may return this error if an attempt to register a
994	         service was rejected by all DAs because of a malformed URL or
995	         attributes.  SLP does not return the error if at least one DA
996	         accepted the registration.

998	      AUTHENTICATION_ABSENT

1000	         If the SLP framework supports authentication, this error arises
1001	         when the UA or SA failed to send an authenticator for requests
1002	         or registrations in a protected scope.

1004	      INVALID_UPDATE

1006	         An update for a non-existing registration was issued, or the
1007	         update includes a service type or scope different than that in
1008	         the initial registration, etc.

1010	   The following errors result from interactions with remote agents or
1011	   can occur locally:

1013	      AUTHENTICATION_FAILED

1015	         If the SLP framework supports authentication, this error arises
1016	         when a authentication on an SLP message failed.

1018	      SCOPE_NOT_SUPPORTED

1020	         The API returns this error if the SA has been configured with
1021	         net.slp.useScopes value-list of scopes and the SA request did
1022	         not specify one or more of these allowable scopes, and no
1023	         others.  It may be returned by a DA or SA if the scope included
1024	         in a request is not supported by the DA or SA.

1026	      REFRESH_REJECTED

1028	         The SA attempted to refresh a registration more frequently
1029	         than the minimum refresh interval.  The SA should call the
1030	         appropriate API function to obtain the minimum refresh interval
1031	         to use.

1033	   The following errors are generated through a program interacting with
1034	   the API implementation.  They do not involve a remote SLP agent.

1036	      NOT_IMPLEMENTED

1038	         If an unimplemented feature is used, this error is returned.

1040	      NETWORK_INIT_FAILED

1042	         If the network cannot initialize properly, this error is
1043	         returned.

1045	      NETWORK_TIMED_OUT

1047	         When no reply can be obtained in the time specified by the
1048	         configured timeout interval for a unicast request, this error
1049	         is returned.

1051	      NETWORK_ERROR

1053	         The failure of networking during normal operations causes this
1054	         error to be returned.

1056	      BUFFER_OVERFLOW

1058	         An outgoing request overflowed the maximum network MTU size.
1059	         The request should be reduced in size or broken into pieces and
1060	         tried again.

1062	      MEMORY_ALLOC_FAILED

1064	         If the API fails to allocate memory, the operation is aborted
1065	         and returns this.

1067	      PARAMETER_BAD

1069	         If a parameter passed into an interface is bad, this error is
1070	         returned.

1072	      INTERNAL_SYSTEM_ERROR

1074	         A basic failure of the API causes this error to be returned.
1075	         This occurs when a system call or library fails.  The operation
1076	         could not recover.

1078	      HANDLE_IN_USE

1080	         In the C API, callback functions are not permitted to
1081	         recursively call into the API on the same SLPHandle, either
1082	         directly or indirectly.  If an attempt is made to do so, this
1083	         error is returned from the called API function.

1085	      TYPE_ERROR

1087	         If the API supports type checking of registrations against
1088	         service type templates, this error can arise if the attributes
1089	         in a registration do not match the service type template for
1090	         the service.

1092	   Some error codes are handled differently in the Java API. These
1093	   differences are discussed in Section 5.

1095	   The SLP protocol errors OPTION_NOT_UNDERSTOOD, VERSION_NOT_SUPPORTED,
1096	   INTERNAL_ERROR, MSG_NOT_SUPPORTED, AUTHENTICATON_UNKNOWN, and
1097	   DA_BUSY_NOW should be handled internally and not surfaced to clients
1098	   through the API.

1100	3.10. Modular Implementations

1102	   Subset implementations that do not support the full range of
1103	   functionality are required to nevertheless support every interface
1104	   in order to maintain link compatibility between compliant API
1105	   implementations and applications.  If a particular operation is not
1106	   supported, a NOT_IMPLEMENTED error should be returned.  The Java API
1107	   has some additional conventions for handling subsets.  Applications
1108	   that are expected to run on a wide variety of platforms should be
1109	   prepared for subset API implementations by checking returned error
1110	   codes.

1112	3.11. Handling Special Service Types

1114	   The service types service:directory-agent and service:service-agent
1115	   are used internally in the SLP framework to discover DAs and SAs.
1116	   The mechanism of DA and SA discovery is not normally exposed to the
1117	   API client; however, the client may have interest in discovering
1118	   DAs and SAs independently of their role in discovering other
1119	   services.  For example, a network management application may want
1120	   to determine which machines are running SLP DAs.  To facilitate
1121	   that, API implementations must handle requests to find services and
1122	   attributes for these two service types so that API clients obtain the
1123	   information they expect.

1125	   In particular, if the UA is using a DA, SrvRqst and AttrRqst for
1126	   these service types must be multicast and not unicast to the DA,
1127	   as is the case for other service types.  If the requests are not
1128	   multicast, the DA will respond with an empty reply to a request for
1129	   services of type service:service-agent and with its URL only to a
1130	   request for services of type service:directory-agent.  The UA would
1131	   therefore not obtain a complete picture of the available DAs and SAs.

1133	3.12. Scope Discovery and Handling

1135	   Both APIs contain an operation to obtain a list of currently known
1136	   scope names.  This scope information comes from a variety of places:
1137	   DHCP, the net.slp.useScopes property, unicast to DAs configured via
1138	   DHCP or the net.slp.DAAddresses property, and active and passive
1139	   discovery.

1141	   The API is required to be implemented in a way that re-enforces the
1142	   administrative and user scoping models described in [7].  SA clients
1143	   only support the administrative scoping model.  SAs must know a
1144	   priori what DAs they need to register with since there is typically
1145	   no human intervention in scope selection for SAs.  UAs must support
1146	   both administrative and user scoping because an application may
1147	   require human intervention in scope selection.

1149	   API implementations are required to support administrative scoping
1150	   in the following way.  Scopes configured by DHCP and scopes of DAs
1151	   configured by DHCP have first priority (in that order) and must be
1152	   returned if they are available.  The net.slp.useScopes property has
1153	   second priority, and scopes discovered through the net.slp.useScopes
1154	   property must be returned if this property is set and there are
1155	   no scopes available from DHCP. If scopes are not available from
1156	   either of these sources and the net.slp.DAAddresses property is set,
1157	   then the scopes available from the configured DAs must be returned.
1158	   Note that if both DAs and scopes are configured, the scopes of the
1159	   configured DAs must match the configured scope list; otherwise
1160	   and error is signaled and agent execution is terminated.  If no
1161	   configured scope information is available, then an SA client has
1162	   default scope, "DEFAULT", and a UA client employs user scoping.

1164	   User scoping is supported in the following way.  Scopes discovered
1165	   from active DA discovery, and from passive DA discovery all must be
1166	   returned.  If no information is available from active and passive DA
1167	   discovery, then the API library may perform SA discovery, using the
1168	   service types in the net.slp.typeHint property to limit the search
1169	   to SAs supporting particular service types.  If no net.slp.typeHint
1170	   property is set, the UA may perform SA discovery without any
1171	   service type query.  In the absence of any of the above sources of
1172	   information, the API must return the default scope, "DEFAULT".  Note
1173	   that the API must always return some scope information.

1175	   SLP requires that SAs must perform their operations in all scopes
1176	   currently known to them. [7].  The API enforces this constraint by
1177	   not requiring the API client to supply any scopes as parameters to
1178	   API operations.  The API library must obtain all currently known
1179	   scopes and use them in SA operations.  UA API clients should use a
1180	   scope obtained through one of the API operations for finding scopes.
1181	   Any other scope name may result in a SCOPE_NOT_SUPPORTED error from a
1182	   remote agent.  The UA API library can optionally check the scope and
1183	   return the error without contacting a remote agent.

1185	4. C Language Binding

1187	   The C language binding presents a minimal overhead implementation
1188	   that maps directly into the protocol.  There is one C language
1189	   function per protocol request, with the exception of the SLPDereg()
1190	   and SLPDelAttrs() functions, which map into different uses of the
1191	   SLP deregister request.  Parameters are for the most part character
1192	   buffers.  Memory management is kept simple by having the client
1193	   allocate most memory and requiring that client callback functions
1194	   copy incoming parameters into memory allocated by the client code.
1195	   Any memory returned directly from the API functions is deallocated
1196	   using the SLPFree() function.

1198	   To conform with standard C practice, all character strings passed to
1199	   and returned through the API are null terminated, even though the
1200	   SLP protocol does not use null terminated strings.  Strings passed
1201	   as parameters are UTF-8 but they may still be passed as a C string
1202	   (a null terminated sequence of bytes.)  Escaped characters must be
1203	   encoded by the API client as UTF-8.  In the common case of US-ASCII,
1204	   the usual one byte per character C strings work.  API functions
1205	   assist in escaping and unescaping strings.

1207	   Unless otherwise noted, parameters to API functions and callbacks
1208	   are non-NULL. Some parameters may have other restrictions.  If
1209	   any parameter fails to satisfy the restrictions on its value, the
1210	   operation returns a PARAMETER_BAD error.

1212	4.1. Constant Types

1214	4.1.1. URL Lifetimes

1216	4.1.1.1. Synopsis

1218	   typedef enum {
1219	     SLP_LIFETIME_DEFAULT = 10800,
1220	     SLP_LIFETIME_MAXIMUM = 65535
1221	   } SLPURLLifetime;

1223	4.1.1.2. Description

1225	   The SLPURLLifetime enum type contains URL lifetime values, in
1226	   seconds, that are frequently used.  SLP_LIFETIME_DEFAULT is 3 hours,
1227	   while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the
1228	   maximum size of the lifetime field in SLP messages.

1230	4.1.2. Error Codes

1232	4.1.2.1. Synopsis

1234	   typedef enum {
1235	     SLP_LAST_CALL                    = 1,
1236	     SLP_OK                           = 0,
1237	     SLP_LANGUAGE_NOT_SUPPORTED       = -1,
1238	     SLP_PARSE_ERROR                  = -2,
1239	     SLP_INVALID_REGISTRATION         = -3,
1240	     SLP_SCOPE_NOT_SUPPORTED          = -4,
1241	     SLP_AUTHENTICATION_ABSENT        = -6,
1242	     SLP_AUTHENTICATION_FAILED        = -7,
1243	     SLP_INVALID_UPDATE               = -13,
1244	     SLP_REFRESH_REJECTED             = -15,
1245	     SLP_NOT_IMPLEMENTED              = -17,
1246	     SLP_BUFFER_OVERFLOW              = -18,
1247	     SLP_NETWORK_TIMED_OUT            = -19,
1248	     SLP_NETWORK_INIT_FAILED          = -20,
1249	     SLP_MEMORY_ALLOC_FAILED          = -21,
1250	     SLP_PARAMETER_BAD                = -22,
1251	     SLP_NETWORK_ERROR                = -23,
1252	     SLP_INTERNAL_SYSTEM_ERROR        = -24,
1253	     SLP_HANDLE_IN_USE                = -25,
1254	     SLP_TYPE_ERROR                   = -26

1256	   } SLPError ;

1258	4.1.2.2. Description

1260	   The SLPError enum contains error codes that are returned from API
1261	   functions.

1263	   The SLP_OK code indicates that the no error occurred during the
1264	   operation.

1266	   The SLP_LAST_CALL code is passed to callback functions when the API
1267	   library has no more data for them and therefore no further calls will
1268	   be made to the callback on the currently outstanding operation.  The
1269	   callback can use this to signal the main body of the client code
1270	   that no more data will be forthcoming on the operation, so that
1271	   the main body of the client code can break out of data collection
1272	   loops.  On the last call of a callback during both a synchronous and
1273	   asynchronous call, the error code parameter has value SLP_LAST_CALL,
1274	   and the other parameters are all NULL. If no results are returned
1275	   by an API operation, then only one call is made, with the error
1276	   parameter set to SLP_LAST_CALL.

1278	4.1.3. SLPBoolean

1280	4.1.3.1. Synopsis

1282	   typedef enum {
1283	      SLP_FALSE = 0,
1284	      SLP_TRUE = 1

1286	   } SLPBoolean;

1288	4.1.3.2. Description

1290	   The SLPBoolean enum is used as a boolean flag.

1292	4.2. Struct Types

1294	4.2.1. SLPSrvURL

1296	4.2.1.1. Synopsis

1298	   typedef struct srvurl {
1299	     char *s_pcSrvType;
1300	     char *s_pcHost;
1301	     int   s_iPort;
1302	     char *s_pcNetFamily;
1303	     char *s_pcSrvPart;
1304	   } SLPSrvURL;

1306	4.2.1.2. Description

1308	   The SLPSrvURL structure is filled in by the SLPParseSrvURL() function
1309	   with information parsed from a character buffer containing a service
1310	   URL. The fields correspond to different parts of the URL. Note that
1311	   the structure is conformant with the standard Berkeley sockets
1312	   struct servent, with the exception that the pointer to an array of
1313	   characters for aliases (s_aliases field) is replaced by the pointer
1314	   to host name (s_pcHost field).

1316	      s_pcSrvType

1318	         A pointer to a character string containing the service
1319	         type name, including naming authority.  The service type
1320	         name includes the "service:" if the URL is of the service:
1321	         scheme. [7]

1323	      s_pcHost

1325	         A pointer to a character string containing the host
1326	         identification information.

1328	      s_iPort

1330	         The port number, or zero if none.  The port is only available
1331	         if the transport is IP.

1333	      s_pcNetFamily

1335	         A pointer to a character string containing the network address
1336	         family identifier.  Possible values are "ipx" for the IPX
1337	         family, "at" for the Appletalk family, and "" (i.e.  the empty
1338	         string) for the IP address family.

1340	      s_pcSrvPart

1342	         The remainder of the URL, after the host identification.

1344	   The host and port should be sufficient to open a socket to the
1345	   machine hosting the service, and the remainder of the URL should
1346	   allow further differentiation of the service.

1348	4.2.2. SLPHandle

1350	4.2.2.1. Synopsis

1352	   typedef void* SLPHandle;

1354	   The SLPHandle type is returned by SLPOpen() and is a parameter to all
1355	   SLP functions.  It serves as a handle for all resources allocated on
1356	   behalf of the process by the SLP library.  The type is opaque, since
1357	   the exact nature differs depending on the implementation.

1359	4.3. Callbacks

1361	   A function pointer to a callback function specific to a particular
1362	   API operation is included in the parameter list when the API function
1363	   is invoked.  The callback function is called with the results of the
1364	   operation in both the synchronous and asynchronous cases.  The memory
1365	   included in the callback parameters is owned by the API library, and
1366	   the client code in the callback must copy out the contents if it
1367	   wants to maintain the information longer than the duration of the
1368	   current callback call.

1370	   In addition to parameters for reporting the results of the operation,
1371	   each callback parameter list contains an error code parameter and a
1372	   cookie parameter.  The error code parameter reports the error status
1373	   of the ongoing (for asynchronous) or completed (for synchronous)
1374	   operation.  The cookie parameter allows the client code that starts
1375	   the operation by invoking the API function to pass information
1376	   down to the callback without using global variables.  The callback
1377	   returns an SLPBoolean to indicate whether the API library should
1378	   continue processing the operation.  If the value returned from
1379	   the callback is SLP_TRUE, asynchronous operations are terminated,
1380	   synchronous operations ignore the return (since the operation is
1381	   already complete).

1383	4.3.1. SLPRegReport

1385	4.3.1.1. Synopsis

1387	   typedef void SLPRegReport(SLPHandle hSLP,
1388	                             SLPError errCode,
1389	                             void *pvCookie);

1391	4.3.1.2. Description

1393	   The SLPRegReport callback type is the type of the callback function
1394	   to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions.

1396	4.3.1.3. Parameters

1398	      hSLP

1400	         The SLPHandle used to initiate the operation.

1402	      errCode

1404	         An error code indicating if an error occurred during the
1405	         operation.

1407	      pvCookie

1409	         Memory passed down from the client code that called the
1410	         original API function, starting the operation.  May be NULL.

1412	4.3.2. SLPSrvTypeCallback

1414	4.3.2.1. Synopsis

1416	   typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,
1417	                                         const char* pcSrvTypes,
1418	                                         SLPError errCode,
1419	                                         void *pvCookie);

1421	4.3.2.2. Description

1423	   The SLPSrvTypeCallback type is the type of the callback function
1424	   parameter to SLPFindSrvTypes() function.  If the hSLP handle
1425	   parameter was opened asynchronously, the results returned through
1426	   the callback MAY be uncollated.  If the hSLP handle parameter was
1427	   opened synchronously, then the returned results must be collated and
1428	   duplicates eliminated.

1430	4.3.2.3. Parameters

1432	      hSLP

1434	         The SLPHandle used to initiate the operation.

1436	      pcSrvTypes

1438	         A character buffer containing a comma separated, null
1439	         terminated list of service types.

1441	      errCode

1443	         An error code indicating if an error occurred during the
1444	         operation.  The callback should check this error code before
1445	         processing the parameters.  If the error code is other than
1446	         SLP_OK, then the API library may choose to terminate the
1447	         outstanding operation.

1449	      pvCookie

1451	         Memory passed down from the client code that called the
1452	         original API function, starting the operation.  May be NULL.

1454	4.3.2.4. Returns

1456	   The client code should return SLP_TRUE if more data is desired,
1457	   otherwise SLP_FALSE.

1459	4.3.3. SLPSrvURLCallback

1461	4.3.3.1. Synopsis

1463	   typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP,
1464	                                        const char* pcSrvURL,
1465	                                        unsigned short sLifetime,
1466	                                        SLPError errCode,
1467	                                        void *pvCookie);

1469	4.3.3.2. Description

1471	   The SLPSrvURLCallback type is the type of the callback function
1472	   parameter to SLPFindSrvs() function.  If the hSLP handle parameter
1473	   was opened asynchronously, the results returned through the
1474	   callback MAY be uncollated.  If the hSLP handle parameter was
1475	   opened synchronously, then the returned results must be collated and
1476	   duplicates eliminated.

1478	4.3.3.3. Parameters

1480	      hSLP

1482	         The SLPHandle used to initiate the operation.

1484	      pcSrvURL

1486	         A character buffer containing the returned service URL.

1488	      sLifetime

1490	         An unsigned short giving the life time of the service
1491	         advertisement, in seconds.  The value must be an unsigned
1492	         integer less than or equal to SLP_LIFETIME_MAXIMUM.

1494	      errCode

1496	         An error code indicating if an error occurred during the
1497	         operation.  The callback should check this error code before
1498	         processing the parameters.  If the error code is other than
1499	         SLP_OK, then the API library may choose to terminate the
1500	         outstanding operation.

1502	      pvCookie

1504	         Memory passed down from the client code that called the
1505	         original API function, starting the operation.  May be NULL.

1507	4.3.3.4. Returns

1509	   The client code should return SLP_TRUE if more data is desired,
1510	   otherwise SLP_FALSE.

1512	4.3.4. SLPAttrCallback

1514	4.3.4.1. Synopsis

1516	   typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP,
1517	                                      const char* pcAttrList,
1518	                                      SLPError errCode,
1519	                                      void *pvCookie);

1521	4.3.4.2. Description

1523	   The SLPAttrCallback type is the type of the callback function
1524	   parameter to SLPFindAttrs() function.

1526	   The behavior of the callback differs depending on whether
1527	   the attribute request was by URL or by service type.  If the
1528	   SLPFindAttrs() operation was originally called with a URL, the
1529	   callback is called once regardless of whether the handle was opened
1530	   asynchronously or synchronously.  The pcAttrList parameter contains
1531	   the requested attributes as a comma separated list (or is empty if no
1532	   attributes matched the original tag list).

1534	   If the SLPFindAttrs() operation was originally called with a service
1535	   type, the value of pcAttrList and calling behavior depend on whether
1536	   the handle was opened asynchronously or synchronously.  If the handle
1537	   was opened asynchronously, the callback is called every time the API
1538	   library has results from a remote agent.  The pcAttrList parameter
1539	   MAY be uncollated between calls.  It contains a comma separated list
1540	   with the results from the agent that immediately returned results.
1541	   If the handle was opened synchronously, the results must be collated
1542	   from all returning agents and the callback is called once, with the
1543	   pcAttrList parameter set to the collated result.

1545	4.3.4.3. Parameters

1547	      hSLP

1549	         The SLPHandle used to initiate the operation.

1551	      pcAttrList

1553	         A character buffer containing a comma separated, null
1554	         terminated list of attribute id/value assignments, in SLP wire
1555	         format; i.e.  "(attr-id=attr-value-list)" [7].

1557	      errCode

1559	         An error code indicating if an error occurred during the
1560	         operation.  The callback should check this error code before
1561	         processing the parameters.  If the error code is other than
1562	         SLP_OK, then the API library may choose to terminate the
1563	         outstanding operation.

1565	      pvCookie

1567	         Memory passed down from the client code that called the
1568	         original API function, starting the operation.  May be NULL.

1570	4.3.4.4. Returns

1572	   The client code should return SLP_TRUE if more data is desired,
1573	   otherwise SLP_FALSE.

1575	4.4. Opening and Closing an SLPHandle

1577	4.4.1. SLPOpen

1579	4.4.1.1. Synopsis

1581	   SLPError SLPOpen(const char *pcLang, SLPBoolean isAsync, SLPHandle *phSLP);

1583	4.4.1.2. Description

1585	   Returns a SLPHandle handle in the phSLP parameter for the language
1586	   locale passed in as the pcLang parameter.  The client indicates
1587	   if operations on the handle are to be synchronous or asynchronous
1588	   through the isAsync parameter.  The handle encapsulates the language
1589	   locale for SLP requests issued through the handle, and any other
1590	   resources required by the implementation.  However, SLP properties
1591	   are not encapsulated by the handle; they are global.  The return
1592	   value of the function is an SLPError code indicating the status of
1593	   the operation.  Upon failure, the phSLP parameter is NULL.

1595	   An SLPHandle can only be used for one SLP API operation at a time.
1596	   If the original operation was started asynchronously, any attempt
1597	   to start an additional operation on the handle while the original
1598	   operation is pending results in the return of an SLP_HANDLE_IN_USE
1599	   error from the API function.  The SLPClose() API function terminates
1600	   any outstanding calls on the handle.  If an implementation is
1601	   unable to support a asynchronous( resp.  synchronous) operation,
1602	   due to memory constraints or lack of threading support, the
1603	   SLP_NOT_IMPLEMENTED flag may be returned when the isAsync flag is
1604	   SLP_TRUE (resp.  SLP_FALSE).

1606	4.4.1.3. Parameters

1608	      pcLang

1610	         A pointer to an array of characters containing the RFC 1766
1611	         Language Tag [6] for the natural language locale of requests
1612	         and registrations issued on the handle.

1614	      isAsync

1616	         An SLPBoolean indicating whether the SLPHandle should be opened
1617	         for asynchronous operation or not.

1619	      phSLP

1621	         A pointer to an SLPHandle, in which the open SLPHandle is
1622	         returned.  If an error occurs, the value upon return is NULL.

1624	4.4.2. SLPClose

1626	4.4.2.1. Synopsis

1628	   void SLPClose(SLPHandle hSLP);

1630	4.4.2.2. Description

1632	   Frees all resources associated with the handle.  If the handle was
1633	   invalid, the function returns silently.  Any outstanding synchronous
1634	   or asynchronous operations are cancelled so their callback functions
1635	   will not be called any further.

1637	4.4.2.3. Parameters

1639	      SLPHandle

1641	         A SLPHandle handle returned from a call to SLPOpen().

1643	4.5. Protocol API

1645	4.5.1. SLPReg

1647	4.5.1.1. Synopsis

1649	   SLPError SLPReg(SLPHandle   hSLP,
1650	                   const char  *pcSrvURL,
1651	                   const unsigned short usLifetime,
1652	                   const char  *pcSrvType,
1653	                   const char  *pcAttrs
1654	                   SLPBoolean  fresh,
1655	                   SLPRegReport callback,
1656	                   void *pvCookie);

1658	4.5.1.2. Description

1660	   Registers the URL in pcSrvURL having the lifetime usLifetime with the
1661	   attribute list in pcAttrs.  The pcAttrs list is a comma separated
1662	   list of attribute assignments in the wire format (including escaping
1663	   of reserved characters).  The usLifetime parameter must be nonzero
1664	   and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is
1665	   SLP_TRUE, then the registration is new (the SLP protocol FRESH flag
1666	   is set) and the registration replaces any existing registrations.
1667	   The pcSrvType parameter is a service type name and can be included
1668	   for service URLs that are not in the service:  scheme.  If the URL is
1669	   in the service:  scheme, the pcSrvType parameter is ignored.  If the
1670	   fresh flag is SLP_FALSE, then an existing registration is updated.
1671	   Rules for new and updated registrations, and the format for pcAttrs
1672	   and pcScopeList can be found in [7].  Registrations and updates take
1673	   place in the language locale of the hSLP handle.

1675	   The API library is required to perform the operation in all scopes
1676	   obtained through configuration.

1678	4.5.1.3. Parameters

1680	      hSLP

1682	         The language specific SLPHandle on which to register the
1683	         advertisement.

1685	      pcSrvURL

1687	         The URL to register.  May not be the empty string.

1689	      usLifetime

1691	         An unsigned short giving the life time of the service
1692	         advertisement, in seconds.  The value must be an unsigned
1693	         integer less than or equal to SLP_LIFETIME_MAXIMUM and greater
1694	         than zero.

1696	      pcSrvType

1698	         The service type.  If pURL is a service:  URL, then this
1699	         parameter is ignored.

1701	      pcAttrs

1703	         A comma separated list of attribute assignment expressions for
1704	         the attributes of the advertisement.  Use empty string, "" for
1705	         no attributes.

1707	      fresh

1709	         An SLPBoolean that is SLP_TRUE if the registration is new or
1710	         SLP_FALSE if a reregistration.

1712	      callback

1714	         A callback to report the operation completion status.

1716	      pvCookie

1718	         Memory passed to the callback code from the client.  May be
1719	         NULL.

1721	4.5.1.4. Returns

1723	   If an error occurs in starting the operation, one of the SLPError
1724	   codes is returned.

1726	4.5.2. SLPDereg

1728	4.5.2.1. Synopsis

1730	   SLPError SLPDereg(SLPHandle  hSLP,
1731	                     const char *pcURL,
1732	                     SLPRegReport callback,
1733	                     void *pvCookie);

1735	4.5.2.2. Description

1737	   Deregisters the advertisement for URL pcURL in all scopes where the
1738	   service is registered and all language locales.  The deregistration
1739	   is not just confined to the locale of the SLPHandle, it is in all
1740	   locales.  The API library is required to perform the operation in all
1741	   scopes obtained through configuration.

1743	4.5.2.3. Parameters

1745	      hSLP

1747	         The language specific SLPHandle to use for deregistering.

1749	      pcURL

1751	         The URL to deregister.  May not be the empty string.

1753	      callback

1755	         A callback to report the operation completion status.

1757	      pvCookie

1759	         Memory passed to the callback code from the client.  May be
1760	         NULL.

1762	4.5.2.4. Returns

1764	   If an error occurs in starting the operation, one of the SLPError
1765	   codes is returned.

1767	4.5.3. SLPDelAttrs

1769	4.5.3.1. Synopsis

1771	   SLPError SLPDelAttrs(SLPHandle   hSLP,
1772	                        const char  *pcURL,
1773	                        const char  *pcAttrs,
1774	                        SLPRegReport callback,
1775	                        void *pvCookie);

1777	4.5.3.2. Description

1779	   Delete the selected attributes in the locale of the SLPHandle.  The
1780	   API library is required to perform the operation in all scopes
1781	   obtained through configuration.

1783	4.5.3.3. Parameters

1785	      hSLP

1787	         The language specific SLPHandle to use for deleting attributes.

1789	      pcURL

1791	         The URL of the advertisement from which the attributes should
1792	         be deleted.  May not be the empty string.

1794	      pcAttrs

1796	         A comma separated list of attribute ids for the attributes to
1797	         deregister.  See Section 9.8 in [7] for a description of the
1798	         list format.  May not be the empty string.

1800	      callback

1802	         A callback to report the operation completion status.

1804	      pvCookie

1806	         Memory passed to the callback code from the client.  May be
1807	         NULL.

1809	4.5.3.4. Returns

1811	   If an error occurs in starting the operation, one of the SLPError
1812	   codes is returned.

1814	4.5.4. SLPFindSrvTypes

1816	4.5.4.1. Synopsis

1818	   SLPError SLPFindSrvTypes(SLPHandle    hSLP,
1819	                            const char  *pcNamingAuthority,
1820	                            const char  *pcScopeList,
1821	                            SLPSrvTypeCallback callback,
1822	                            void *pvCookie);

1824	   The SLPFindSrvType() function issues an SLP service type request
1825	   for service types in the scopes indicated by the pcScopeList.  The
1826	   results are returned through the callback parameter.  The service
1827	   types are independent of language locale, but only for services
1828	   registered in one of scopes and for the indicated naming authority.

1830	   If the naming authority is "*", then results are returned for all
1831	   naming authorities.  If the naming authority is the empty string,
1832	   i.e.  "", then the default naming authority, "IANA", is used.  "IANA"
1833	   is not a valid naming authority name, and it is a PARAMETER_BAD error
1834	   to include it explicitly.

1836	   The service type names are returned with the naming authority intact.
1837	   If the naming authority is the default (i.e.  empty string) then
1838	   it is omitted, as is the separating ".".  Service type names from
1839	   URLs of the service:  scheme are returned with the "service:" prefix
1840	   intact. [7] See [8] for more information on the syntax of service
1841	   type names.

1843	4.5.4.2. Parameters

1845	      hSLP

1847	         The SLPHandle on which to search for types.

1849	      pcNamingAuthority

1851	         The naming authority to search.  Use "*" for all naming
1852	         authorities and the empty string, "", for the default naming
1853	         authority.

1855	      pcScopeList

1857	         A pointer to a char containing comma separated list of scope
1858	         names to search for service types.  May not be the empty
1859	         string, "".

1861	      callback

1863	         A callback function through which the results of the operation
1864	         are reported.

1866	      pvCookie

1868	         Memory passed to the callback code from the client.  May be
1869	         NULL.

1871	4.5.4.3. Returns

1873	   If an error occurs in starting the operation, one of the SLPError
1874	   codes is returned.

1876	4.5.5. SLPFindSrvs

1878	4.5.5.1. Synopsis

1880	   SLPError SLPFindSrvs(SLPHandle  hSLP,
1881	                        const char *pcServiceType,
1882	                        const char *pcScopeList,
1883	                        const char *pcSearchFilter,
1884	                        SLPSrvURLCallback callback,
1885	                        void *pvCookie);

1887	4.5.5.2. Description

1889	   Issue the query for services on the language specific SLPHandle and
1890	   return the results through the callback.  The parameters determine
1891	   the results

1893	4.5.5.3. Parameters

1895	      hSLP

1897	         The language specific SLPHandle on which to search for
1898	         services.

1900	      pcServiceType

1902	         The Service Type String, including authority string if any, for
1903	         the request, such as can be discovered using SLPSrvTypes().
1904	         This could be, for example "service:printer:lpr" or
1905	         "service:nfs".  May not be the empty string.

1907	      pcScopeList

1909	         A pointer to a char containing comma separated list of scope
1910	         names.  May not be the empty string, "".

1912	      pcSearchFilter

1914	         A query formulated of attribute pattern matching expressions in
1915	         the form of a LDAPv3 Search Filter, see [4].  If this filter
1916	         is empty, i.e.  "", all services of the requested type in the
1917	         specified scopes are returned.

1919	      callback

1921	         A callback function through which the results of the operation
1922	         are reported.

1924	      pvCookie

1926	         Memory passed to the callback code from the client.  May be
1927	         NULL.

1929	4.5.5.4. Returns

1931	   If an error occurs in starting the operation, one of the SLPError
1932	   codes is returned.

1934	4.5.6. SLPFindAttrs

1936	4.5.6.1. Synopsis

1938	   SLPError SLPFindAttrs(SLPHandle   hSLP,
1939	                         const char *pcURLOrServiceType,
1940	                         const char *pcScopeList,
1941	                         const char *pcAttrIds,
1942	                         SLPAttrCallback callback,
1943	                         void *pvCookie);

1945	4.5.6.2. Description

1947	   This function returns service attributes matching the attribute ids
1948	   for the indicated service URL or service type.  If pcURLOrServiceType
1949	   is a service URL, the attribute information returned is for that
1950	   particular advertisement in the language locale of the SLPHandle.

1952	   If pcURLOrServiceType is a service type name (including naming
1953	   authority if any), then the attributes for all advertisements of that
1954	   service type are returned regardless of the language of registration.
1955	   Results are returned through the callback.

1957	   The result is filtered with an SLP attribute request filter string
1958	   parameter, the syntax of which is described in [7].  If the filter
1959	   string is the empty string, i.e.  "", all attributes are returned.

1961	4.5.6.3. Parameters

1963	      hSLP

1965	         The language specific SLPHandle on which to search for
1966	         attributes.

1968	      pcURLOrServiceType

1970	         The service URL or service type.  See [7] for URL and service
1971	         type syntax.  May not be the empty string.

1973	      pcScopeList

1975	         A pointer to a char containing a comma separated list of scope
1976	         names.  May not be the empty string, "".

1978	      pcAttrIds

1980	         The filter string indicating which attribute values to return.
1981	         Use empty string, "", to indicate all values.  Wildcards
1982	         matching all attribute ids having a particular prefix or suffix
1983	         are also possible.  See [7] for the exact format of the filter
1984	         string.

1986	      callback

1988	         A callback function through which the results of the operation
1989	         are reported.

1991	      pvCookie

1993	         Memory passed to the callback code from the client.  May be
1994	         NULL.

1996	4.5.6.4. Returns

1998	   If an error occurs in starting the operation, one of the SLPError
1999	   codes is returned.

2001	4.6. Miscellaneous Functions

2003	4.6.1. SLPGetRefreshInterval

2005	4.6.1.1. Synopsis

2007	   unsigned short SLPGetRefreshInterval();

2009	4.6.1.2. Description

2011	   Returns the maximum across all DAs of the min-refresh-interval
2012	   attribute.  This value satisfies the advertised refresh interval
2013	   bounds for all DAs, and, if used by the SA, assures that no
2014	   refresh registration will be rejected.  If no DA advertises a
2015	   min-refresh-interval attribute, a value of 0 is returned.

2017	4.6.1.3. Returns

2019	   If no error, the maximum refresh interval value allowed by all DAs
2020	   (a positive integer).  If no DA advertises a min-refresh-interval
2021	   attribute, returns 0.  If an error occurs, returns an SLP error code.

2023	4.6.2. SLPFindScopes

2025	4.6.2.1. Synopsis

2027	   SLPError SLPFindScopes(SLPHandle hSLP,
2028	                          char** ppcScopeList);

2030	4.6.2.2. Description

2032	   Sets ppcScopeList parameter to a pointer to a comma separated list
2033	   including all available scope values.  The list of scopes comes from
2034	   a variety of sources:  the configuration file's net.slp.useScopes
2035	   property, unicast to DAs on the net.slp.DAAddresses property, DHCP,
2036	   or through the DA discovery process.  If there is any order to the
2037	   scopes, preferred scopes are listed before less desirable scopes.
2038	   There is always at least one name in the list, the default scope,
2039	   "DEFAULT".

2041	4.6.2.3. Parameters

2043	      hSLP

2045	         The SLPHandle on which to search for scopes.

2047	      ppcScopeList

2049	         A pointer to char pointer into which the buffer pointer is
2050	         placed upon return.  The buffer is null terminated.  The memory
2051	         should be freed by calling SLPFree().

2053	4.6.2.4. Returns

2055	   If no error occurs, returns SLP_OK, otherwise, the appropriate error
2056	   code.

2058	4.6.3. SLPParseSrvURL

2060	4.6.3.1. Synopsis

2062	   SLPError SLPParseSrvURL(char *pcSrvURL
2063	                           SLPSrvURL** ppSrvURL);

2065	4.6.3.2. Description

2067	   Parses the URL passed in as the argument into a service URL structure
2068	   and returns it in the ppSrvURL pointer.  If a parse error occurs,
2069	   returns SLP_PARSE_ERROR. The input buffer pcSrvURL is destructively
2070	   modified during the parse and used to fill in the fields of the
2071	   return structure.  The structure returned in ppSrvURL should be freed
2072	   with SLPFreeURL().  If the URL has no service part, the s_pcSrvPart
2073	   string is the empty string, "", i.e.  not NULL. If pcSrvURL is not
2074	   a service:  URL, then the s_pcSrvType field in the returned data
2075	   structure is the URL's scheme, which might not be the same as the
2076	   service type under which the URL was registered.  If the transport is
2077	   IP, the s_pcTransport field is the empty string.  If the transport is
2078	   not IP or there is no port number, the s_iPort field is zero.

2080	4.6.3.3. Parameters

2082	      pcSrvURL

2084	         A pointer to a character buffer containing the null terminated
2085	         URL string to parse.  It is destructively modified to produce
2086	         the output structure.

2088	      ppSrvURL

2090	         A pointer to a pointer for the SLPSrvURL structure to receive
2091	         the parsed URL. The memory should be freed by a call to
2092	         SLPFree() when no longer needed.

2094	4.6.3.4. Returns

2096	   If no error occurs, the return value is SLP_OK. Otherwise, the
2097	   appropriate error code is returned.

2099	4.6.4. SLPEscape

2101	4.6.4.1. Synopsis

2103	   SLPError SLPEscape(const char* pcInbuf,
2104	                      char** ppcOutBuf,
2105	                      SLPBoolean isTag);

2107	4.6.4.2. Description

2109	   Process the input string in pcInbuf and escape any SLP reserved
2110	   characters.  If the isTag parameter is SLPTrue, then look for bad
2111	   tag characters and signal an error if any are found by returning the
2112	   SLP_PARSE_ERROR code.  The results are put into a buffer allocated by
2113	   the API library and returned in the ppcOutBuf parameter.  This buffer
2114	   should be deallocated using SLPFree() when the memory is no longer
2115	   needed.

2117	4.6.4.3. Parameters

2119	      pcInbuf

2121	         Pointer to he input buffer to process for escape characters.

2123	      ppcOutBuf

2125	         Pointer to a pointer for the output buffer with the SLP
2126	         reserved characters escaped.  Must be freed using SLPFree()
2127	         when the memory is no longer needed.

2129	      isTag

2131	         When true, the input buffer is checked for bad tag characters.

2133	4.6.4.4. Returns

2135	   Return SLP_PARSE_ERROR if any characters are bad tag characters and
2136	   the isTag flag is true, otherwise SLP_OK, or the appropriate error
2137	   code if another error occurs.

2139	4.6.5. SLPUnescape

2141	4.6.5.1. Synopsis

2143	   SLPError SLPUnescape(const char* pcInbuf,
2144	                        char** ppcOutBuf,
2145	                        SLPBoolean isTag);

2147	4.6.5.2. Description

2149	   Process the input string in pcInbuf and unescape any SLP reserved
2150	   characters.  If the isTag parameter is SLPTrue, then look for
2151	   bad tag characters and signal an error if any are found with the
2152	   SLP_PARSE_ERROR code.  No transformation is performed if the input
2153	   string is an opaque.  The results are put into a buffer allocated by
2154	   the API library and returned in the ppcOutBuf parameter.  This buffer
2155	   should be deallocated using SLPFree() when the memory is no longer
2156	   needed.

2158	4.6.5.3. Parameters

2160	      pcInbuf

2162	         Pointer to he input buffer to process for escape characters.

2164	      ppcOutBuf

2166	         Pointer to a pointer for the output buffer with the SLP
2167	         reserved characters escaped.  Must be freed using SLPFree()
2168	         when the memory is no longer needed.

2170	      isTag

2172	         When true, the input buffer is checked for bad tag characters.

2174	4.6.5.4. Returns

2176	   Return SLP_PARSE_ERROR if any characters are bad tag characters and
2177	   the isTag flag is true, otherwise SLP_OK, or the appropriate error
2178	   code if another error occurs.

2180	4.6.6. SLPFree

2182	4.6.6.1. Synopsis

2184	   void SLPFree(void* pvMem);

2186	4.6.6.2. Description

2188	   Frees memory returned from SLPParseSrvURL(), SLPFindScopes(),
2189	   SLPEscape(), and SLPUnescape().

2191	4.6.6.3. Parameters

2193	      pvMem

2195	         A pointer to the storage allocated by the SLPParseSrvURL(),
2196	         SLPEscape(), SLPUnescape(), or SLPFindScopes() function.
2197	         Ignored if NULL.

2199	4.6.7. SLPGetProperty

2201	4.6.7.1. Synopsis

2203	   const char* SLPGetProperty(const char* pcName);

2205	4.6.7.2. Description

2207	   Returns the value of the corresponding SLP property name.  The
2208	   returned string is owned by the library and MUST NOT be freed.

2210	4.6.7.3. Parameters

2212	      pcName

2214	         Null terminated string with the property name, from
2215	         Section 2.1.

2217	4.6.7.4. Returns

2219	   If no error, returns a pointer to a character buffer containing the
2220	   property value.  If the property was not set, returns the default
2221	   value.  If an error occurs, returns NULL. The returned string MUST
2222	   NOT be freed.

2224	4.6.8. SLPSetProperty

2226	4.6.8.1. Synopsis

2228	   void SLPSetProperty(const char *pcName,
2229	                       const char *pcValue);

2231	4.6.8.2. Description

2233	   Sets the value of the SLP property to the new value.  The pcValue
2234	   parameter should be the property value as a string.

2236	4.6.8.3. Parameters

2238	      pcName

2240	         Null terminated string with the property name, from
2241	         Section 2.1.

2243	      pcValue

2245	         Null terminated string with the property value, in UTF-8
2246	         character encoding.

2248	4.7. Implementation Notes

2250	4.7.1. Refreshing Registrations

2252	   Clients indicate that they want URLs to be automatically
2253	   refreshed by setting the usLifetime parameter in the SLPReg()
2254	   function call to SLP_LIFETIME_MAXIMUM. This will cause the API
2255	   implementation to refresh the URL before it times out.  Although
2256	   using SLP_LIFETIME_MAXIMUM to designate automatic reregistration
2257	   means that a transient URL can't be registered for the maximum
2258	   lifetime, little hardship is likely to occur, since service URL
2259	   lifetimes are measured in seconds and the client can simply use a
2260	   lifetime of SLP_LIFETIME_MAXIMUM - 1 if a transient URL near the
2261	   maximum lifetime is desired.  API implementations MUST provide this
2262	   facility.

2264	4.7.2. Syntax for String Parameters

2266	   Query strings, attribute registration lists, attribute deregistration
2267	   lists, scope lists, and attribute selection lists follow the syntax
2268	   described in [7] for the appropriate requests.  The API directly
2269	   reflects the strings passed in from clients into protocol requests,
2270	   and directly reflects out strings returned from protocol replies to
2271	   clients.  As a consequence, clients are responsible for formatting
2272	   request strings, including escaping and converting opaque values to
2273	   escaped byte encoded strings.  Similarly, on output, clients are
2274	   required to unescape strings and convert escaped string encoded
2275	   opaques to binary.  The functions SLPEscape() and SLPUnescape() can
2276	   be used for escaping SLP reserved characters, but perform no opaque
2277	   processing.

2279	   Opaque values consist of a character buffer containing a
2280	   UTF-8-encoded string, the first characters of which are the nonUTF-8
2281	   encoding '\ff'.  Subsequent characters are the escaped values for the
2282	   original bytes in the opaque.  The escape convention is relatively
2283	   simple.  An escape consists of a backslash followed by the two
2284	   hexadecimal digits encoding the byte.  An example is '\2c' for the
2285	   byte 0x2c.  Clients handle opaque processing themselves, since the
2286	   algorithm is relatively simple and uniform.

2288	4.7.3. Client Side Syntax Checking

2290	   Client side API implementations may do syntax checking of scope
2291	   names, naming authority names, and service type names, but are
2292	   not required to do so.  Since the C API is designed to be a
2293	   thin layer over the protocol, some low memory SA implementations
2294	   may find extensive syntax checking on the client side to be
2295	   burdensome.  If syntax checking uncovers an error in a parameter, the
2296	   SLP_PARAMETER_BAD error must be returned.  If any parameter is NULL
2297	   and is required to be nonNULL, SLP_PARAMETER_BAD is returned.

2299	4.7.4. System Properties

2301	   The system properties established in the configuration file are
2302	   accessible through the SLPGetProperty() and SLPSetProperty()
2303	   functions.  The SLPSetProperty() function only modifies properties
2304	   in the running process, not in the configuration file.  Properties
2305	   are global to the process, affecting all threads and all handles
2306	   created with SLPOpen.  Errors are checked when the property is used
2307	   and, as with parsing the configuration file, are logged.  Program
2308	   execution continues without interruption by substituting the default
2309	   for the erroneous parameter.  With the exception of net.slp.locale,
2310	   net.slp.typeHint, and net.slp.maxResults, clients of the API should
2311	   rarely be required to override these properties, since they reflect
2312	   properties of the SLP network that are not of concern to individual
2313	   agents.  If changes are required, system administrators should modify
2314	   the configuration file.

2316	4.7.5. Memory Management

2318	   The only API functions returning memory specifically requiring
2319	   deallocation on the part of the client are SLPParseSrvURL(),
2320	   SLPFindScopes(), SLPEscape(), and SLPUnescape().  This memory should
2321	   be freed using SLPFree() when no longer needed.  Character strings
2322	   returned via the SLPGetProperty() function should NOT be freed, they
2323	   are owned by the SLP library.

2325	   Memory passed to callbacks belongs to the library and MUST NOT be
2326	   retained by the client code.  Otherwise, crashes are possible.
2327	   Clients are required to copy data out of the callback parameters.  No
2328	   other use of the parameter memory in callback parameters is allowed.

2330	4.7.6. Asynchronous and Incremental Return Semantics

2332	   If a handle parameter to an API function was opened asynchronously,
2333	   API function calls on the handle check the other parameters, open the
2334	   appropriate operation and return immediately.  In an error occurs in
2335	   the process of starting the operation, an error code is returned.  If
2336	   the handle parameter was opened synchronously, the API function call
2337	   blocks until all results are available, and returns only after the
2338	   results are reported through the callback function.  The return code
2339	   indicates whether any errors occurred both starting and during the
2340	   operation.

2342	   The callback function is called whenever the API library has results
2343	   to report.  The callback code is required to check the error code
2344	   parameter before looking at the other parameters.  If the error code
2345	   is not SLP_OK, the other parameters may be invalid.  The API library
2346	   has the option of terminating any outstanding operation on which an
2347	   error occurs.  The callback code can similarly indicate that the
2348	   operation should be terminated by passing back SLP_FALSE. Callback
2349	   functions are not permitted to recursively call into the API on the
2350	   same SLPHandle.  If an attempt is made to recursively call into
2351	   the API, the API function returns SLP_HANDLE_IN_USE. Prohibiting
2352	   recursive callbacks on the same handle simplifies implementation of
2353	   thread safe code, since locks held on the handle will not be in place
2354	   during a second outcall on the handle.  On the other hand, it means
2355	   that handle creation should be fairly lightweight so a client program
2356	   can easily support multiple outstanding calls.

2358	   The total number of results received can be controlled by setting the
2359	   net.slp.maxResults parameter.

2361	   On the last call to a callback, whether asynchronous or synchronous,
2362	   the status code passed to the callback has value SLP_LAST_CALL. There
2363	   are four reasons why the call can terminate:

2365	      DA reply received

2367	         A reply from a DA has been received and therefore nothing more
2368	         is expected.

2370	      Multicast terminated

2372	         The multicast convergence time has elapsed and the API library
2373	         multicast code is giving up.

2375	      Multicast null results

2377	         Nothing new has been received during multicast for a while and
2378	         the API library multicast code is giving up on that (as an
2379	         optimization).

2381	      Maximum results

2383	         The user has set the net.slp.maxResults property and that
2384	         number of replies has been collected and returned

2386	4.8. Example

2388	   This example illustrates how to discover a mailbox.

2390	   A POP3 server registers itself with the SLP framework.  The
2391	   attributes it registers are "USER", a list of all users whose mail is
2392	   available through the POP3 server.

2394	   The POP3 server code is the following:

2396	   SLPHandle slph;
2397	   SLPRegReport errCallback = POPRegErrCallback;

2399	   /* Create an English SLPHandle, asynchronous processing. */

2401	   SLPError err = SLPOpen("en", SLP_TRUE, &slph);

2403	   if( err != SLP_OK ) {

2405	     /* Deal with error. */

2407	   }

2409	   /* Create the service: URL and attribute parameters. */

2411	   const char* surl = "service:pop3://mail.netsurf.de"; /* the URL */

2413	   const char *pcAttrs = "(user=zaphod,trillian,roger,marvin)"

2415	   /* Perform the registration. */

2417	   err = SLPReg(slph,
2418	                surl,
2419	                SLP_LIFETIME_DEFAULT,
2420	                ppcAttrs,
2421	                errCallback,
2422	                NULL);

2424	   if (err != SLP_OK ) {

2426	      /*Deal with error.*/

2428	   }

2430	   The errCallback reports any errors:

2432	   void
2433	   POPRegErrCallback(SLPHandle hSLP,
2434	                     SLPError errCode,
2435	                     unsigned short usLifetime,
2436	                     void* pvCookie) {

2438	      if( errCode != SLP_OK ) {

2440	        /* Report error through a dialog, message, etc. */

2442	      }

2444	      /*Use lifetime interval to update periodically. */

2446	    }

2448	   The POP3 client locates the server for the user with the following
2449	   code:

2451	   /*
2452	    * The client calls SLPOpen(), exactly as above.
2453	    */

2455	   const char *pcSrvType   = "service:pop3"; /* the service type  */
2456	   const char *pcScopeList = "default";      /* the scope         */
2457	   const char *pcFilter    = "(user=roger)"; /* the search filter */
2458	   SLPSrvURLCallback srvCallback =           /* the callback      */
2459	                                   POPSrvURLCallback;

2461	   err = SLPFindSrvs(slph,
2462	                     pcSrvType, pcScopeList, pcFilter,
2463	                     srvCallback, NULL);

2465	   if( err != SLP_OK ) {

2467	       /* Deal with error. */

2469	   }

2471	   Within the callback, the client code can use the returned POP
2472	   service:

2474	  SLPBoolean
2475	  POPSrvURLCallback(SLPHandle hSLP,
2476	                    const char* pcSrvURL,
2477	                    unsigned short sLifetime,
2478	                    SLPError errCode,
2479	                    void* pvCookie) {

2481	     if( errCode != SLP_OK ) {

2483	        /* Deal with error. */

2485	     }
2486	     SLPSrvURL* pSrvURL;

2488	     errCode = SLPParseSrvURL(pcSrvURL, &pSrvURL);

2490	     if (err != SLP_OK ) {

2492	       /* Deal with error. */

2494	     } else {

2496	       /* get the server's address */

2498	       struct hostent *phe = gethostbyname(pSrvURL.s_pcHost);

2500	       /* use hostname in pSrvURL to connect to the POP3 server
2501	        *     . . .
2502	        */

2504	       SLPFreeSrvURL((void*)pSrvURL);  /* Free the pSrvURL storage */
2505	     }

2507	     return SLP_FALSE;                 /* Done! */
2508	   }

2510	   A client that wanted to discover all the users receiving mail at the
2511	   server uses with the following query:

2513	   /*
2514	    * The client calls SLPOpen(), exactly as above. We assume the
2515	    * service: URL was retrieved into surl.
2516	    */

2518	   const char *pcScopeList = "default";      /* the scope            */
2519	   const char *pcAttrFilter    = "use";      /* the attribute filter */
2520	   SLPAttrCallback attrCallBack =            /* the callback         */
2521	                                  POPUsersCallback

2523	   err =
2524	     SLPFindAttrs(slph,
2525	                  surl,
2526	                  pcScopeList, pcAttrFilter,
2527	                  attrCallBack, NULL);

2529	   if( err != SLP_OK ) {

2531	        /* Deal with error. */

2533	   }
2534	   The callback processes the attributes:

2536	   SLPBoolean
2537	   POPUsersCallback(const char* pcAttrList,
2538	                    SLPError errCode,
2539	                    void* pvCookie) {

2541	     if( errCode != SLP_OK ) {

2543	       /* Deal with error. */

2545	     } else {

2547	       /* Parse attributes. */

2549	     }

2551	     return SLP_FALSE;  /* Done! */

2553	   }

2555	5. Java Language Binding

2557	5.1. Introduction

2559	   The Java API is designed to model the various SLP entities in
2560	   classes and objects.  APIs are provided for SA, UA, and service type
2561	   template access capabilities.  The ServiceLocationManager class
2562	   contains methods that return instances of objects implementing
2563	   SA and UA capability.  Each of these is modeled in an interface.
2564	   The Locator interface provides UA capability and the Advertiser
2565	   interface provides SA capability.  The TemplateRegistry abstract
2566	   class contains methods that return objects for template introspection
2567	   and attribute type checking.  The ServiceURL, ServiceType, and
2568	   ServiceLocationAttribute classes model the basic SLP concepts.  A
2569	   concrete subclass instance of TemplateRegistry is returned by a class
2570	   method.

2572	   All SLP classes and interfaces are located within a single package.
2573	   The package name should begin with the name of the implementation and
2574	   conclude with the suffix "slp".  Thus, the name for a hypothetical
2575	   implementation from the University of Michigan would look like:

2577	                             edu.umich.slp

2579	   This follows the Java convention of prepending the top level DNS
2580	   domain name for the organization implementing the package onto the
2581	   organization's name and using that as the package prefix.

2583	5.2. Exceptions and Errors

2585	   Most parameters to API methods are required to be non-null.  The
2586	   API description indicates if a null parameter is acceptable, or
2587	   if other restrictions constrain a parameter.  When parameters
2588	   are checked for validity (such as not being null) or their
2589	   syntax is checked, an error results in the RuntimeException
2590	   subclass IllegalArgumentException being thrown.  Clients of the
2591	   API are reminded that IllegalArgumentException, derived from
2592	   RuntimeException, is unchecked by the compiler.  Clients should
2593	   thus be careful to include try/catch blocks for it if the relevant
2594	   parameters could be erroneous.

2596	   Standard Java practice is to encode every exceptional condition as a
2597	   separate subclass of Exception.  Because of the relatively high cost
2598	   in code size of Exception subclasses, the API contains only a single
2599	   Exception subclass with different conditions being determined by an
2600	   integer error code property.  A subset, appropriate to Java, of the
2601	   error codes described in Section 3 are available as constants on the
2602	   ServiceLocationException class.  The subset excludes error codes such
2603	   as MEMORY_ALLOC_FAILED.

2605	5.2.1. Class ServiceLocationException

2607	5.2.1.1. Synopsis

2609	   public class ServiceLocationException
2610	   extends Exception

2612	5.2.1.2. Description

2614	   The ServiceLocationException class is thrown by all methods when
2615	   exceptional conditions occur in the SLP framework.  The error
2616	   code property determines the exact nature of the condition, and an
2617	   optional message may provide more information.

2619	5.2.1.3. Fields

2621	   public static final short LANGUAGE_NOT_SUPPORTED = 1
2622	   public static final short PARSE_ERROR = 2
2623	   public static final short INVALID_REGISTRATION = 3
2624	   public static final short SCOPE_NOT_SUPPORTED = 4
2625	   public static final short AUTHENTICATION_ABSENT = 6
2626	   public static final short AUTHENTICATION_FAILED = 7
2627	   public static final short INVALID_UPDATE = 13
2628	   public static final short REFRESH_REJECTED = 15
2629	   public static final short NOT_IMPLEMENTED = 16
2630	   public static final short NETWORK_INIT_FAILED 17
2631	   public static final short NETWORK_TIMED_OUT = 18
2632	   public static final short NETWORK_ERROR = 19
2633	   public static final short INTERNAL_SYSTEM_ERROR = 20
2634	   public static final short TYPE_ERROR = 21
2635	   public static final short BUFFER_OVERFLOW = 22

2637	5.2.1.4. Instance Methods

2639	   public short getErrorCode()

2641	   Return the error code.  The error code takes on one of the static
2642	   field values.

2644	5.3. Basic Data Structures

2646	5.3.1. Interface ServiceLocationEnumeration

2648	   public interface ServiceLocationEnumeration
2649	    extends Enumeration

2651	5.3.1.1. Description

2653	   The ServiceLocationEnumeration class is the return type for all
2654	   Locator SLP operations.  The Java API library may implement this
2655	   class to block until results are available from the SLP operation,
2656	   so that the client can achieve asynchronous operation by retrieving
2657	   results from the enumeration in a separate thread.  Clients use the
2658	   superclass nextElement() method if they are unconcerned with SLP
2659	   exceptions.

2661	5.3.1.2. Instance Methods

2663	   public abstract Object next() throws ServiceLocationException
2664	   Return the next value or block until it becomes available.

2666	   Throws:

2668	      ServiceLocationException

2670	         Thrown if the SLP operation encounters an error.

2672	      NoSuchElementException

2674	         If there are no more elements to return.

2676	5.3.2. Class ServiceLocationAttribute

2678	5.3.2.1. Synopsis

2680	   public class ServiceLocationAttribute
2681	     extends Object implements Serializable

2683	5.3.2.2. Description

2685	   The ServiceLocationAttribute class models SLP attributes.  Instances
2686	   of this class are returned by Locator.findAttributes() and are
2687	   communicated along with register/deregister requests.

2689	5.3.2.3. Constructors

2691	   public ServiceLocationAttribute(String id,Vector values)

2693	   Construct a service location attribute.  Errors in the id or values
2694	   vector result in an IllegalArgumentException.

2696	   Parameters:

2698	      id

2700	         The attribute name.  The String can consist of any Unicode
2701	         character.

2703	      values

2705	         A Vector of one or more attribute values.  Vector contents
2706	         must be uniform in type and one of Integer, String, Boolean,
2707	         or byte[].  If the attribute is a keyword attribute, then the
2708	         parameter should be null.  String values can consist of any
2709	         Unicode character.

2711	5.3.2.4. Class Methods

2713	   public static String escapeId(String id)

2715	   Returns an escaped version of the id parameter, suitable for
2716	   inclusion in a query.  Any reserved characters as specified in [7]
2717	   are escaped using UTF-8 encoding.  If any characters in the tag are
2718	   illegal, throws IllegalArgumentException.

2720	   Parameters:

2722	      id

2724	         The attribute id to escape.  ServiceLocationException is thrown
2725	         if any characters are illegal for an attribute tag.

2727	   public static String escapeValue(Object value)

2729	   Returns a String containing the escaped value parameter as a string,
2730	   suitable for inclusion in a query.  If the parameter is a string,
2731	   any reserved characters as specified in [7] are escaped using UTF-8
2732	   encoding.  If the parameter is a byte array, then the escaped string
2733	   begins with the nonUTF-8 sequence `\ff` and the rest of the string
2734	   consists of the escaped bytes, which is the encoding for opaques.
2735	   If the value parameter is a Boolean or Integer, then the returned
2736	   string contains the object converted into a string.  If the value
2737	   is any type other than String, Integer, Boolean or byte[], an
2738	   IllegalArgumentException is thrown.

2740	   Parameters:

2742	      value

2744	         The attribute value to be converted into a string and escaped.

2746	5.3.2.5. Instance Methods

2748	   public Vector getValues()

2750	   Returns a cloned vector of attribute values, or null if the attribute
2751	   is a keyword attribute.  If the attribute is single-valued, then the
2752	   vector contains only one object.

2754	   public String getId()

2756	   Returns the attribute's name.

2758	   public boolean equals(Object o)

2760	   Overrides Object.equals().  Two attributes are equal if their
2761	   identifiers are equal and their value vectors contain the same number
2762	   of equal values as determined by the Object equals() method.  Values
2763	   having byte[] type are equal if the contents of all byte arrays in
2764	   both attribute vectors match.  Note that the SLP string matching
2765	   algorithm [7] MUST NOT be used for comparing attribute identifiers or
2766	   string values.

2768	   public String toString()

2770	   Overrides Object.toString().  The string returned contains a
2771	   formatted representation of the attribute, giving the attribute's
2772	   id, values, and the Java type of the values.  The returned string is
2773	   suitable for debugging purposes, but is not in SLP wire format.

2775	   public int hashCode()

2777	   Overrides Object.hashCode().  Hashes on the attribute's identifier.

2779	5.3.3. Class ServiceType

2781	5.3.3.1. Synopsis
2782	   public class ServiceType extends Object implements Serializable

2784	5.3.3.2. Description

2786	   The ServiceType object models the SLP service type.  It parses a
2787	   string based service type specifier into its various components, and
2788	   contains property accessors to return the components.  URL schemes,
2789	   protocol service types, and abstract service types are all handled.

2791	5.3.3.3. Constructors

2793	   public ServiceType(String type)

2795	   Construct a service type object from the service type specifier.
2796	   Throws IllegalArgumentException if the type name is syntactically
2797	   incorrect.

2799	   Parameters:

2801	      type

2803	         The service type name as a String.  If the service type is from
2804	         a service:  URL, the "service:" prefix must be intact.

2806	5.3.3.4. Methods

2808	   public boolean isServiceURL()

2810	   Returns true if the type name contains the "service:" prefix.

2812	   public boolean isAbstractType()

2814	   Returns true if the type name is for an abstract type.

2816	   public boolean isNADefault()
2817	   Returns true if the naming authority is the default, i.e.  is the
2818	   empty string.

2820	   public String getConcreteTypeName()

2822	   Returns the concrete type name in an abstract type, or the empty
2823	   string if the service type is not abstract.  For example, if the type
2824	   name is "service:printing:ipp", the method returns "ipp".  If the
2825	   type name is "service:ftp", the method returns "".

2827	   public String getPrincipleTypeName()

2829	   Returns the abstract type name for an abstract type, the protocol
2830	   name in a protocol type, or the URL scheme for a generic URL. For
2831	   example, in the abstract type name "service:printing:ipp", the method
2832	   returns "printing".  In the protocol type name "service:ftp", the
2833	   method returns "ftp".

2835	   public String getAbstractTypeName()

2837	   If the type is an abstract type, returns the fully formatted abstract
2838	   type name including the "service:" and naming authority but without
2839	   the concrete type name or intervening colon.  If not an abstract
2840	   type, returns the empty string.  For example, in the abstract type
2841	   name "service:printing:ipp", the method returns "service:printing".

2843	   public String getNamingAuthority()

2845	   Return the naming authority name, or the empty string if the naming
2846	   authority is the default.

2848	   public boolean equals(Object obj)

2850	   Overrides Object.equals().  The two objects are equal if they are
2851	   both ServiceType objects and the components of both are equal.

2853	   public String toString()
2854	   Returns the fully formatted type name, including the "service:" if
2855	   the type was originally from a service:  URL.

2857	   public int hashCode()

2859	   Overrides Object.hashCode().  Hashes on the string value of the
2860	   ``service'' prefix, naming authority, if any, abstract and concrete
2861	   type names for abstract types, protocol type name for protocol types,
2862	   and URL scheme for generic URLs.

2864	5.3.4. Class ServiceURL

2866	5.3.4.1. Synopsis

2868	   public class ServiceURL extends Object implements Serializable

2870	5.3.4.2. Description

2872	   The ServiceURL object models the advertised SLP service URL. It
2873	   can be either a service:  URL or a regular URL. These objects are
2874	   returned from service lookup requests, and describe the registered
2875	   services.  This class should be a subclass of java.net.URL but can't
2876	   since that class is final.

2878	5.3.4.3. Class Variables

2880	   public static final int NO_PORT = 0

2882	   Indicates that no port information is required or was returned for
2883	   this URL.

2885	   public static final int LIFETIME_NONE = 0

2887	   Indicates that the URL has a zero lifetime.  This value is never
2888	   returned from the API, but can be used to create a ServiceURL object
2889	   to deregister, delete attributes, or find attributes.

2891	   public static final int LIFETIME_DEFAULT = 10800

2893	   The default URL lifetime (3 hours) in seconds.

2895	   public static final int LIFETIME_MAXIMUM = 65535

2897	   The maximum URL lifetime (about 18 hours) in seconds.

2899	   public static final int LIFETIME_PERMANENT = -1

2901	   Indicates that the API implementation should continuously re-register
2902	   the URL until the application exits.

2904	5.3.4.4. Constructors

2906	   public ServiceURL(String URL,int lifetime)

2908	   Construct a service URL object having the specified lifetime.

2910	   Parameters:

2912	      URL

2914	         The URL as a string.  Must be either a service:  URL or a valid
2915	         generic URL according to RFC 2396 [2].

2917	      lifetime

2919	         The service advertisement lifetime in seconds.  This value may
2920	         be between LIFETIME_NONE and LIFETIME_MAXIMUM.

2922	5.3.4.5. Methods

2924	   public ServiceType getServiceType()

2926	   Returns the service type object representing the service type name of
2927	   the URL.

2929	  public final void setServiceType(ServiceType type)
2930	  throws ServiceLocationException

2932	   Set the service type name to the object.  Ignored if the URL is a
2933	   service:  URL.

2935	   Parameters:

2937	      type

2939	         The service type object.

2941	   public String getTransport()

2943	   Get the network layer transport identifier.  If the transport is IP,
2944	   an empty string, "", is returned.

2946	   public String getHost()

2948	   Returns the host identifier.  For IP, this will be the machine name
2949	   or IP address.

2951	   public int getPort()

2953	   Returns the port number, if any.  For non-IP transports, always
2954	   returns NO_PORT.

2956	   public String getURLPath()

2958	   Returns the URL path description, if any.

2960	   public int getLifetime()

2962	   Returns the service advertisement lifetime.  This will be a positive
2963	   int between LIFETIME_NONE and LIFETIME_MAXIMUM.

2965	   public boolean equals(Object obj)

2967	   Compares the object to the ServiceURL and returns true if the two are
2968	   the same.  Two ServiceURL objects are equal if their current service
2969	   types match and they have the same host, port, transport, and URL
2970	   path.

2972	   public String toString()

2974	   Returns a formatted string with the URL. Overrides Object.toString().
2975	   The returned URL has the original service type or URL scheme, not the
2976	   current service type.

2978	   public int hashCode()

2980	   Overrides Object.hashCode().  Hashes on the current service type,
2981	   transport, host, port, and URL part.

2983	5.4. SLP Access Interfaces

2985	5.4.1. Interface Advertiser

2987	5.4.1.1. Synopsis

2989	   public interface Advertiser

2991	5.4.1.2. Description

2993	   The Advertiser is the SA interface, allowing clients to register new
2994	   service instances with SLP, to change the attributes of existing
2995	   services, and to deregister service instances.  New registrations
2996	   and modifications of attributes are made in the language locale
2997	   with which the Advertiser was created, deregistrations of service
2998	   instances are made for all locales.

3000	5.4.1.3. Instance Methods

3002	   public abstract Locale getLocale()
3003	   Return the language locale with which this object was created.

3005	   public abstract void register(ServiceURL URL,
3006	                                 Vector attributes)
3007	   throws ServiceLocationException

3009	   Register a new service with SLP having the given attributes.

3011	   The API library is required to perform the operation in all
3012	   scopes obtained through configuration.

3014	   Parameters:

3016	      URL

3018	         The URL for the service.

3020	      attributes

3022	         A vector of ServiceLocationAttribute objects describing the
3023	         service.

3025	   public abstract void deregister(ServiceURL URL)
3026	   throws ServiceLocationException

3028	   Deregister a service from the SLP framework.  This has the effect
3029	   of deregistering the service from every language locale.  The API
3030	   library is required to perform the operation in all scopes obtained
3031	   through configuration.

3033	   Parameters:

3035	      URL

3037	         The URL for the service.

3039	   public abstract void
3040	   addAttributes(ServiceURL URL,
3041	                 Vector attributes)
3042	   throws ServiceLocationException
3043	   Update the registration by adding the given attributes.  The API
3044	   library is required to perform the operation in all scopes obtained
3045	   through configuration.

3047	   Parameters:

3049	      URL

3051	         The URL for the service.

3053	      attributes

3055	         A Vector of ServiceLocationAttribute objects to add to the
3056	         existing registration.  Use an empty vector to update the URL
3057	         alone.  May not be null.

3059	   public abstract void
3060	   deleteAttributes(ServiceURL URL,
3061	                    Vector attributeIds)
3062	   throws ServiceLocationException

3064	   Delete the attributes from a URL for the locale with which the
3065	   Advertiser was created.  The API library is required to perform the
3066	   operation in all scopes obtained through configuration.

3068	   Parameters:

3070	      URL

3072	         The URL for the service.

3074	      attributeIds

3076	         A vector of Strings indicating the ids of the attributes
3077	         to remove.  The strings may be attribute ids or they
3078	         may be wildcard patterns to match ids.  See [7] for the
3079	         syntax of wildcard patterns.  The strings may include SLP
3080	         reserved characters, they will be escaped by the API before
3081	         transmission.  May not be the empty vector or null.

3083	5.4.2. Interface Locator

3085	5.4.2.1. Synopsis

3087	   public interface Locator

3089	5.4.2.2. Description

3091	   The Locator is the UA interface, allowing clients to query the SLP
3092	   framework about existing service types, services instances, and about
3093	   the attributes of an existing service instance or service type.
3094	   Queries for services and attributes are made in the locale with which
3095	   the Locator was created, queries for service types are independent of
3096	   locale.

3098	5.4.2.3. Instance Methods

3100	   public abstract Locale getLocale()

3102	   Return the language locale with which this object was created.

3104	   public abstract ServiceLocationEnumeration
3105	   findServiceTypes(String namingAuthority,
3106	                    Vector scopes)
3107	   throws ServiceLocationException

3109	   Returns an enumeration of ServiceType objects giving known service
3110	   types for the given scopes and given naming authority.  If no service
3111	   types are found, an empty enumeration is returned.

3113	   Parameters:

3115	      namingAuthority

3117	         The naming authority.  Use "" for the default naming authority
3118	         and "*" for all naming authorities.

3120	      scopes

3122	         A Vector of scope names.  The vector should be selected from
3123	         the results of a findScopes() API invocation.  Use "DEFAULT"
3124	         for the default scope.

3126	   public abstract ServiceLocationEnumeration
3127	   findServices(ServiceType type,
3128	                Vector scopes,
3129	                String searchFilter)
3130	   throws ServiceLocationException

3132	   Returns a vector of ServiceURL objects for services matching the
3133	   query, and having a matching type in the given scopes.  If no
3134	   services are found, an empty enumeration is returned.

3136	   Parameters:

3138	      type

3140	         The SLP service type of the service.

3142	      scopes

3144	         A Vector of scope names.  The vector should be selected from
3145	         the results of a findScopes() API invocation.  Use "DEFAULT"
3146	         for the default scope.

3148	      searchFilter

3150	         An LDAPv3 [4] string encoded query.  If the filter is empty,
3151	         i.e.  "", all services of the requested type in the specified
3152	         scopes are returned.  SLP reserved characters must be escaped
3153	         in the query.  Use ServiceLocationAttribute.escapeId() and
3154	         ServiceLocationAttribute.escapeValue() to construct the query.

3156	   public abstract ServiceLocationEnumeration
3157	   findAttributes(ServiceURL URL,
3158	                  Vector scopes,
3159	                  Vector attributeIds)
3160	   throws ServiceLocationException

3162	   For the URL and scope, return a Vector of ServiceLocationAttribute
3163	   objects whose ids match the String patterns in the attributeIds
3164	   Vector.  The request is made in the language locale of the Locator.
3165	   If no attributes match, an empty enumeration is returned.

3167	   Parameters:

3169	      URL

3171	         The URL for which the attributes are desired.

3173	      scopes

3175	         A Vector of scope names.  The vector should be selected from
3176	         the results of a findScopes() API invocation.  Use "DEFAULT"
3177	         for the default scope.

3179	      attributeIds

3181	         A Vector of String patterns identifying the desired attributes.
3182	         An empty vector means return all attributes.  As described
3183	         in [7], the patterns may include wildcards to match substrings.
3184	         The strings may include SLP reserved characters, they will be
3185	         escaped by the API before transmission.

3187	   public abstract ServiceLocationEnumeration
3188	   findAttributes(ServiceType type,
3189	                  Vector scopes,
3190	                  Vector attributeIds)
3191	   throws ServiceLocationException

3193	   For the type and scope, return a Vector of all ServiceLocationAttribute
3194	   objects whose ids match the String patterns in the attributeIds
3195	   Vector regardless of the Locator's locale.  The request is made
3196	   independent of language locale.  If no attributes are found, an empty
3197	   vector is returned.

3199	   Parameters:

3201	      serviceType

3203	         The service type.

3205	      scopes

3207	         A Vector of scope names.  The vector should be selected from
3208	         the results of a findScopes() API invocation.  Use "DEFAULT"
3209	         for the default scope.

3211	      attributeIds

3213	         A Vector of String patterns identifying the desired
3214	         attributes.  An empty vector means return all attributes.
3215	         As described in [7], the patterns may include wildcards to
3216	         match all prefixes or suffixes.  The patterns may include SLP
3217	         reserved characters, they will be escaped by the API before
3218	         transmission.

3220	5.5. The Service Location Manager

3222	5.5.1. Class ServiceLocationManager

3224	5.5.1.1. Synopsis

3226	    public class ServiceLocationManager
3227	    extends Object

3229	5.5.1.2. Description

3231	   The ServiceLocationManager manages access to the service location
3232	   framework.  Clients obtain the Locator and Advertiser objects
3233	   for UA and SA, and a Vector of known scope names from the
3234	   ServiceLocationManager.

3236	5.5.1.3. Class Methods

3238	   public static int getRefreshInterval()
3239	   throws ServiceLocationException

3241	   Returns the maximum across all DAs of the min-refresh-interval
3242	   attribute.  This value satisfies the advertised refresh interval
3243	   bounds for all DAs, and, if used by the SA, assures that no
3244	   refresh registration will be rejected.  If no DA advertises a
3245	   min-refresh-interval attribute, a value of 0 is returned.

3247	   public static Vector findScopes()
3248	   throws ServiceLocationException

3250	   Returns an Vector of strings with all available scope names.  The
3251	   list of scopes comes from a variety of sources, see Section 2.1 for
3252	   the scope discovery algorithm.  There is always at least one string
3253	   in the Vector, the default scope, "DEFAULT".

3255	   public static Locator
3256	   getLocator(Locale locale)
3257	   throws ServiceLocationException
3258	   Return a Locator object for the given language Locale.  If the
3259	   implementation does not support UA functionality, returns null.

3261	   Parameters:

3263	      locale

3265	         The language locale of the Locator.  The default SLP locale is
3266	         used if null.

3268	   public static Advertiser
3269	   getAdvertiser(Locale locale)
3270	   throws ServiceLocationException

3272	   Return an Advertiser object for the given language locale.  If the
3273	   implementation does not support SA functionality, returns null.

3275	   Parameters:

3277	      locale

3279	         The language locale of the Advertiser.  The default SLP locale
3280	         is used if null.

3282	5.6. Service Template Introspection

3284	5.6.1. Abstract Class TemplateRegistry

3286	5.6.1.1. Synopsis

3288	   public abstract class TemplateRegistry

3290	5.6.1.2. Description

3292	   Subclasses of the TemplateRegistry abstract class provide
3293	   access to service location templates [8].  Classes implementing
3294	   TemplateRegistry perform a variety of functions.  They manage the
3295	   registration and access of service type template documents.  They
3296	   create attribute verifiers from service templates, for verification
3297	   of attributes and introspection on template documents.  Note that
3298	   clients of the Advertiser are not required to verify attributes
3299	   before registering (though they may get a TYPE_ERROR if the
3300	   implementation supports type checking and there is a mismatch with
3301	   the template).

3303	5.6.1.3. Class Methods

3305	   public static TemplateRegistry getTemplateRegistry();

3307	   Returns the distinguished TemplateRegistry object for performing
3308	   operations on and with service templates.  Returns null if the
3309	   implementation doesn't support TemplateRegistry functionality.

3311	5.6.1.4. Instance Methods

3313	   public abstract void
3314	   registerServiceTemplate(ServiceType type,
3315	                           String documentURL,
3316	                           Locale locale,
3317	                           String version)
3318	   throws ServiceLocationException

3320	   Register the service template with the template registry.

3322	   Parameters:

3324	      type

3326	         The service type.

3328	      documentURL

3330	         A string containing the URL of the template document.  May not
3331	         be the empty string.

3333	      locale

3335	         A Locale object containing the language locale of the template.

3337	      version

3339	         The version number identifier of template document.

3341	   public abstract void
3342	   deregisterServiceTemplate(ServiceType type,
3343	                             Locale locale,
3344	                             String version)
3345	   throws ServiceLocationException

3347	   Deregister the template for the service type.

3349	   Parameters:

3351	      type

3353	         The service type.

3355	      locale

3357	         A Locale object containing the language locale of the template.

3359	      version

3361	         A String containing the version number.  Use null to indicate
3362	         the latest version.

3364	   public abstract
3365	   String findTemplateURL(ServiceType type,
3366	                          Locale locale,
3367	                          String version)
3368	   throws ServiceLocationException

3370	   Returns the URL for the template document.

3372	   Parameters:

3374	      type

3376	         The service type.

3378	      locale

3380	         A Locale object containing the language locale of the template.

3382	      version

3384	         A String containing the version number.  Use null to indicate
3385	         the latest version.

3387	   public abstract
3388	   ServiceLocationAttributeVerifier
3389	   attributeVerifier(String documentURL)
3390	   throws ServiceLocationException

3392	   Reads the template document URL and returns an attribute verifier
3393	   for the service type.  The attribute verifier can be used for
3394	   verifying that registration attributes match the template, and for
3395	   introspection on the template definition.

3397	   Parameters:

3399	      documentURL

3401	         A String containing the template document's URL. May not be the
3402	         empty string.

3404	5.6.2. Interface ServiceLocationAttributeVerifier

3406	5.6.2.1. Synopsis

3408	   public interface ServiceLocationAttributeVerifier

3410	5.6.2.2. Description

3412	   The ServiceLocationAttributeVerifier provides access to service
3413	   templates.  Classes implementing this interface parse SLP template
3414	   definitions, provide information on attribute definitions for
3415	   service types, and verify whether a ServiceLocationAttribute object
3416	   matches a template for a particular service type.  Clients obtain
3417	   ServiceLocationAttributeVerifier objects for specific SLP service
3418	   types through the TemplateRegistry.

3420	5.6.2.3. Instance Methods

3422	   public abstract ServiceType getServiceType()

3424	   Returns the SLP service type for which this is the verifier.

3426	   public abstract Locale getLocale()
3427	   Return the language locale of the template.

3429	   public abstract String getVersion()

3431	   Return the template version number identifier.

3433	   public abstract String getURLSyntax()

3435	   Return the URL syntax expression for the service:  URL.

3437	   public abstract String getDescription()

3439	   Return the descriptive help text for the template.

3441	   public abstract ServiceLocationAttributeDescriptor
3442	   getAttributeDescriptor(String attrId)

3444	   Return the ServiceLocationAttributeDescriptor for the attribute
3445	   having the named id.  If no such attribute exists in this template,
3446	   return null.  This method is primarily for GUI tools to display
3447	   attribute information.  Programmatic verification of attributes
3448	   should use the verifyAttribute() method.

3450	   public abstract Enumeration
3451	   getAttributeDescriptors()

3453	   Returns an Enumeration allowing introspection on the attribute
3454	   definition in the service template.  The Enumeration returns
3455	   ServiceLocationAttributeDescriptor objects for the attributes.
3456	   This method is primarily for GUI tools to display attribute
3457	   information.  Programmatic verification of attributes should use the
3458	   verifyAttribute() method.

3460	   public abstract void
3461	   verifyAttribute(
3462	     ServiceLocationAttribute attribute)

3464	   throws ServiceLocationException

3466	   Verify that the attribute matches the template definition.  If the
3467	   attribute doesn't match, ServiceLocationException is thrown with the
3468	   error code as ServiceLocationException.PARSE_ERROR.

3470	   Parameters:

3472	      attribute

3474	         The ServiceLocationAttribute object to be verified.

3476	   public abstract void
3477	   verifyRegistration(
3478	     Vector attributeVector)
3479	   throws ServiceLocationException

3481	   Verify that the Vector of ServiceLocationAttribute objects matches
3482	   the template for this service type.  The vector must contain all the
3483	   required attributes, and all attributes must match their template
3484	   definitions.  If the attributes don't match, ServiceLocationException
3485	   is thrown with the error code as ServiceLocationException.PARSE_ERROR

3487	   Parameters:

3489	      attributeVector

3491	         A Vector of ServiceLocationAttribute objects for the
3492	         registration.

3494	5.6.3. Interface ServiceLocationAttributeDescriptor

3496	5.6.3.1. Synopsis

3498	   public interface
3499	   ServiceLocationAttributeDescriptor

3501	5.6.3.2. Description

3503	   The ServiceLocationAttributeDescriptor interface provides
3504	   introspection on a template attribute definition.  Classes
3505	   implementing the ServiceLocationAttributeDescriptor interface return
3506	   information on a particular service location attribute definition
3507	   from the service template.  This information is primarily for GUI
3508	   tools.  Programmatic attribute verification should be done through
3509	   the ServiceLocationAttributeVerifier.

3511	5.6.3.3. Instance Methods

3513	   public abstract String getId()

3515	   Return a String containing the attribute's id.

3517	   public abstract String getValueType()

3519	   Return a String containing the fully package-qualified Java type of
3520	   the attribute.  SLP types are translated into Java types as follows:

3522	      STRING

3524	         "java.lang.String"

3526	      INTEGER

3528	         "java.lang.Integer"

3530	      BOOLEAN

3532	         "java.lang.Boolean"

3534	      OPAQUE

3536	         "[B" (i.e.  array of byte, byte[])

3538	      KEYWORD

3540	         empty string, ""

3542	 public abstract String getDescription()

3544	   Return a String containing the attribute's help text.

3546	   public abstract Enumeration
3547	   getAllowedValues()

3549	   Return an Enumeration of allowed values for the attribute type.
3550	   For keyword attributes returns null.  For no allowed values (i.e.
3551	   unrestricted) returns an empty Enumeration.

3553	   public abstract Enumeration
3554	   getDefaultValues()

3556	   Return an Enumeration of default values for the attribute type.
3557	   For keyword attributes returns null.  For no allowed values (i.e.
3558	   unrestricted) returns an empty Enumeration.

3560	   public abstract boolean
3561	   getRequiresExplicitMatch()

3563	   Returns true if the "X"" flag is set, indicating that the attribute
3564	   should be included in an any Locator.findServices() request search
3565	   filter.

3567	   public abstract boolean getIsMultivalued()

3569	   Returns true if the "M" flag is set.

3571	   public abstract boolean getIsOptional()

3573	   Returns true if the "O"" flag is set.

3575	   public abstract boolean getIsLiteral()

3577	   Returns true if the "L" flag is set.

3579	   public abstract boolean getIsKeyword()

3581	   Returns true if the attribute is a keyword attribute.

3583	5.7. Implementation Notes

3585	5.7.1. Refreshing Registrations

3587	   A special lifetime constant, ServiceURL.LIFETIME_PERMANENT, is
3588	   used by clients to indicate that the URL should be automatically
3589	   refreshed until the application exits.  The API implementation
3590	   should interpret this flag as indicating that the URL lifetime is
3591	   ServiceURL.LIFETIME_MAXIMUM, and MUST arrange for automatic refresh
3592	   to occur.

3594	5.7.2. Parsing Alternate Transports in ServiceURL

3596	   The ServiceURL class is designed to handle multiple transports.  The
3597	   standard API performs no additional processing on transports other
3598	   than IP except to separate out the host identifier and the URL path.
3599	   However, implementations are free to subclass ServiceURL and support
3600	   additional methods that provide more detailed parsing of alternate
3601	   transport information.  For IP transport, the port number, if any,
3602	   is returned from the getPort() method.  For non-IP transports, the
3603	   getPort() method returns NO_PORT.

3605	5.7.3. String Attribute Values

3607	   In general, translation between Java types for attribute values and
3608	   the SLP on-the-wire string is straightforward.  However, there are
3609	   two corner cases.  If the Java attribute value type is String and
3610	   the value of the string has an on-the-wire representation that is
3611	   inferred by SLP as an integer, the registered attribute value may not
3612	   be what the API client intended.  A similar problem could result if
3613	   the Java attribute value is the string "true" or "false", in which
3614	   case the on-the-wire representation is inferred to boolean.  To
3615	   handle these corner cases, the Java API prepends a space onto the
3616	   string.  So, for example, if the string attribute value is "123",
3617	   the Java API transforms the value to "123 ", which will have an
3618	   on-the-wire representation that is inferred by SLP to be string.
3619	   Since appended and prepended spaces have no effect on query handling,
3620	   this procedure should cause no problem with queries.  API clients
3621	   need to be aware, however, that the transformation is occurring.

3623	5.7.4. Client Side Syntax Checking

3625	   The syntax of scope names, service type names, naming authority
3626	   names, and URLs is described in [7] and [8].  The various methods
3627	   and classes taking String parameters for these entities SHOULD
3628	   type check the parameters for syntax errors on the client side,
3629	   and throw an IllegalArgumentException if an error occurs.  In
3630	   addition, character escaping SHOULD be implemented before network
3631	   transmission for escapable characters in attribute ids and String
3632	   values.  This reduces the number of error messages transmitted.
3633	   The ServiceLocationAttribute class provides methods for clients to
3634	   obtain escaped attribute id and value strings to facilitate query
3635	   construction.

3637	5.7.5. Language Locale Handling

3639	   The Locator and Advertiser interfaces are created with a Locale
3640	   parameter.  The language locale with which these objects are created
3641	   is used in all SLP requests issued through the object.  If the Locale
3642	   parameter is null, the default SLP locale is used.  The default SLP
3643	   locale is determined by, first, checking the net.slp.locale System
3644	   property.  If that is unset, then the default SLP locale [7] is used,
3645	   namely "en".  Note that the default SLP locale may not be the same as
3646	   the default Java locale.

3648	5.7.6. Setting SLP System Properties

3650	   SLP system properties that are originally set in the configuration
3651	   file can be overridden programmatically in API clients by simply
3652	   invoking the System.getProperties() operation to get a copy of the
3653	   system properties, modifying or adding the SLP property in question,
3654	   then using System.setProperties() to set the properties to the
3655	   modified Property object.  Program execution continues without
3656	   interruption by substituting the default for the erroneous parameter.
3657	   Errors are checked when the property is used and are logged.

3659	   The SLP configuration file cannot be read with the java.util.Properties
3660	   file reader because there are some syntactic differences.  The SLP
3661	   configuration file syntax defines a different escape convention
3662	   for non-ASCII characters than the Java syntax.  However, after the
3663	   file has been read, the properties are stored and retrieved from
3664	   java.util.Properties objects.

3666	   Properties are global for a process, affecting all threads
3667	   and all Locator and Advertiser objects obtained through the
3668	   ServiceLocationManager.  With the exception of the net.slp.locale,
3669	   net.slp.typeHint, and net.slp.maxResults properties, clients should
3670	   rarely be required to override these properties, since they reflect
3671	   properties of the SLP network that are not of concern to individual
3672	   agents.  If changes are required, system administrators should modify
3673	   the configuration file.

3675	5.7.7. Multithreading

3677	   Thread-safe operation is relatively easy to achieve in Java.  By
3678	   simply making each method in the classes implementing the Locator
3679	   and Advertiser interfaces synchronized, and by synchronizing access
3680	   to any shared data structures within the class, the Locator and
3681	   Advertiser interfaces are made safe.  Alternatively, finer grained
3682	   synchronization is also possible within the classes implementing
3683	   Advertiser and Locator.

3685	5.7.8. Modular Implementations

3687	   While, at first glance, the API may look rather heavyweight, the
3688	   design has been carefully arranged so that modular implementations
3689	   that provide only SA, only UA, or only service template access
3690	   capability, or any combination of the three, are possible.

3692	   Because the objects returned from the ServiceLocationManager.getLocator()
3693	   and ServiceLocationManager.getAdvertiser() operations are interfaces,
3694	   and because the objects returned through those interfaces are in
3695	   the set of base data structures, an implementation is free to omit
3696	   either UA or SA capability by simply returning null from the instance
3697	   creation operation if the classes implementing the missing function
3698	   cannot be dynamically linked.  API clients are encouraged to check
3699	   for such a contingency, and to signal an exception if it occurs.
3700	   Similarly, the TemplateRegistry concrete subclass can simply be
3701	   omitted from an implementation that only supports UA and/or SA
3702	   clients, and the TemplateRegistry.getRegistry() method can return
3703	   null.  In this way, the API implementation can be tailored for the
3704	   particular memory requirements at hand.

3706	   In addition, if an implementation only supports the minimal subset of
3707	   SLP [7], the unsupported Locator and Advertiser interface operations
3708	   can throw an exception with ServiceLocationException.NOT_IMPLEMENTED
3709	   as the error code.  This supports better source portability between
3710	   low and high memory platforms.

3712	5.7.9. Asynchronous and Incremental Return Semantics

3714	   The Java API contains no specific support for asynchronous operation.
3715	   Incremental return is not needed for the Advertiser because service
3716	   registrations can be broken up into pieces when large.  Asynchronous
3717	   return is also not needed because clients can always issue the
3718	   Advertiser operation in a separate thread if the calling thread can't
3719	   block.

3721	   The Locator can be implemented either synchronously or
3722	   asynchronously.  Since the return type for Locator calls is
3723	   ServiceLocationEnumeration, a Java API implementation that supports
3724	   asynchronous semantics can implement ServiceLocationEnumeration
3725	   to dole results out as they come in, blocking when no results are
3726	   available.  If the client code needs to support other processing
3727	   while the results are trickling in, the call into the enumeration to
3728	   retrieve the results can be done in a separate thread.

3730	   Unlike the C case, collation semantics for return of attributes when
3731	   an attribute request by service type is made require that the API
3732	   collate returned values so that only one attribute having a collation
3733	   of all returned values appear to the API client.  In practice, this
3734	   may limit the amount of asynchronous processing possible with the
3735	   findAttributes() method.  This requirement is imposed because memory
3736	   management is much easier in Java and so implementing collation as
3737	   part of the API should not be as difficult as in C, and it saves the
3738	   client from having to do the collation.

3740	5.8. Example

3742	   In this example, a printer server advertises its availability to
3743	   clients.  Additionally, the server advertises a service template for
3744	   use by client software in validating service requests:

3746	  //Get the Advertiser and TemplateRegistry.

3748	  Advertiser adv = null;
3749	  TemplateRegistry tr = null

3751	  try {

3753	    adv = ServiceLocationManager.getAdvertiser("en");

3755	    tr = TemplateRegistry.getTemplateRegistry();

3757	  } catch( ServiceLocationException ex ) { } //Deal with error.

3759	  if( adv == null ) {

3761	    //Serious error as printer can't be registered
3762	    //  if the implementation doesn't support SA
3763	    //  functionality.

3765	  }

3767	  //Get the printer's attributes, from a file or
3768	  //  otherwise. We assume that the attributes
3769	  //  conform to the template, otherwise, we
3770	  //  could register the template here and verify
3771	  //  them.

3773	  Vector attributes = getPrinterAttributes();

3775	  //Create the service: URL for the printer.

3777	  ServiceURL printerURL =
3778	    new ServiceURL(
3779	      "service:printer:lpr://printshop/color2",
3780	      ServiceURL.LIFETIME_MAXIMUM);

3782	  try {

3784	    //Register the printer.

3786	    adv.register(printerURL, attributes);

3788	    //If the template registry is available,
3789	    //  register the printer's template.

3791	    if( tr != null ) {
3792	      tr.registerServiceTemplate(
3793	        new ServiceType("service:printer:lpr"),
3794	        "http://shop.arv/printer/printer-lpr.slp",
3795	        new Locale("en",""),
3796	        "1.0");

3798	   }

3800	  } catch( ServiceLocationException ex ) { } //Deal with error.

3802	   Suppose a client is looking for color printer.  The following code is
3803	   used to issue a request for printer advertisements:

3805	  Locator loc = null;
3806	  TemplateRegistry tr = null;

3808	  try {

3810	    loc = ServiceLocationManager.getLocator("en");

3812	  } catch( ServiceLocationException ex ) { } //Deal with error.

3814	  if( loc == null ) {
3815	    //Serious error as client can't be located
3816	    //  if the implementation doesn't support
3817	    //  UA functionality.

3819	  }

3821	  //We want a color printer that does CMYK
3822	  //  and prints at least 600 dpi.

3824	  String query = "(&(marker-type=CMYK)(resolution=600))";

3826	  //Get scopes.

3828	  Vector scopes = ServiceLocationManager.findScopes();

3830	  Enumeration services;

3832	  try {

3834	    services =
3835	      loc.findServices(new ServiceType("service:printer"),scopes,query);

3837	  } catch { } //Deal with error.

3839	  if (services.hasMoreElements() ) {

3841	    //Printers can now be used.
3842	    ServiceURL surl = (ServiceURL) services.next();

3844	    Socket sock = new Socket(surl.getHost, surl.getPort());

3846	    // Use the Socket...

3848	  }

3850	6. Internationalization Considerations

3852	6.1. service URL

3854	   The service URL itself must be encoded using the rules set forth
3855	   in [2].  The character set encoding is limited to specific ranges
3856	   within the UTF-8 character set [3].

3858	   The attribute information associated with the service URL must be
3859	   expressed in UTF-8.  See [8] for attribute internationalization
3860	   guidelines.

3862	6.2. Character Set Encoding

3864	   Configuration and serialized registration files are encoded in the
3865	   UTF-8 character set [3].  This is fully compatible with US-ASCII
3866	   character values.  C platforms that do not support UTF-8 are required
3867	   to check the top bit of input bytes to determine whether the incoming
3868	   character is multibyte.  If it is, the character should be dealt
3869	   with accordingly.  This should require no additional implementation
3870	   effort, since the SLP wire protocol requires that strings are encoded
3871	   as UTF-8.  C platforms without UTF-8 support need to supply their own
3872	   support, if only in the form of multibyte string handling.

3874	   At the API level, the character encoding is specified to be Unicode
3875	   for Java and UTF-8 for C. Unicode is the default in Java.  For C, the
3876	   standard US-ASCII 8 bits per character, null terminated C strings are
3877	   a subset of the UTF-8 character set, and so work in the API. Because
3878	   the C API is very simple, the API library needs to do a minimum of
3879	   processing on UTF-8 strings.  The strings primarily just need to be
3880	   reflected into the outgoing SLP messages, and reflected out of the
3881	   API from incoming SLP messages.

3883	6.3. Language Tagging

3885	   All SLP requests and registrations are tagged to indicate in which
3886	   language the strings included are encoded.  This allows multiple
3887	   languages to be supported.  It also presents the possibility that
3888	   error conditions result when a request is made in a language that is
3889	   not supported.  In this case, an error is only returned when there is
3890	   data available, but not obtainable in the language requested.

3892	   The dialect portion of the Language Tag is used on 'best effort'
3893	   basis for matching strings by SLP. Dialects that match are preferred
3894	   over those which don't.  Dialects that do not match will not prevent
3895	   string matching or comparisons from occurring.

3897	7. Security Considerations

3899	   Security is handled within the API library and is not exposed
3900	   to API clients except in the form of exceptions.  The
3901	   net.slp.securityEnabled, property determines whether an SA
3902	   client's messages are signed, but a UA client should be prepared for
3903	   an authentication exception at any time, because it may contact a DA
3904	   with authenticated advertisements.

3906	   An adversary could delete valid service advertisements, provide false
3907	   service information and deny UAs knowledge of existing services
3908	   unless the mechanisms in SLP for authenticating SLP messages are
3909	   used.  These mechanisms allow DAAdverts, SAAdverts, Service URLs and
3910	   Service Attributes to be verified using digital cryptography.  For
3911	   this reason, all SLP agents should be configured to use SLP SPIs.
3912	   See [7] for a description of how this mechanism works.

3914	8. Acknowledgements

3916	   The authors would like to thank Don Provan for his pioneering work
3917	   during the initial stages of API definition.

3919	References

3921	    [1] S. Bradner.  Key Words for Use in RFCs to Indicate Requirement
3922	        Levels.  RFC 2119, March 1997.

3924	    [2] T. Berners-Lee, R. Fielding, and L. Masinter.  Uniform Resource
3925	        Locators (URL): Generic Syntax and Semantics.  RFC 2396, August,
3926	        1998.

3928	    [3] F. Yerfeau  UTF-8, a transformation format of ISO 10646.  RFC
3929	        2279  January 1998.

3931	    [4] T. Howes  The String Representation of LDAP Search Filters  RFC
3932	        2254  December 1997.

3934	    [5] D. Crocker and P Overell.  Augmented BNF for Syntax
3935	        Specifications:  ABNF.  RFC 2234  November 1997.

3937	    [6] H. Alvestrand.  Tags for the Identification of Languages.  RFC
3938	        1766  March 1995.

3940	    [7] E. Guttman, C. Perkins, J. Veizades, and M. Day.  Service
3941	        Location Protocol.  draft-ietf-svrloc-protocol-v2-12.txt  A work
3942	        in progress  Feburary 1999.

3944	    [8] E. Guttman, C. Perkins, J. Kempf  Service Templates and service:
3945	        Schemes  draft-ietf-svrloc-service-scheme-14.txt  A work in
3946	        progress  Feburary 1999.

3948	9. Full Copyright Statement

3950	   Copyright (C) The Internet Society (1997).  All Rights Reserved.

3952	   This document and translations of it may be copied and furnished to
3953	   others, and derivative works that comment on or otherwise explain it
3954	   or assist in its implementation may be prepared, copied, published
3955	   and distributed, in whole or in part, without restriction of any
3956	   kind, provided that the above copyright notice and this paragraph
3957	   are included on all such copies and derivative works.  However,
3958	   this document itself may not be modified in any way, such as by
3959	   removing the copyright notice or references to the Internet Society
3960	   or other Internet organizations, except as needed for the purpose
3961	   of developing Internet standards in which case the procedures
3962	   for copyrights defined in the Internet Standards process must be
3963	   followed, or as required to translate it into languages other than
3964	   English.

3966	   The limited permissions granted above are perpetual and will not be
3967	   revoked by the Internet Society or its successors or assigns.

3969	   This document and the information contained herein is provided on an
3970	   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3971	   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3972	   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3973	   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3974	   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."

3976	Authors' Addresses

3978	   Questions about this memo can be directed to:

3980	James Kempf                                  Erik Guttman
3981	Sun Microsystems                             Sun Microsystems
3982	901 San Antonio Rd.                          Bahnstr. 2
3983	Palo Alto, CA, 94303                         74915 Waibstadt
3984	USA                                          Germany
3985	+1 650 786 5890                              +49 7263 911 701
3986	+1 650 786 6445 (fax)
3987	james.kempf@sun.com                          erik.guttman@sun.com