1slp_api(3SLP) Service Location Protocol Library Functions slp_api(3SLP)
2
6 slp_api - Service Location Protocol Application Programming Interface
7
9 cc [ flag ... ] file ... -lslp [ library ... ]
10 #include <slp.h>
11
14 The slp_api is a C language binding that maps directly into the
15 Service Location Protocol ("SLP") defined by RFC 2614. This imple‐
16 mentation requires minimal overhead. With the exception of the
17 SLPDereg() and SLPDelAttrs() functions, which map into different
18 uses of the SLP deregister request, there is one C language func‐
19 tion per protocol request. Parameters are for the most part charac‐
20 ter buffers. Memory management is kept simple because the client allo‐
21 cates most memory and client callback functions are required to copy
22 incoming parameters into memory allocated by the client code. Any mem‐
23 ory returned directly from the API functions is deallocated using the
24 SLPFree() function.
25 To conform with standard C practice, all character strings passed to
28 and returned through the API are null-terminated, even though the SLP
29 protocol does not use null-terminated strings. Strings passed as
30 parameters are UTF-8 but they may still be passed as a C string (a
31 null-terminated sequence of bytes.) Escaped characters must be encoded
32 by the API client as UTF-8. In the common case of US-ASCII, the usual
33 one byte per character C strings work. API functions assist in escap‐
34 ing and unescaping strings.
35 Unless otherwise noted, parameters to API functions and callbacks are
38 non-NULL. Some parameters may have other restrictions. If any parame‐
39 ter fails to satisfy the restrictions on its value, the operation
40 returns a PARAMETER_BAD error.
41 Syntax for String Parameters
43 Query strings, attribute registration lists, attribute deregistration
44 lists, scope lists, and attribute selection lists follow the syntax
45 described in RFC 2608. The API reflects the strings passed from clients
46 directly into protocol requests, and reflects out strings returned
47 from protocol replies directly to clients. As a consequence, clients
48 are responsible for formatting request strings, including escaping and
49 converting opaque values to escaped byte-encoded strings. Similarly, on
50 output, clients are required to unescape strings and convert escaped
51 string-encoded opaques to binary. The SLPEscape() and SLPUnescape()
52 functions can be used for escaping SLP reserved characters, but they
53 perform no opaque processing.
54 Opaque values consist of a character buffer that contains a
57 UTF-8-encoded string, the first characters of which are the non UTF-8
58 encoding "". Subsequent characters are the escaped values for the orig‐
59 inal bytes in the opaque. The escape convention is relatively simple.
60 An escape consists of a backslash followed by the two hexadecimal dig‐
61 its encoding the byte. An example is "2c" for the byte 0x2c. Clients
62 handle opaque processing themselves, since the algorithm is relatively
63 simple and uniform.
64 System Properties
66 The system properties established in slp.conf(4), the configuration
67 file, are accessible through the SLPGetProperty() and SLPSetProperty()
68 functions. The SLPSetProperty() function modifies properties only in
69 the running process, not in the configuration file. Errors are checked
70 when the property is used and, as with parsing the configuration file,
71 are logged at the LOG_INFO priority. Program execution continues with‐
72 out interruption by substituting the default for the erroneous parame‐
73 ter. In general, individual agents should rarely be required to over‐
74 ride these properties, since they reflect properties of the SLP network
75 that are not of concern to individual agents. If changes are required,
76 system administrators should modify the configuration file.
77 Properties are global to the process, affecting all threads and all
80 handles created with SLPOpen().
81 Memory Management
83 The only API functions that return memory specifically requiring deal‐
84 location on the part of the client are SLPParseSrvURL(), SLPFind‐
85 Scope(), SLPEscape(), and SLPUnescape(). Free this memory with
86 SLPFree() when it is no longer needed. Do not free character strings
87 returned by means of the SLPGetProperty() function.
88 Any memory passed to callbacks belongs to the library, and it must not
91 be retained by the client code. Otherwise, crashes are possible.
92 Clients must copy data out of the callback parameters. No other use of
93 the memory in callback parameters is allowed.
94 Asynchronous and Incremental Return Semantics
96 If a handle parameter to an API function is opened asynchronously, the
97 API function calls on the handle to check the other parameters, opens
98 the appropriate operation, and returns immediately. If an error occurs
99 in the process of starting the operation, the error code is returned.
100 If the handle parameter is opened synchronously, the function call is
101 blocked until all results are available, and it returns only after the
102 results are reported through the callback function. The return code
103 indicates whether any errors occurred during the operation.
104 The callback function is called whenever the API library has results to
107 report. The callback code is required to check the error code parameter
108 before looking at the other parameters. If the error code is not
109 SLP_OK, the other parameters may be NULL or otherwise invalid. The API
110 library can terminate any outstanding operation on which an error
111 occurs. The callback code can similarly indicate that the operation
112 should be terminated by passing back SLP_FALSE to indicate that it is
113 not interested in receiving more results. Callback functions are not
114 permitted to recursively call into the API on the same SLPHandle. If an
115 attempt is made to call into the API, the API function returns SLP_HAN‐
116 DLE_IN_USE. Prohibiting recursive callbacks on the same handle simpli‐
117 fies implementation of thread safe code, since locks held on the handle
118 will not be in place during a second outcall on the handle.
119 The total number of results received can be controlled by setting the
122 net.slp.maxResults parameter.
123 On the last call to a callback, whether asynchronous or synchronous,
126 the status code passed to the callback has value SLP_LAST_CALL. There
127 are four reasons why the call can terminate:
128 DA reply received A reply from a DA has been received and
130 therefore nothing more is expected.
131 Multicast terminated The multicast convergence time has elapsed
134 and the API library multicast code is giving
135 up.
136 Multicast null results Nothing new has been received during multi‐
139 cast for awhile and the API library multicast
140 code is giving up on that (as an optimiza‐
141 tion).
142 Maximum results The user has set the net.slp.maxResults prop‐
145 erty and that number of replies has been col‐
146 lected and returned.
147 Configuration Files
150 The API library reads slp.conf(4), the default configuration file, to
151 obtain the operating parameters. You can specify the location of this
152 file with the SLP_CONF_FILE environment variable. If you do not set
153 this variable, or the file it refers to is invalid, the API will use
154 the default configuration file at /etc/inet/slp.conf instead.
155 Data Structures
157 The data structures used by the SLP API are as follows:
158 The URL Lifetime Type
160 typedef enum {
161 SLP_LIFETIME_DEFAULT = 10800,
162 SLP_LIFETIME_MAXIMUM = 65535
163 } SLPURLLifetime;
164 The enumeration SLPURLLifetime contains URL lifetime values, in sec‐
168 onds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours, while
169 SLP_LIFETIME_MAXIMUM is 18 hours, which corresponds to the maximum
170 size of the lifetime field in SLP messages. Note that on registration
171 SLP_LIFETIME_MAXIMUM causes the advertisement to be continually rereg‐
172 istered until the process exits.
173 The SLPBoolean Type
175 typedef enum {
176 SLP_FALSE = 0,
177 SLP_TRUE = 1
178 } SLPBoolean;
179 The enumeration SLPBoolean is used as a Boolean flag.
183 The Service URL Structure
185 typedef struct srvurl {
186 char *s_pcSrvType;
187 char *s_pcHost;
188 int s_iPort;
189 char *s_pcNetFamily;
190 char *s_pcSrvPart;
191 } SLPSrvURL;
192 The SLPSrvURL structure is filled in by the SLPParseSrvURL() function
196 with information parsed from a character buffer containing a service
197 URL. The fields correspond to different parts of the URL, as follows:
198 s_pcSrvType A pointer to a character string containing the service
200 type name, including naming authority.
201 s_pcHost A pointer to a character string containing the host
204 identification information.
205 s_iPort The port number, or zero, if none. The port is only
208 available if the transport is IP.
209 s_pcNetFamily A pointer to a character string containing the network
212 address family identifier. Possible values are "ipx"
213 for the IPX family, "at" for the Appletalk family, and
214 "", the empty string, for the IP address family.
215 s_pcSrvPart The remainder of the URL, after the host identifica‐
218 tion.
219 The host and port should be sufficient to open a
221 socket to the machine hosting the service; the remain‐
222 der of the URL should allow further differentiation of
223 the service.
224 The SLPHandle
227 typedef void* SLPHandle;
228 The SLPHandle type is returned by SLPOpen() and is a parameter to all
232 SLP functions. It serves as a handle for all resources allocated on
233 behalf of the process by the SLP library. The type is opaque.
234 Callbacks
236 Include a function pointer to a callback function specific to a partic‐
237 ular API operation in the parameter list when the API function is
238 invoked. The callback function is called with the results of the opera‐
239 tion in both the synchronous and asynchronous cases. When the callback
240 function is invoked, the memory included in the callback parameters is
241 owned by the API library, and the client code in the callback must copy
242 out the contents if it wants to maintain the information longer than
243 the duration of the current callback call.
244 Each callback parameter list contains parameters for reporting the
247 results of the operation, as well as an error code parameter and a
248 cookie parameter. The error code parameter reports the error status of
249 the ongoing (for asynchronous) or completed (for synchronous) opera‐
250 tion. The cookie parameter allows the client code that starts the oper‐
251 ation by invoking the API function to pass information down to the
252 callback without using global variables. The callback returns an SLP‐
253 Boolean to indicate whether the API library should continue processing
254 the operation. If the value returned from the callback is SLP_TRUE,
255 asynchronous operations are terminated. Synchronous operations ignore
256 the return since the operation is already complete.
257 SLPRegReport()
259 typedef void SLPRegReport(SLPHandle hSLP,
260 SLPError errCode,
261 void *pvCookie);
262 SLPRegReport() is the callback function to the SLPReg(), SLPDereg(),
266 and SLPDelAttrs() functions. The SLPRegReport() callback has the fol‐
267 lowing parameters:
268 hSLP TheSLPHandle() used to initiate the operation.
270 errCode An error code indicating if an error occurred during the
273 operation.
274 pvCookie Memory passed down from the client code that called the
277 original API function, starting the operation. It may be
278 NULL.
279 SLPSrvTypeCallback()
282 typedef SLPBoolean SLPSrvTypeCallback(SLPHandle hSLP,
283 const char* pcSrvTypes,
284 SLPError errCode,
285 void *pvCookie);
286 The SLPSrvTypeCallback() type is the type of the callback function
290 parameter to the SLPFindSrvTypes() function. The results are collated
291 when the hSLP handle is opened either synchronously or asynchronously.
292 The SLPSrvTypeCallback() callback has the following parameters:
293 hSLP The SLPHandle used to initiate the operation.
295 pcSrvTypes A character buffer containing a comma-separated, null-
298 terminated list of service types.
299 errCode An error code indicating if an error occurred during the
302 operation. The callback should check this error code
303 before processing the parameters. If the error code is
304 other than SLP_OK, then the API library may choose to
305 terminate the outstanding operation.
306 pvCookie emory passed down from the client code that called the
309 original API function, starting the operation. It can be
310 NULL.
311 SLPSrvURLCallback
314 typedef SLPBoolean SLPSrvURLCallback(SLPHandle hSLP,
315 const char* pcSrvURL,
316 unsigned short usLifetime,
317 SLPError errCode,
318 void *pvCookie);
319 The SLPSrvURLCallback() type is the type of the callback function
323 parameter to the SLPFindSrvs() function. The results are collated,
324 regardless of whether the hSLP was opened collated or uncollated. The
325 SLPSrvURLCallback() callback has the following parameters:
326 hSLP The SLPHandle used to initiate the operation.
328 pcSrvURL A character buffer containing the returned service URL.
331 usLifetime An unsigned short giving the life time of the service
334 advertisement. The value must be an unsigned integer less
335 than or equal to SLP_LIFETIME_MAXIMUM.
336 errCode An error code indicating if an error occurred during the
339 operation. The callback should check this error code
340 before processing the parameters. If the error code is
341 other than SLP_OK, then the API library may choose to
342 terminate the outstanding operation.
343 pvCookie Memory passed down from the client code that called the
346 original API function, starting the operation. It can be
347 NULL.
348 SLPAttrCallback
351 typedef SLPBoolean SLPAttrCallback(SLPHandle hSLP,
352 const char* pcAttrList,
353 SLPError errCode,
354 void *pvCookie);
355 The SLPAttrCallback() type is the type of the callback function parame‐
359 ter to the SLPFindAttrs() function.
360 The behavior of the callback differs depending upon whether the
363 attribute request was by URL or by service type. If the SLPFindAttrs()
364 operation was originally called with a URL, the callback is called
365 once, in addition to the last call, regardless of whether the handle
366 was opened asynchronously or synchronously. The pcAttrList parameter
367 contains the requested attributes as a comma-separated list. It is
368 empty if no attributes match the original tag list.
369 If the SLPFindAttrs() operation was originally called with a service
372 type, the value of pcAttrList and the calling behavior depend upon
373 whether the handle was opened asynchronously or synchronously. If the
374 handle was opened asynchronously, the callback is called every time the
375 API library has results from a remote agent. The pcAttrList parameter
376 is collated between calls, and contains a comma-separated list of the
377 results from the agent that immediately returned. If the handle was
378 opened synchronously, the results are collated from all returning
379 agents, the callback is called once, and the pcAttrList parameter is
380 set to the collated result.
381 SLPAttrCallback() callback has the following parameters:
384 hSLP The SLPHandle used to initiate the operation.
386 pcAttrList A character buffer containing a comma-separated and null-
389 terminated list of attribute id/value assignments, in SLP
390 wire format.
391 errCode An error code indicating if an error occurred during the
394 operation. The callback should check this error code
395 before processing the parameters. If the error code is
396 other than SLP_OK, then the API library may choose to
397 terminate the outstanding operation.
398 pvCookie Memory passed down from the client code that called the
401 original API function, starting the operation. It can be
402 NULL.
403
406 An interface that is part of the SLP API may return one of the follow‐
407 ing values.
408 SLP_LAST_CALL The SLP_LAST_CALL code is passed to call‐
410 back functions when the API library has
411 no more data for them and therefore no
412 further calls will be made to the call‐
413 back on the currently outstanding opera‐
414 tion. The callback uses this to signal
415 the main body of the client code that no
416 more data will be forthcoming on the
417 operation, so that the main body of the
418 client code can break out of data collec‐
419 tion loops. On the last call of a call‐
420 back during both a synchronous and asyn‐
421 chronous call, the error code parameter
422 has value SLP_LAST_CALL, and the other
423 parameters are all NULL. If no results
424 are returned by an API operation, then
425 only one call is made, with the error
426 parameter set to SLP_LAST_CALL.
427 SLP_OK The SLP_OK code indicates that the no
430 error occurred during the operation.
431 SLP_LANGUAGE_NOT_SUPPORTED No DA or SA has service advertisement
434 information in the language requested,
435 but at least one DA or SA might have
436 information for that service in another
437 language.
438 SLP_PARSE_ERROR The SLP message was rejected by a remote
441 SLP agent. The API returns this error
442 only when no information was retrieved,
443 and at least one SA or DA indicated a
444 protocol error. The data supplied through
445 the API may be malformed or damaged in
446 transit.
447 SLP_INVALID_REGISTRATION The API may return this error if an
450 attempt to register a service was
451 rejected by all DAs because of a mal‐
452 formed URL or attributes.SLP does not
453 return the error if at least one DA
454 accepts the registration.
455 SLP_SCOPE_NOT_SUPPORTED The API returns this error if the UA or
458 SA has been configured with the
459 net.slp.useScopes list of scopes and the
460 SA request did not specify one or more of
461 these allowable scopes, and no others. It
462 may also be returned by a DA if the scope
463 included in a request is not supported by
464 a DA.
465 SLP_AUTHENTICATION_ABSENT This error arises when the UA or SA
468 failed to send an authenticator for
469 requests or registrations when security
470 is enabled and thus required.
471 SLP_AUTHENTICATION_FAILED This error arises when a authentication
474 on an SLP message received from a remote
475 SLP agent failed.
476 SLP_INVALID_UPDATE An update for a nonexisting registration
479 was issued, or the update includes a ser‐
480 vice type or scope different than that in
481 the initial registration.
482 SLP_REFRESH_REJECTED The SA attempted to refresh a registra‐
485 tion more frequently than the minimum
486 refresh interval. The SA should call the
487 appropriate API function to obtain the
488 minimum refresh interval to use.
489 SLP_NOT_IMPLEMENTED An outgoing request overflowed the maxi‐
492 mum network MTU size. The request should
493 be reduced in size or broken into pieces
494 and tried again.
495 SLP_BUFFER_OVERFLOW An outgoing request overflowed the maxi‐
498 mum network MTU size. The request should
499 be reduced in size or broken into pieces
500 and tried again.
501 SLP_NETWORK_TIMED_OUT When no reply can be obtained in the time
504 specified by the configured timeout
505 interval, this error is returned.
506 SLP_NETWORK_INIT_FAILED If the network cannot initialize prop‐
509 erly, this error is returned.
510 SLP_MEMORY_ALLOC_FAILED If the API fails to allocate memory, the
513 operationis aborted and returns this.
514 SLP_PARAMETER_BAD If a parameter passed into an interface
517 is bad, this error is returned.
518 SLP_NETWORK_ERROR The failure of networking during normal
521 operations causes this error to be
522 returned.
523 SLP_INTERNAL_SYSTEM_ERROR A basic failure of the API causes this
526 error to be returned. This occurs when a
527 system call or library fails. The opera‐
528 tion could not recover.
529 SLP_HANDLE_IN_USE In the C API, callback functions are not
532 permitted to recursively call into the
533 API on the same SLPHandle, either
534 directly or indirectly. If an attempt is
535 made to do so, this error is returned
536 from the called API function
537
540 SLPOpen() open an SLP handle
541 SLPClose() close an open SLP handle
544 SLPReg() register a service advertisement
547 SLPDereg() deregister a service advertisement
550 SLPDelAttrs() delete attributes
553 SLPFindSrvTypes() return service types
556 SLPFindSrvs() return service URLs
559 SLPFindAttrs() return service attributes
562 SLPGetRefreshInterval() return the maximum allowed refresh interval
565 for SAs
566 SLPFindScopes() return list of configured and discovered
569 scopes
570 SLPParseSrvURL() parse service URL
573 SLPEscape() escape special characters
576 SLPUnescape() translate escaped characters into UTF-8
579 SLPGetProperty() return SLP configuration property
582 SLPSetProperty() set an SLP configuration property
585 slp_strerror() map SLP error code to message
588 SLPFree() free memory
591
594 When SLP_CONF_FILE is set, use this file for configuration.
595
597 See attributes(5) for descriptions of the following attributes:
598 ┌─────────────────────────────┬─────────────────────────────┐
603 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
604 ├─────────────────────────────┼─────────────────────────────┤
605 │Availability │SUNWslpu │
606 ├─────────────────────────────┼─────────────────────────────┤
607 │CSI │CSI-enabled │
608 ├─────────────────────────────┼─────────────────────────────┤
609 │MT-Level │Safe │
610 └─────────────────────────────┴─────────────────────────────┘
611
613 slpd(1M), slp.conf(4), slpd.reg(4), attributes(5)
614 System Administration Guide: Network Services
617 Guttman, E., Perkins, C., Veizades, J., and Day, M. RFC 2608, Service
620 Location Protocol, Version 2. The Internet Society. June 1999.
621 Kempf, J. and Guttman, E. RFC 2614, An API for Service Location. The
624 Internet Society. June 1999.
625SunOS 5.11 16 Jan 2003 slp_api(3SLP)