Warning: That file was not part of the compilation database. It may have many parsing errors.
1 | /***************************************************************************/ |
---|---|
2 | /* */ |
3 | /* Project: OpenSLP - OpenSource implementation of Service Location */ |
4 | /* Protocol */ |
5 | /* */ |
6 | /* File: slp.h */ |
7 | /* */ |
8 | /* Abstract: Main header file for the SLP API exactly as described by */ |
9 | /* rfc2614. This is the only file that needs to be included */ |
10 | /* in order make all SLP API declarations. */ |
11 | /* */ |
12 | /* Author(s) Matt Peterson <mpeterson@caldera.com> */ |
13 | /*-------------------------------------------------------------------------*/ |
14 | /* */ |
15 | /* Please submit patches to http://www.openslp.org */ |
16 | /* */ |
17 | /*-------------------------------------------------------------------------*/ |
18 | /* */ |
19 | /* Copyright (C) 2000 Caldera Systems, Inc */ |
20 | /* All rights reserved. */ |
21 | /* */ |
22 | /* Redistribution and use in source and binary forms, with or without */ |
23 | /* modification, are permitted provided that the following conditions are */ |
24 | /* met: */ |
25 | /* */ |
26 | /* Redistributions of source code must retain the above copyright */ |
27 | /* notice, this list of conditions and the following disclaimer. */ |
28 | /* */ |
29 | /* Redistributions in binary form must reproduce the above copyright */ |
30 | /* notice, this list of conditions and the following disclaimer in */ |
31 | /* the documentation and/or other materials provided with the */ |
32 | /* distribution. */ |
33 | /* */ |
34 | /* Neither the name of Caldera Systems nor the names of its */ |
35 | /* contributors may be used to endorse or promote products derived */ |
36 | /* from this software without specific prior written permission. */ |
37 | /* */ |
38 | /* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS */ |
39 | /* `AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT */ |
40 | /* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR */ |
41 | /* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CALDERA */ |
42 | /* SYSTEMS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, */ |
43 | /* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */ |
44 | /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, */ |
45 | /* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON */ |
46 | /* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT */ |
47 | /* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE */ |
48 | /* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ |
49 | /* */ |
50 | /***************************************************************************/ |
51 | |
52 | #if(!defined SLP_H_INCLUDED) |
53 | #define SLP_H_INCLUDED |
54 | |
55 | #if(defined __cplusplus) |
56 | extern "C" |
57 | { |
58 | #endif |
59 | |
60 | #if defined(_WIN32) && defined(_MSC_VER) |
61 | /* MSVC auto-exports, BCB uses .def file */ |
62 | # define SLPCALLBACK |
63 | # ifdef LIBSLP_EXPORTS |
64 | # define SLPEXP __declspec(dllexport) |
65 | # elif defined(LIBSLP_STATIC) |
66 | # define SLPEXP |
67 | # else |
68 | # define SLPEXP __declspec(dllimport) |
69 | # endif |
70 | # define SLPAPI |
71 | #else |
72 | # define SLPCALLBACK |
73 | # define SLPEXP |
74 | # define SLPAPI |
75 | #endif |
76 | |
77 | /*==========================================================================*/ |
78 | /* lifetime values, in seconds, that are frequently used. */ |
79 | /*==========================================================================*/ |
80 | #define SLP_LIFETIME_DEFAULT 10800 /* 3 hours */ |
81 | #define SLP_LIFETIME_MAXIMUM 65535 /* 18 hours */ |
82 | |
83 | |
84 | /*==========================================================================*/ |
85 | /* SLPError */ |
86 | /* --------- */ |
87 | /* The SLPError type represents error codes that are returned from API */ |
88 | /* functions. */ |
89 | typedef int SLPError; |
90 | |
91 | #define SLP_LAST_CALL 1 |
92 | |
93 | /* passed to callback functions when the API */ |
94 | /* library has no more data for them and therefore no further calls */ |
95 | /* will be made to the callback on the currently outstanding operation. */ |
96 | /* The callback can use this to signal the main body of the client code */ |
97 | /* that no more data will be forthcoming on the operation, so that the */ |
98 | /* main body of the client code can break out of data collection loops. */ |
99 | /* On * the last call of a callback during both a synchronous and */ |
100 | /* asynchronous call, the error code parameter has value SLP_LAST_CALL, */ |
101 | /* and the other parameters are all NULL. If no results are returned by */ |
102 | /* an API operation, then only one call is made, with the error */ |
103 | /* parameter set to SLP_LAST_CALL. */ |
104 | |
105 | #define SLP_OK 0 |
106 | |
107 | /* indicates that the no error occurred during the operation. */ |
108 | |
109 | #define SLP_LANGUAGE_NOT_SUPPORTED -1 |
110 | |
111 | /* No DA or SA has service advertisement or attribute information */ |
112 | /* in the language requested, but at least one DA or SA indicated, */ |
113 | /* via the LANGUAGE_NOT_SUPPORTED error code, that it might have */ |
114 | /* information for that service in another language */ |
115 | |
116 | #define SLP_PARSE_ERROR -2 |
117 | |
118 | /* The SLP message was rejected by a remote SLP agent. The API */ |
119 | /* returns this error only when no information was retrieved, and */ |
120 | /* at least one SA or DA indicated a protocol error. The data */ |
121 | /* supplied through the API may be malformed or a may have been */ |
122 | /* damaged in transit. */ |
123 | |
124 | #define SLP_INVALID_REGISTRATION -3 |
125 | |
126 | /* The API may return this error if an attempt to register a */ |
127 | /* service was rejected by all DAs because of a malformed URL or */ |
128 | /* attributes. SLP does not return the error if at least one DA */ |
129 | /* accepted the registration. */ |
130 | |
131 | #define SLP_SCOPE_NOT_SUPPORTED -4 |
132 | |
133 | /* The API returns this error if the SA has been configured with */ |
134 | /* net.slp.useScopes value-list of scopes and the SA request did */ |
135 | /* not specify one or more of these allowable scopes, and no */ |
136 | /* others. It may be returned by a DA or SA if the scope included */ |
137 | /* in a request is not supported by the DA or SA. */ |
138 | |
139 | #define SLP_AUTHENTICATION_ABSENT -6 |
140 | |
141 | /* if the SLP framework supports authentication, this error arises */ |
142 | /* when the UA or SA failed to send an authenticator for requests */ |
143 | /* or registrations in a protected scope. */ |
144 | |
145 | #define SLP_AUTHENTICATION_FAILED -7 |
146 | |
147 | /* If the SLP framework supports authentication, this error arises */ |
148 | /* when a authentication on an SLP message failed */ |
149 | |
150 | #define SLP_INVALID_UPDATE -13 |
151 | |
152 | /* An update for a non-existing registration was issued, or the */ |
153 | /* update includes a service type or scope different than that in */ |
154 | /* the initial registration, etc. */ |
155 | |
156 | #define SLP_REFRESH_REJECTED -15 |
157 | |
158 | /* The SA attempted to refresh a registration more frequently */ |
159 | /* than the minimum refresh interval. The SA should call the */ |
160 | /* appropriate API function to obtain the minimum refresh interval */ |
161 | /* to use. */ |
162 | |
163 | #define SLP_NOT_IMPLEMENTED -17 |
164 | |
165 | /* If an unimplemented feature is used, this error is returned. */ |
166 | |
167 | #define SLP_BUFFER_OVERFLOW -18 |
168 | |
169 | /* An outgoing request overflowed the maximum network MTU size. */ |
170 | /* The request should be reduced in size or broken into pieces and */ |
171 | /* tried again. */ |
172 | |
173 | #define SLP_NETWORK_TIMED_OUT -19 |
174 | |
175 | /* When no reply can be obtained in the time specified by the */ |
176 | /* configured timeout interval for a unicast request, this error */ |
177 | /* is returned. */ |
178 | |
179 | #define SLP_NETWORK_INIT_FAILED -20 |
180 | |
181 | /* If the network cannot initialize properly, this error is */ |
182 | /* returned. Will also be returned if an SA or DA agent (slpd) */ |
183 | /* can not be contacted. See SLPRegReport() callback. */ |
184 | |
185 | #define SLP_MEMORY_ALLOC_FAILED -21 |
186 | |
187 | /* Out of memory error */ |
188 | |
189 | #define SLP_PARAMETER_BAD -22 |
190 | |
191 | /* If a parameter passed into an interface is bad, this error is */ |
192 | /* returned. */ |
193 | |
194 | #define SLP_NETWORK_ERROR -23 |
195 | |
196 | /* The failure of networking during normal operations causes this */ |
197 | /* error to be returned. */ |
198 | |
199 | #define SLP_INTERNAL_SYSTEM_ERROR -24 |
200 | |
201 | /* A basic failure of the API causes this error to be returned. */ |
202 | /* This occurs when a system call or library fails. The operation */ |
203 | /* could not recover. */ |
204 | |
205 | #define SLP_HANDLE_IN_USE -25 |
206 | |
207 | /* In the C API, callback functions are not permitted to */ |
208 | /* recursively call into the API on the same SLPHandle, either */ |
209 | /* directly or indirectly. If an attempt is made to do so, this */ |
210 | /* error is returned from the called API function. */ |
211 | |
212 | #define SLP_TYPE_ERROR -26 |
213 | |
214 | |
215 | #ifndef UNICAST_NOT_SUPPORTED |
216 | /* The SLP UA needs to send a unicast query to a SA because this SA has */ |
217 | /* sent a packet > MTU size */ |
218 | # define SLP_RETRY_UNICAST -27 |
219 | #endif |
220 | |
221 | |
222 | /* If the API supports type checking of registrations against */ |
223 | /* service type templates, this error can arise if the attributes */ |
224 | /* in a registration do not match the service type template for */ |
225 | /* the service. */ |
226 | |
227 | /*==========================================================================*/ |
228 | /* SLPBoolean */ |
229 | /*------------ */ |
230 | /* The SLPBoolean enum is used as a boolean flag. */ |
231 | typedef enum |
232 | { |
233 | SLP_FALSE = 0, |
234 | SLP_TRUE = 1 |
235 | } SLPBoolean; |
236 | |
237 | |
238 | /*==========================================================================*/ |
239 | /* SLPSrvURL */ |
240 | /*----------- */ |
241 | /* The SLPSrvURL structure is filled in by the SLPParseSrvURL() function */ |
242 | /* with information parsed from a character buffer containing a service */ |
243 | /* URL. The fields correspond to different parts of the URL. Note that */ |
244 | /* the structure is in conformance with the standard Berkeley sockets */ |
245 | /* struct servent, with the exception that the pointer to an array of */ |
246 | /* characters for aliases (s_aliases field) is replaced by the pointer */ |
247 | /* to host name (s_pcHost field). */ |
248 | typedef struct srvurl |
249 | { |
250 | char *s_pcSrvType; |
251 | /* A pointer to a character string containing the service */ |
252 | /* type name, including naming authority. The service type */ |
253 | /* name includes the "service:" if the URL is of the service: */ |
254 | /* scheme. */ |
255 | |
256 | char *s_pcHost; |
257 | /* A pointer to a character string containing the host */ |
258 | /* identification information. */ |
259 | |
260 | int s_iPort; |
261 | /* The port number, or zero if none. The port is only available */ |
262 | /* if the transport is IP. */ |
263 | |
264 | char *s_pcNetFamily; |
265 | /* A pointer to a character string containing the network address */ |
266 | /* family identifier. Possible values are "ipx" for the IPX */ |
267 | /* family, "at" for the Appletalk family, and "" (i.e. the empty */ |
268 | /* string) for the IP address family. */ |
269 | |
270 | char *s_pcSrvPart; |
271 | /* The remainder of the URL, after the host identification. */ |
272 | |
273 | } SLPSrvURL; |
274 | /*=========================================================================*/ |
275 | |
276 | |
277 | #if(!defined SLPHANDLE_INTERNAL) |
278 | |
279 | /*=========================================================================*/ |
280 | typedef void* SLPHandle; |
281 | /* */ |
282 | /* The SLPHandle type is returned by SLPOpen() and is a parameter to all */ |
283 | /* SLP functions. It serves as a handle for all resources allocated on */ |
284 | /* behalf of the process by the SLP library. The type is opaque, since */ |
285 | /* the exact nature differs depending on the implementation. */ |
286 | /*=========================================================================*/ |
287 | #endif |
288 | |
289 | |
290 | |
291 | /*=========================================================================*/ |
292 | typedef void SLPCALLBACK SLPRegReport(SLPHandle hSLP, |
293 | SLPError errCode, |
294 | void *pvCookie); |
295 | /* */ |
296 | /* The SLPRegReport callback type is the type of the callback function */ |
297 | /* to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. */ |
298 | /* */ |
299 | /* hSLP The SLPHandle used to initiate the operation. */ |
300 | /* */ |
301 | /* errCode An error code indicating if an error occurred during the */ |
302 | /* operation. */ |
303 | /* */ |
304 | /* pvCookie Memory passed down from the client code that called the */ |
305 | /* original API function, starting the operation. May be NULL. */ |
306 | /*=========================================================================*/ |
307 | |
308 | |
309 | /*=========================================================================*/ |
310 | typedef SLPBoolean SLPCALLBACK SLPSrvTypeCallback(SLPHandle hSLP, |
311 | const char* pcSrvTypes, |
312 | SLPError errCode, |
313 | void *pvCookie); |
314 | /* */ |
315 | /* The SLPSrvTypeCallback type is the type of the callback function */ |
316 | /* parameter to SLPFindSrvTypes() function. If the hSLP handle */ |
317 | /* parameter was opened asynchronously, the results returned through the */ |
318 | /* callback MAY be uncollated. If the hSLP handle parameter was opened */ |
319 | /* synchronously, then the returned results must be collated and */ |
320 | /* duplicates eliminated. */ |
321 | /* */ |
322 | /* hSLP The SLPHandle used to initiate the operation. */ |
323 | /* */ |
324 | /* pcSrvTypes A character buffer containing a comma separated, null */ |
325 | /* terminated list of service types. */ |
326 | /* */ |
327 | /* errCode An error code indicating if an error occurred during the */ |
328 | /* operation. The callback should check this error code befor*/ |
329 | /* processing the parameters. If the error code is other than*/ |
330 | /* SLP_OK, then the API library may choose to terminate the */ |
331 | /* outstanding operation. */ |
332 | /* */ |
333 | /* pvCookie Memory passed down from the client code that called the */ |
334 | /* original API function, starting the operation. May be NULL*/ |
335 | /* */ |
336 | /* Returns The client code should return SLP_TRUE if more data is */ |
337 | /* desired, otherwise return SLP_FALSE */ |
338 | /*=========================================================================*/ |
339 | |
340 | |
341 | /*=========================================================================*/ |
342 | typedef SLPBoolean SLPCALLBACK SLPSrvURLCallback(SLPHandle hSLP, |
343 | const char* pcSrvURL, |
344 | unsigned short sLifetime, |
345 | SLPError errCode, |
346 | void *pvCookie); |
347 | /* */ |
348 | /* The SLPSrvURLCallback type is the type of the callback function */ |
349 | /* parameter to SLPFindSrvs() function. If the hSLP handle parameter */ |
350 | /* was opened asynchronously, the results returned through the callback */ |
351 | /* MAY be uncollated. If the hSLP handle parameter was opened */ |
352 | /* synchronously, then the returned results must be collated and */ |
353 | /* duplicates eliminated. */ |
354 | /* */ |
355 | /* hSLP The SLPHandle used to initiate the operation. */ |
356 | /* */ |
357 | /* pcSrvURL A character buffer containing the returned service URL. */ |
358 | /* May be NULL if errCode not SLP_OK. */ |
359 | /* */ |
360 | /* sLifetime An unsigned short giving the life time of the service */ |
361 | /* advertisement, in seconds. The value must be an unsigned */ |
362 | /* integer less than or equal to SLP_LIFETIME_MAXIMUM. */ |
363 | /* */ |
364 | /* errCode An error code indicating if an error occurred during the */ |
365 | /* operation. The callback should check this error code */ |
366 | /* before processing the parameters. If the error code is */ |
367 | /* other than SLP_OK, then the API library may choose to */ |
368 | /* terminate the outstanding operation. SLP_LAST_CALL is */ |
369 | /* returned when no more services are available and the */ |
370 | /* callback will not be called again.. */ |
371 | /* */ |
372 | /* pvCookie Memory passed down from the client code that called the */ |
373 | /* original API function, starting the operation. */ |
374 | /* May be NULL. */ |
375 | /* */ |
376 | /* Returns The client code should return SLP_TRUE if more data is */ |
377 | /* desired, otherwise return SLP_FALSE */ |
378 | /*=========================================================================*/ |
379 | |
380 | |
381 | /*=========================================================================*/ |
382 | typedef SLPBoolean SLPCALLBACK SLPAttrCallback(SLPHandle hSLP, |
383 | const char* pcAttrList, |
384 | SLPError errCode, |
385 | void *pvCookie); |
386 | /* */ |
387 | /* The SLPAttrCallback type is the type of the callback function */ |
388 | /* parameter to SLPFindAttrs() function. */ |
389 | /* */ |
390 | /* The behavior of the callback differs depending on whether the */ |
391 | /* attribute request was by URL or by service type. If the */ |
392 | /* SLPFindAttrs() operation was originally called with a URL, the */ |
393 | /* callback is called once regardless of whether the handle was opened */ |
394 | /* asynchronously or synchronously. The pcAttrList parameter contains */ |
395 | /* the requested attributes as a comma separated list (or is empty if no */ |
396 | /* attributes matched the original tag list). */ |
397 | /* */ |
398 | /* If the SLPFindAttrs() operation was originally called with a service */ |
399 | /* type, the value of pcAttrList and calling behavior depend on whether */ |
400 | /* the handle was opened asynchronously or synchronously. If the handle */ |
401 | /* was opened asynchronously, the callback is called every time the API */ |
402 | /* library has results from a remote agent. The pcAttrList parameter */ |
403 | /* MAY be uncollated between calls. It contains a comma separated list */ |
404 | /* with the results from the agent that immediately returned results. */ |
405 | /* If the handle was opened synchronously, the results must be collated */ |
406 | /* from all returning agents and the callback is called once, with the */ |
407 | /* pcAttrList parameter set to the collated result. */ |
408 | /* */ |
409 | /* hSLP The SLPHandle used to initiate the operation. */ |
410 | /* */ |
411 | /* pcAttrList A character buffer containing a comma separated, null */ |
412 | /* terminated list of attribute id/value assignments, in SLP */ |
413 | /* wire format; i.e. "(attr-id=attr-value-list)". */ |
414 | /* */ |
415 | /* errCode An error code indicating if an error occurred during the */ |
416 | /* operation. The callback should check this error code */ |
417 | /* before processing the parameters. If the error code is */ |
418 | /* other than SLP_OK, then the API library may choose to */ |
419 | /* terminate the outstanding operation. */ |
420 | /* */ |
421 | /* pvCookie Memory passed down from the client code that called the */ |
422 | /* original API function, starting the operation. */ |
423 | /* May be NULL. */ |
424 | /* */ |
425 | /* Returns The client code should return SLP_TRUE if more data is */ |
426 | /* desired,otherwise return SLP_FALSE */ |
427 | /*=========================================================================*/ |
428 | |
429 | |
430 | /*=========================================================================*/ |
431 | SLPEXP SLPError SLPAPI SLPOpen(const char *pcLang, |
432 | SLPBoolean isAsync, |
433 | SLPHandle *phSLP); |
434 | /* */ |
435 | /* Returns a SLPHandle handle in the phSLP parameter for the language */ |
436 | /* locale passed in as the pcLang parameter. The client indicates if */ |
437 | /* operations on the handle are to be synchronous or asynchronous */ |
438 | /* through the isAsync parameter. The handle encapsulates the language */ |
439 | /* locale for SLP requests issued through the handle, and any other */ |
440 | /* resources required by the implementation. However, SLP properties */ |
441 | /* are not encapsulated by the handle; they are global. The return */ |
442 | /* value of the function is an SLPError code indicating the status of */ |
443 | /* the operation. Upon failure, the phSLP parameter is NULL. */ |
444 | /* */ |
445 | /* An SLPHandle can only be used for one SLP API operation at a time. */ |
446 | /* If the original operation was started asynchronously, any attempt to */ |
447 | /* start an additional operation on the handle while the original */ |
448 | /* operation is pending results in the return of an SLP_HANDLE_IN_USE */ |
449 | /* error from the API function. The SLPClose() API function terminates */ |
450 | /* any outstanding calls on the handle. If an implementation is unable */ |
451 | /* to support a asynchronous( resp. synchronous) operation, due to */ |
452 | /* memory constraints or lack of threading support, the */ |
453 | /* SLP_NOT_IMPLEMENTED flag may be returned when the isAsync flag is */ |
454 | /* SLP_TRUE (resp. SLP_FALSE). */ |
455 | /* */ |
456 | /* pcLang A pointer to an array of characters containing the RFC 1766 */ |
457 | /* Language Tag RFC 1766 for the natural language locale of */ |
458 | /* requests and registrations issued on the handle. Pass in NULL */ |
459 | /* or the empty string, "" to use the default locale */ |
460 | /* */ |
461 | /* isAsync An SLPBoolean indicating whether the SLPHandle should be opened*/ |
462 | /* for asynchronous operation or not. */ |
463 | /* */ |
464 | /* phSLP A pointer to an SLPHandle, in which the open SLPHandle is */ |
465 | /* returned. If an error occurs, the value upon return is NULL. */ |
466 | /* */ |
467 | /* Returns SLPError code */ |
468 | /*=========================================================================*/ |
469 | |
470 | |
471 | /*=========================================================================*/ |
472 | SLPEXP void SLPAPI SLPClose(SLPHandle hSLP); |
473 | /* */ |
474 | /* Frees all resources associated with the handle. If the handle was */ |
475 | /* invalid, the function returns silently. Any outstanding synchronous */ |
476 | /* or asynchronous operations are cancelled so their callback functions */ |
477 | /* will not be called any further. */ |
478 | /* */ |
479 | /* SLPHandle A SLPHandle handle returned from a call to SLPOpen(). */ |
480 | /*=========================================================================*/ |
481 | |
482 | |
483 | #ifndef MI_NOT_SUPPORTED |
484 | /*=========================================================================*/ |
485 | SLPEXP SLPError SLPAssociateIFList( SLPHandle hSLP, const char* McastIFList); |
486 | /* */ |
487 | /* Associates a list of interfaces McastIFList on which multicast needs to */ |
488 | /* be done with a particular SLPHandle hSLP. McastIFList is a comma */ |
489 | /* separated list of host interface IP addresses. */ |
490 | /* */ |
491 | /* hSLP The SLPHandle with which the interface list is to */ |
492 | /* be associated with. */ |
493 | /* */ |
494 | /* McastIFList A comma separated list of host interface IP */ |
495 | /* addresses on which multicast needs to be done. */ |
496 | /* */ |
497 | /* Returns SLPError code */ |
498 | /*=========================================================================*/ |
499 | #endif /* MI_NOT_SUPPORTED */ |
500 | |
501 | |
502 | #ifndef UNICAST_NOT_SUPPORTED |
503 | /*=========================================================================*/ |
504 | SLPEXP SLPError SLPAssociateIP( SLPHandle hSLP, const char* unicast_ip); |
505 | /* */ |
506 | /* Associates an IP address unicast_ip with a particular SLPHandle hSLP. */ |
507 | /* unicast_ip is the IP address of the SA/DA from which service is */ |
508 | /* requested. */ |
509 | /* */ |
510 | /* hSLP The SLPHandle with which the unicast_ip address is */ |
511 | /* to be associated with. */ |
512 | /* */ |
513 | /* unicast_ip IP address of the SA/DA from which service is */ |
514 | /* requested. */ |
515 | /* */ |
516 | /* Returns SLPError code */ |
517 | /*=========================================================================*/ |
518 | #endif |
519 | |
520 | |
521 | #define SLP_REG_FLAG_FRESH (1) |
522 | #define SLP_REG_FLAG_WATCH_PID (1 << 1) |
523 | |
524 | /*=========================================================================*/ |
525 | SLPEXP SLPError SLPAPI SLPReg(SLPHandle hSLP, |
526 | const char *pcSrvURL, |
527 | const unsigned short usLifetime, |
528 | const char *pcSrvType, |
529 | const char *pcAttrs, |
530 | SLPBoolean fresh, |
531 | SLPRegReport callback, |
532 | void *pvCookie); |
533 | /* */ |
534 | /* Registers the URL in pcSrvURL having the lifetime usLifetime with the */ |
535 | /* attribute list in pcAttrs. The pcAttrs list is a comma separated */ |
536 | /* list of attribute assignments in the wire format (including escaping */ |
537 | /* of reserved characters). The usLifetime parameter must be nonzero */ |
538 | /* and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is */ |
539 | /* SLP_TRUE, then the registration is new (the SLP protocol FRESH flag */ |
540 | /* is set) and the registration replaces any existing registrations. */ |
541 | /* The pcSrvType parameter is a service type name and can be included */ |
542 | /* for service URLs that are not in the service: scheme. If the URL is */ |
543 | /* in the service: scheme, the pcSrvType parameter is ignored. If the */ |
544 | /* fresh flag is SLP_FALSE, then an existing registration is updated. */ |
545 | /* Registrations and updates take place in the language locale of the */ |
546 | /* hSLP handle. */ |
547 | /* */ |
548 | /* hSLP The language specific SLPHandle on which to register the */ |
549 | /* advertisement. */ |
550 | /* */ |
551 | /* pcSrvURL The URL to register. May not be the empty string. May not */ |
552 | /* be NULL. Must conform to SLP Service URL syntax. */ |
553 | /* SLP_INVALID_REGISTRATION will be returned if it does not. */ |
554 | /* */ |
555 | /* usLifetime An unsigned short giving the life time of the service */ |
556 | /* advertisement, in seconds. The value must be an unsigned */ |
557 | /* integer less than or equal to SLP_LIFETIME_MAXIMUM and */ |
558 | /* greater than zero. If SLP_LIFETIME_MAXIMUM is used, the */ |
559 | /* registration will remain for the life of the calling */ |
560 | /* process. Also, OpenSLP, will not allow registrations to */ |
561 | /* be made with SLP_LIFETIME_MAXIMUM unless */ |
562 | /* SLP_REG_FLAG_WATCH_PID is also used */ |
563 | /* */ |
564 | /* pcSrvType This parameter is ALWAYS ignored since the SLP Service URL */ |
565 | /* syntax required for the pcSrvURL encapsulates the service */ |
566 | /* type. */ |
567 | /* */ |
568 | /* pcAttrs A comma separated list of attribute assignment expressions */ |
569 | /* for the attributes of the advertisement. Use empty string,*/ |
570 | /* "" for no attributes. */ |
571 | /* */ |
572 | /* fresh Use of non-fresh registrations is deprecated. SLP_TRUE */ |
573 | /* must be passed in for this parameter or SLP_BAD_PARAMETER */ |
574 | /* will be returned */ |
575 | /* */ |
576 | /* callback A SLPRegReport callback to report the operation completion */ |
577 | /* status. */ |
578 | /* */ |
579 | /* pvCookie Memory passed to the callback code from the client. May be*/ |
580 | /* NULL. */ |
581 | /* */ |
582 | /* Returns: If an error occurs in starting the operation, one of the */ |
583 | /* SLPError codes is returned. */ |
584 | /*=========================================================================*/ |
585 | |
586 | |
587 | /*=========================================================================*/ |
588 | SLPEXP SLPError SLPAPI SLPDereg(SLPHandle hSLP, |
589 | const char *pcSrvURL, |
590 | SLPRegReport callback, |
591 | void *pvCookie); |
592 | /* */ |
593 | /* Deregisters the advertisement for URL pcURL in all scopes where the */ |
594 | /* service is registered and all language locales. The deregistration */ |
595 | /* is not just confined to the locale of the SLPHandle, it is in all */ |
596 | /* locales. The API library is required to perform the operation in all */ |
597 | /* scopes obtained through configuration. */ |
598 | /* */ |
599 | /* hSLP The language specific SLPHandle to use for deregistering. */ |
600 | /* */ |
601 | /* pcSrvURL The SLP Service URL to deregister. May not be the empty */ |
602 | /* string. May not be NULL. Must conform to SLP Service URL */ |
603 | /* syntax or SLP_INVALID_REGISTRATION will be returned. */ |
604 | /* */ |
605 | /* callback A callback to report the operation completion status. */ |
606 | /* */ |
607 | /* pvCookie Memory passed to the callback code from the client. May be*/ |
608 | /* NULL. */ |
609 | /* */ |
610 | /* Returns: If an error occurs in starting the operation, one of the */ |
611 | /* SLPError codes is returned. */ |
612 | /*=========================================================================*/ |
613 | |
614 | |
615 | /*=========================================================================*/ |
616 | SLPEXP SLPError SLPAPI SLPDelAttrs(SLPHandle hSLP, |
617 | const char *pcSrvURL, |
618 | const char *pcAttrs, |
619 | SLPRegReport callback, |
620 | void *pvCookie); |
621 | /* */ |
622 | /* Delete the selected attributes in the locale of the SLPHandle. The */ |
623 | /* API library is required to perform the operation in all scopes */ |
624 | /* obtained through configuration. */ |
625 | /* */ |
626 | /* hSLP The language specific SLPHandle to use for deleting */ |
627 | /* attributes. */ |
628 | /* */ |
629 | /* pcSrvURL The SLP Service URL of the advertisement from which the */ |
630 | /* attributes should be deleted. May not be the empty string. */ |
631 | /* */ |
632 | /* pcAttrs A comma separated list of attribute ids for the attributes */ |
633 | /* to deregister. May not be the empty string. */ |
634 | /* */ |
635 | /* callback A callback to report the operation completion status. */ |
636 | /* */ |
637 | /* pvCookie Memory passed to the callback code from the client. May be*/ |
638 | /* NULL. */ |
639 | /* */ |
640 | /* Returns If an error occurs in starting the operation, one of the */ |
641 | /* SLPError codes is returned. */ |
642 | /*=========================================================================*/ |
643 | |
644 | |
645 | |
646 | /*=========================================================================*/ |
647 | SLPEXP SLPError SLPAPI SLPFindSrvTypes(SLPHandle hSLP, |
648 | const char *pcNamingAuthority, |
649 | const char *pcScopeList, |
650 | SLPSrvTypeCallback callback, |
651 | void *pvCookie); |
652 | /* */ |
653 | /* The SLPFindSrvType() function issues an SLP service type request for */ |
654 | /* service types in the scopes indicated by the pcScopeList. The */ |
655 | /* results are returned through the callback parameter. The service */ |
656 | /* types are independent of language locale, but only for services */ |
657 | /* registered in one of scopes and for the indicated naming authority. */ |
658 | /* */ |
659 | /* If the naming authority is "*", then results are returned for all */ |
660 | /* naming authorities. If the naming authority is the empty string, */ |
661 | /* i.e. "", then the default naming authority, "IANA", is used. "IANA" */ |
662 | /* is not a valid naming authority name, and it is a PARAMETER_BAD error */ |
663 | /* to include it explicitly. */ |
664 | /* */ |
665 | /* The service type names are returned with the naming authority intact. */ |
666 | /* If the naming authority is the default (i.e. empty string) then it */ |
667 | /* is omitted, as is the separating ".". Service type names from URLs */ |
668 | /* of the service: scheme are returned with the "service:" prefix */ |
669 | /* intact. See RFC 2609 for more information on the syntax of service */ |
670 | /* type names. */ |
671 | /* */ |
672 | /* hSLP The SLPHandle on which to search for types. */ |
673 | /* */ |
674 | /* pcNamingAuthority The naming authority to search. Use "*" for all */ |
675 | /* naming authorities and the empty string, "", for */ |
676 | /* the default naming authority. */ |
677 | /* */ |
678 | /* pcScopeList A pointer to a string containing comma separated */ |
679 | /* list of scope names to search for service types. */ |
680 | /* May not be the empty string, "". */ |
681 | /* */ |
682 | /* callback A callback function through which the results of */ |
683 | /* the operation are reported. */ |
684 | /* */ |
685 | /* pvCookie Memory passed to the callback code from the client.*/ |
686 | /* May be NULL. */ |
687 | /* */ |
688 | /* Returns If an error occurs in starting the operation, one */ |
689 | /* of the SLPError codes is returned. */ |
690 | /*=========================================================================*/ |
691 | |
692 | |
693 | /*=========================================================================*/ |
694 | SLPEXP SLPError SLPAPI SLPFindSrvs(SLPHandle hSLP, |
695 | const char *pcServiceType, |
696 | const char *pcScopeList, |
697 | const char *pcSearchFilter, |
698 | SLPSrvURLCallback callback, |
699 | void *pvCookie); |
700 | /* */ |
701 | /* Issue the query for services on the language specific SLPHandle and */ |
702 | /* return the results through the callback. The parameters determine */ |
703 | /* the results */ |
704 | /* */ |
705 | /* hSLP The language specific SLPHandle on which to search for */ |
706 | /* services. */ |
707 | /* */ |
708 | /* pcServiceType The Service Type String, including authority string if */ |
709 | /* any, for the request, such as can be discovered using */ |
710 | /* SLPSrvTypes(). This could be, for example */ |
711 | /* "service:printer:lpr" or "service:nfs". May not be */ |
712 | /* the empty string or NULL. */ |
713 | /* */ |
714 | /* */ |
715 | /* pcScopeList A pointer to a char containing comma separated list of */ |
716 | /* scope names. Pass in the NULL or the empty string "" */ |
717 | /* to find services in all the scopes the local host is */ |
718 | /* configured query. */ |
719 | /* */ |
720 | /* pcSearchFilter A query formulated of attribute pattern matching */ |
721 | /* expressions in the form of a LDAPv3 Search Filter. */ |
722 | /* If this filter is NULL or empty, i.e. "", all */ |
723 | /* services of the requested type in the specified scopes */ |
724 | /* are returned. */ |
725 | /* */ |
726 | /* callback A callback function through which the results of the */ |
727 | /* operation are reported. May not be NULL */ |
728 | /* */ |
729 | /* pvCookie Memory passed to the callback code from the client. */ |
730 | /* May be NULL. */ |
731 | /* */ |
732 | /* Returns: If an error occurs in starting the operation, one of */ |
733 | /* the SLPError codes is returned. */ |
734 | /* */ |
735 | /*=========================================================================*/ |
736 | |
737 | |
738 | |
739 | /*=========================================================================*/ |
740 | SLPEXP SLPError SLPAPI SLPFindAttrs(SLPHandle hSLP, |
741 | const char *pcURLOrServiceType, |
742 | const char *pcScopeList, |
743 | const char *pcAttrIds, |
744 | SLPAttrCallback callback, |
745 | void *pvCookie); |
746 | /* */ |
747 | /* This function returns service attributes matching the attribute ids */ |
748 | /* for the indicated service URL or service type. If pcURLOrServiceType */ |
749 | /* is a service URL, the attribute information returned is for that */ |
750 | /* particular advertisement in the language locale of the SLPHandle. */ |
751 | /* */ |
752 | /* If pcURLOrServiceType is a service type name (including naming */ |
753 | /* authority if any), then the attributes for all advertisements of that */ |
754 | /* service type are returned regardless of the language of registration. */ |
755 | /* Results are returned through the callback. */ |
756 | /* */ |
757 | /* The result is filtered with an SLP attribute request filter string */ |
758 | /* parameter, the syntax of which is described in RFC 2608. If the filter */ |
759 | /* string is the empty string, i.e. "", all attributes are returned. */ |
760 | /* */ |
761 | /* hSLP The language specific SLPHandle on which to search */ |
762 | /* for attributes. */ |
763 | /* */ |
764 | /* pcURLOrServiceType The service URL or service type. See RFC 2608 for */ |
765 | /* URL and service type syntax. May not be the empty */ |
766 | /* string. */ |
767 | /* */ |
768 | /* pcScopeList A pointer to a char containing a comma separated */ |
769 | /* list of scope names. Pass in NULL or the empty */ |
770 | /* string "" to find services in all the scopes the */ |
771 | /* local host is configured query. */ |
772 | /* */ |
773 | /* pcAttrIds A comma separated list of attribute ids to return. */ |
774 | /* Use NULL or the empty string, "", to indicate all */ |
775 | /* values. Wildcards are not currently supported */ |
776 | /* */ |
777 | /* callback A callback function through which the results of */ |
778 | /* the operation are reported. */ |
779 | /* */ |
780 | /* pvCookie Memory passed to the callback code from the client.*/ |
781 | /* May be NULL. */ |
782 | /* */ |
783 | /* Returns: If an error occurs in starting the operation, one */ |
784 | /* of the SLPError codes is returned. */ |
785 | /*=========================================================================*/ |
786 | |
787 | |
788 | |
789 | /*=========================================================================*/ |
790 | SLPEXP unsigned short SLPAPI SLPGetRefreshInterval(); |
791 | /* */ |
792 | /* Returns the maximum across all DAs of the min-refresh-interval */ |
793 | /* attribute. This value satisfies the advertised refresh interval */ |
794 | /* bounds for all DAs, and, if used by the SA, assures that no refresh */ |
795 | /* registration will be rejected. If no DA advertises a min-refresh- */ |
796 | /* interval attribute, a value of 0 is returned. */ |
797 | /* */ |
798 | /* Returns: If no error, the maximum refresh interval value allowed by all */ |
799 | /* DAs (a positive integer). If no DA advertises a */ |
800 | /* min-refresh-interval attribute, returns 0. If an error occurs,*/ |
801 | /* returns an SLP error code. */ |
802 | /*=========================================================================*/ |
803 | |
804 | |
805 | |
806 | /*=========================================================================*/ |
807 | SLPEXP SLPError SLPAPI SLPFindScopes(SLPHandle hSLP, |
808 | char** ppcScopeList); |
809 | /* */ |
810 | /* Sets ppcScopeList parameter to a pointer to a comma separated list */ |
811 | /* including all available scope values. The list of scopes comes from */ |
812 | /* a variety of sources: the configuration file's net.slp.useScopes */ |
813 | /* property, unicast to DAs on the net.slp.DAAddresses property, DHCP, */ |
814 | /* or through the DA discovery process. If there is any order to the */ |
815 | /* scopes, preferred scopes are listed before less desirable scopes. */ |
816 | /* There is always at least one name in the list, the default scope, */ |
817 | /* "DEFAULT". */ |
818 | /* */ |
819 | /* hSLP The SLPHandle on which to search for scopes. */ |
820 | /* */ |
821 | /* ppcScopeList A pointer to char pointer into which the buffer pointer is */ |
822 | /* placed upon return. The buffer is null terminated. The */ |
823 | /* memory should be freed by calling SLPFree(). */ |
824 | /* */ |
825 | /* Returns: If no error occurs, returns SLP_OK, otherwise, the a */ |
826 | /* ppropriate error code. */ |
827 | /*=========================================================================*/ |
828 | |
829 | |
830 | |
831 | /*=========================================================================*/ |
832 | SLPEXP SLPError SLPAPI SLPParseSrvURL(const char *pcSrvURL, |
833 | SLPSrvURL** ppSrvURL); |
834 | /* */ |
835 | /* Parses the URL passed in as the argument into a service URL structure */ |
836 | /* and returns it in the ppSrvURL pointer. If a parse error occurs, */ |
837 | /* returns SLP_PARSE_ERROR. The structure returned in ppSrvURL should be */ |
838 | /* freed with SLPFreeURL(). If the URL has no service part, the */ |
839 | /* s_pcSrvPart string is the empty string, "", i.e. not NULL. If */ |
840 | /* pcSrvURL is not a service: URL, then the s_pcSrvType field in the */ |
841 | /* returned data structure is the URL's scheme, which might not be the */ |
842 | /* same as the service type under which the URL was registered. If the */ |
843 | /* transport is IP, the s_pcTransport field is the empty string. If the */ |
844 | /* transport is not IP or there is no port number, the s_iPort field is */ |
845 | /* zero. */ |
846 | /* */ |
847 | /* pcSrvURL A pointer to a character buffer containing the null terminated */ |
848 | /* URL string to parse. */ |
849 | /* */ |
850 | /* ppSrvURL A pointer to a pointer for the SLPSrvURL structure to receive */ |
851 | /* the parsed URL. The memory should be freed by a call to */ |
852 | /* SLPFree() when no longer needed. */ |
853 | /* */ |
854 | /* Returns: If no error occurs, the return value is SLP_OK. Otherwise, the */ |
855 | /* appropriate error code is returned. */ |
856 | /*=========================================================================*/ |
857 | |
858 | |
859 | |
860 | /*=========================================================================*/ |
861 | SLPEXP SLPError SLPAPI SLPEscape(const char* pcInbuf, |
862 | char** ppcOutBuf, |
863 | SLPBoolean isTag); |
864 | /* */ |
865 | /* Process the input string in pcInbuf and escape any SLP reserved */ |
866 | /* characters. If the isTag parameter is SLPTrue, then look for bad tag */ |
867 | /* characters and signal an error if any are found by returning the */ |
868 | /* SLP_PARSE_ERROR code. The results are put into a buffer allocated by */ |
869 | /* the API library and returned in the ppcOutBuf parameter. This buffer */ |
870 | /* should be deallocated using SLPFree() when the memory is no longer */ |
871 | /* needed. */ |
872 | /* */ |
873 | /* pcInbuf Pointer to he input buffer to process for escape */ |
874 | /* characters. */ |
875 | /* */ |
876 | /* ppcOutBuf Pointer to a pointer for the output buffer with the SLP */ |
877 | /* reserved characters escaped. Must be freed using */ |
878 | /* SLPFree()when the memory is no longer needed. */ |
879 | /* */ |
880 | /* isTag When true, the input buffer is checked for bad tag */ |
881 | /* characters. */ |
882 | /* */ |
883 | /* Returns: Return SLP_PARSE_ERROR if any characters are bad tag */ |
884 | /* characters and the isTag flag is true, otherwise SLP_OK, */ |
885 | /* or the appropriate error code if another error occurs. */ |
886 | /*=========================================================================*/ |
887 | |
888 | |
889 | |
890 | /*=========================================================================*/ |
891 | SLPEXP SLPError SLPAPI SLPUnescape(const char* pcInbuf, |
892 | char** ppcOutBuf, |
893 | SLPBoolean isTag); |
894 | /* */ |
895 | /* Process the input string in pcInbuf and unescape any SLP reserved */ |
896 | /* characters. If the isTag parameter is SLPTrue, then look for bad tag */ |
897 | /* characters and signal an error if any are found with the */ |
898 | /* SLP_PARSE_ERROR code. No transformation is performed if the input */ |
899 | /* string is an opaque. The results are put into a buffer allocated by */ |
900 | /* the API library and returned in the ppcOutBuf parameter. This buffer */ |
901 | /* should be deallocated using SLPFree() when the memory is no longer */ |
902 | /* needed. */ |
903 | /* */ |
904 | /* pcInbuf Pointer to he input buffer to process for escape */ |
905 | /* characters. */ |
906 | /* */ |
907 | /* ppcOutBuf Pointer to a pointer for the output buffer with the SLP */ |
908 | /* reserved characters escaped. Must be freed using */ |
909 | /* SLPFree() when the memory is no longer needed. */ |
910 | /* */ |
911 | /* isTag When true, the input buffer is checked for bad tag */ |
912 | /* characters. */ |
913 | /* */ |
914 | /* Returns: Return SLP_PARSE_ERROR if any characters are bad tag */ |
915 | /* characters and the isTag flag is true, otherwise SLP_OK, */ |
916 | /* or the appropriate error code if another error occurs. */ |
917 | /*=========================================================================*/ |
918 | |
919 | |
920 | /*=========================================================================*/ |
921 | SLPEXP void SLPAPI SLPFree(void* pvMem); |
922 | /* */ |
923 | /* Frees memory returned from SLPParseSrvURL(), SLPFindScopes(), */ |
924 | /* SLPEscape(), and SLPUnescape(). */ |
925 | /* */ |
926 | /* pvMem A pointer to the storage allocated by the SLPParseSrvURL(), */ |
927 | /* SLPEscape(), SLPUnescape(), or SLPFindScopes() function. */ |
928 | /* Ignored if NULL. */ |
929 | /*=========================================================================*/ |
930 | |
931 | |
932 | /*=========================================================================*/ |
933 | SLPEXP const char* SLPAPI SLPGetProperty(const char* pcName); |
934 | /* */ |
935 | /* Returns the value of the corresponding SLP property name. The returned */ |
936 | /* string is owned by the library and MUST NOT be freed. */ |
937 | /* */ |
938 | /* pcName Null terminated string with the property name, from */ |
939 | /* Section 2.1 of RFC 2614. */ |
940 | /* */ |
941 | /* Returns: If no error, returns a pointer to a character buffer containing*/ |
942 | /* the property value. If the property was not set, returns the */ |
943 | /* default value. If an error occurs, returns NULL. The returned */ |
944 | /* string MUST NOT be freed. */ |
945 | /*=========================================================================*/ |
946 | |
947 | |
948 | /*=========================================================================*/ |
949 | SLPEXP void SLPAPI SLPSetProperty(const char *pcName, |
950 | const char *pcValue); |
951 | /* */ |
952 | /* Sets the value of the SLP property to the new value. The pcValue */ |
953 | /* parameter should be the property value as a string. */ |
954 | /* */ |
955 | /* pcName Null terminated string with the property name, from Section */ |
956 | /* 2.1. of RFC 2614. */ |
957 | /* */ |
958 | /* pcValue Null terminated string with the property value, in UTF-8 */ |
959 | /* character encoding. */ |
960 | /*=========================================================================*/ |
961 | |
962 | |
963 | /*=========================================================================*/ |
964 | SLPEXP SLPError SLPAPI SLPParseAttrs(const char* pcAttrList, |
965 | const char *pcAttrId, |
966 | char** ppcAttrVal); |
967 | /* */ |
968 | /* Used to get individual attribute values from an attribute string that */ |
969 | /* is passed to the SLPAttrCallback */ |
970 | /* */ |
971 | /* pcAttrList (IN) A character buffer containing a comma separated, null */ |
972 | /* terminated list of attribute id/value assignments, in */ |
973 | /* SLP wire format; i.e. "(attr-id=attr-value-list)" */ |
974 | /* */ |
975 | /* pcAttrId (IN) The string indicating which attribute value to return. */ |
976 | /* MUST not be null. MUST not be the empty string (""). */ |
977 | /* */ |
978 | /* ppcAttrVal (OUT) A pointer to a pointer to the buffer to receive */ |
979 | /* attribute value. The memory should be freed by a call */ |
980 | /* to SLPFree() when no longer needed. */ |
981 | /* */ |
982 | /* Returns: Returns SLP_PARSE_ERROR if an attribute of the specified id */ |
983 | /* was not found otherwise SLP_OK */ |
984 | /*=========================================================================*/ |
985 | |
986 | #if(defined __cplusplus) |
987 | } |
988 | #endif |
989 | |
990 | #endif /* (!defined SLP_H_INCLUDED) */ |
991 |
Warning: That file was not part of the compilation database. It may have many parsing errors.