1 /*------------------------------------------------------------------------- 2 * Copyright (C) 2000 Caldera Systems, Inc 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * Neither the name of Caldera Systems nor the names of its 17 * contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 * `AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CALDERA 24 * SYSTEMS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 *-------------------------------------------------------------------------*/ 32 33 /** @mainpage OpenSLP - An API for Service Location 34 * 35 * The OpenSLP project was started by Caldera in an attempt to provide a 36 * clean solid implementation of RFC 2614 "An API for Service Location". 37 * This API is based on RFC 2608 "Service Location Protocol, Version 2". 38 * 39 * Since its inception, OpenSLP has been compiled and used effectively on 40 * many platforms, including: most Linux distributions, Solaris, Windows, 41 * HPUX, Mac Classic and OSX, BeOS, FreeBSD, and many others. The primary 42 * reason for this prolification is that there is no standardized, secure, 43 * bandwidth-efficient, robust, service advertising protocol available. 44 * 45 * In the last few years, other advertising protocols have been invented. 46 * Some of them have become quite popular. Apple's Bonjour, for instance, 47 * is really doing well in the zero-conf world. Directories based on LDAP 48 * such as Novell's eDirectory, OpenLDAP, and iPlanet have been configured 49 * to provide some service location infrastructure. The fact remains however, 50 * that no significant solution has ever been created to solve the problems 51 * that SLP was designed to solve. 52 * 53 * The current version of OpenSLP supports SLPv2 security features, 54 * asynchronous multi-threaded execution, IP version 6 support, and many 55 * other features that were missing or not entirely implemented in earlier 56 * releases of the project. 57 * 58 * -- John Calcote, Sr. Software Engineer, Novell, Inc. (jcalcote@novell.com) 59 */ 60 61 /** Main header file for the SLP API exactly as described by RFC 2614. 62 * 63 * This is the only file that needs to be included in order make all 64 * SLP API declarations. 65 * 66 * @file slp.h 67 * @author Matthew Peterson, John Calcote (jcalcote@novell.com) 68 * @attention Please submit patches to http://www.openslp.org 69 * @ingroup SlpUAInterface 70 */ 71 72 #ifndef SLP_H_INCLUDED 73 #define SLP_H_INCLUDED 74 75 /*!@defgroup SlpUAInterface OpenSLP API 76 * @ingroup LibSLPCode 77 * @{ 78 */ 79 80 #ifdef __cplusplus 81 extern "C" 82 { 83 #endif 84 85 /** Public interface attributes 86 * 87 * Note that for Win32 MSVC builds, you must define LIBSLP_STATIC in 88 * your compilation environment if you intend to link against the static 89 * version of the Win32 SLP library. The default action is to link against 90 * the dynamic import library. This macro changes the signature of the 91 * library imports in your code, so not using it properly will cause 92 * "missing symbol" linker errors. 93 */ 94 #if defined(_WIN32) 95 # if defined(_MSC_VER) 96 # if defined(LIBSLP_STATIC) /* User must define to link statically. */ 97 # define SLPEXP 98 # elif defined(LIBSLP_EXPORTS) 99 # define SLPEXP __declspec(dllexport) 100 # else 101 # define SLPEXP __declspec(dllimport) 102 # endif 103 # else /* ! _MSC_VER */ 104 # define SLPEXP 105 # endif 106 # define SLPCALLBACK __cdecl 107 # define SLPAPI __cdecl 108 #else /* ! _WIN32 */ 109 # define SLPCALLBACK 110 # define SLPEXP 111 # define SLPAPI 112 #endif 113 114 /** URL Lifetimes (4.1.1) NOTE: Section numbers refer to [RFC 2614]. 115 * 116 * The SLPURLLifetime enum type contains URL lifetime values, in 117 * seconds, that are frequently used. SLP_LIFETIME_DEFAULT is 3 hours, 118 * while SLP_LIFETIME_MAXIMUM is about 18 hours and corresponds to the 119 * maximum size of the lifetime field in SLP messages. 120 */ 121 typedef enum { 122 SLP_LIFETIME_DEFAULT = 10800, /*!< 3 hours */ 123 SLP_LIFETIME_MAXIMUM = 65535 /*!< 18.2 hours */ 124 } SLPURLLifetime; 125 126 /** Error Semantics - Error type (3.9) 127 */ 128 typedef enum { 129 130 SLP_LAST_CALL = 1, 131 /*!< Passed to callback functions when the API library has no more data 132 * for them and therefore no further calls will be made to the callback 133 * on the currently outstanding operation. The callback can use this to 134 * signal the main body of the client code that no more data will be 135 * forthcoming on the operation, so that the main body of the client code 136 * can break out of data collection loops. On the last call of a callback 137 * during both a synchronous and asynchronous call, the error code 138 * parameter has value SLP_LAST_CALL, and the other parameters are all 139 * NULL. If no results are returned by an API operation, then only one 140 * call is made, with the error parameter set to SLP_LAST_CALL. 141 */ 142 143 SLP_OK = 0, 144 /*!< Indicates that the no error occurred during the operation. */ 145 146 SLP_LANGUAGE_NOT_SUPPORTED = -1, 147 /*!< No DA or SA has service advertisement or attribute information in 148 * the language requested, but at least one DA or SA indicated, via the 149 * LANGUAGE_NOT_SUPPORTED error code, that it might have information for 150 * that service in another language. 151 */ 152 153 SLP_PARSE_ERROR = -2, 154 /*!< The SLP message was rejected by a remote SLP agent. The API returns 155 * this error only when no information was retrieved, and at least one SA 156 * or DA indicated a protocol error. The data supplied through the API 157 * may be malformed or a may have been damaged in transit. 158 */ 159 160 SLP_INVALID_REGISTRATION = -3, 161 /*!< The API may return this error if an attempt to register a service 162 * was rejected by all DAs because of a malformed URL or attributes. SLP 163 * does not return the error if at least one DA accepted the registration. 164 */ 165 166 SLP_SCOPE_NOT_SUPPORTED = -4, 167 /*!< The API returns this error if the SA has been configured with 168 * net.slp.useScopes value-list of scopes and the SA request did not 169 * specify one or more of these allowable scopes, and no others. It may 170 * be returned by a DA or SA if the scope included in a request is not 171 * supported by the DA or SA. 172 */ 173 174 SLP_AUTHENTICATION_ABSENT = -6, 175 /*!< If the SLP framework supports authentication, this error arises 176 * when the UA or SA failed to send an authenticator for requests or 177 * registrations in a protected scope. 178 */ 179 180 SLP_AUTHENTICATION_FAILED = -7, 181 /*!< If the SLP framework supports authentication, this error arises when 182 * a authentication on an SLP message failed. 183 */ 184 185 SLP_INVALID_UPDATE = -13, 186 /*!< An update for a non-existing registration was issued, or the update 187 * includes a service type or scope different than that in the initial 188 * registration, etc. 189 */ 190 191 SLP_REFRESH_REJECTED = -15, 192 /*!< The SA attempted to refresh a registration more frequently than 193 * the minimum refresh interval. The SA should call the appropriate API 194 * function to obtain the minimum refresh interval to use. 195 */ 196 197 SLP_NOT_IMPLEMENTED = -17, 198 /*!< If an unimplemented feature is used, this error is returned. */ 199 200 SLP_BUFFER_OVERFLOW = -18, 201 /*!< An outgoing request overflowed the maximum network MTU size. The 202 * request should be reduced in size or broken into pieces and tried 203 * again. 204 */ 205 206 SLP_NETWORK_TIMED_OUT = -19, 207 /*!< When no reply can be obtained in the time specified by the configured 208 * timeout interval for a unicast request, this error is returned. 209 */ 210 211 SLP_NETWORK_INIT_FAILED = -20, 212 /*!< If the network cannot initialize properly, this error is returned. */ 213 214 SLP_MEMORY_ALLOC_FAILED = -21, 215 /*!< If the API fails to allocate memory, the operation is aborted and 216 * returns this. 217 */ 218 219 SLP_PARAMETER_BAD = -22, 220 /*!< If a parameter passed into an interface is bad, this error is 221 * returned. 222 */ 223 224 SLP_NETWORK_ERROR = -23, 225 /*!< The failure of networking during normal operations causes this error 226 * to be returned. 227 */ 228 229 SLP_INTERNAL_SYSTEM_ERROR = -24, 230 /*!< A basic failure of the API causes this error to be returned. This 231 * occurs when a system call or library fails. The operation could not 232 * recover. 233 */ 234 235 SLP_HANDLE_IN_USE = -25, 236 /*!< In the C API, callback functions are not permitted to recursively 237 * call into the API on the same SLPHandle, either directly or indirectly. 238 * If an attempt is made to do so, this error is returned from the called 239 * API function. 240 */ 241 242 SLP_TYPE_ERROR = -26 243 /*!< If the API supports type checking of registrations against service 244 * type templates, this error can arise if the attributes in a 245 * registration do not match the service type template for the service. 246 */ 247 248 } SLPError; 249 250 /** SLPBoolean (4.1.3) 251 * 252 * The SLPBoolean enum is used as a boolean flag. 253 */ 254 typedef enum { 255 SLP_FALSE = 0, 256 SLP_TRUE = 1 257 } SLPBoolean; 258 259 /** SLPSrvURL (4.2.1) 260 * 261 * The SLPSrvURL structure is filled in by the SLPParseSrvURL() function 262 * with information parsed from a character buffer containing a service 263 * URL. The fields correspond to different parts of the URL. Note that the 264 * structure is in conformance with the standard Berkeley sockets struct 265 * servent, with the exception that the pointer to an array of characters 266 * for aliases (s_aliases field) is replaced by the pointer to host name 267 * (s_pcHost field). 268 */ 269 typedef struct srvurl { 270 271 char * s_pcSrvType; 272 /*!< A pointer to a character string containing the service type name, 273 * including naming authority. The service type name includes the 274 * "service:" if the URL is of the "service:" scheme. [RFC 2608] 275 */ 276 277 char * s_pcHost; 278 /*!< A pointer to a character string containing the host identification 279 * information. 280 */ 281 282 int s_iPort; 283 /*!< The port number, or zero if none. The port is only available if the 284 * transport is IP. 285 */ 286 287 char * s_pcNetFamily; 288 /*!< A pointer to a character string containing the network address 289 * family identifier. Possible values are "ipx" for the IPX family, "at" 290 * for the Appletalk family, and "" (i.e. the empty string) for the IP 291 * address family. OpenSLP extends the RFC here to add "v6" for IPv6 292 * addresses (since "" indicates ip). 293 */ 294 295 char * s_pcSrvPart; 296 /*!< The remainder of the URL, after the host identification. */ 297 298 } SLPSrvURL; 299 300 /** SLPHandle (4.2.2) 301 * 302 * The SLPHandle type is returned by SLPOpen() and is a parameter to all 303 * SLP functions. It serves as a handle for all resources allocated on 304 * behalf of the process by the SLP library. The type is opaque, since 305 * the exact nature differs depending on the implementation. 306 */ 307 typedef void * SLPHandle; 308 309 /** SLPRegReport (4.3.1) 310 * 311 * The SLPRegReport callback type is the type of the callback function 312 * to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. 313 * 314 * @param[in] hSLP - The SLPHandle used to initiate the operation. 315 * 316 * @param[in] errCode - An error code indicating if an error occurred 317 * during the operation. 318 * 319 * @param[in] pvCookie - Memory passed down from the client code that 320 * called the original API function, starting the operation. May be 321 * NULL. 322 */ 323 typedef void SLPCALLBACK SLPRegReport( 324 SLPHandle hSLP, 325 SLPError errCode, 326 void * pvCookie); 327 328 /** SLPSrvTypeCallback (4.3.2) 329 * 330 * The SLPSrvTypeCallback type is the type of the callback function 331 * parameter to SLPFindSrvTypes() function. If the hSLP handle 332 * parameter was opened asynchronously, the results returned through the 333 * callback MAY be uncollated. If the hSLP handle parameter was opened 334 * synchronously, then the returned results must be collated and 335 * duplicates eliminated. 336 * 337 * @param[in] hSLP - The SLPHandle used to initiate the operation. 338 * 339 * @param[in] pcSrvTypes - A character buffer containing a comma 340 * separated, null terminated list of service types. 341 * 342 * @param[in] errCode - An error code indicating if an error occurred 343 * during the operation. The callback should check this error code 344 * before processing the parameters. If the error code is other than 345 * SLP_OK, then the API library may choose to terminate the outstanding 346 * operation. 347 * 348 * @param[in] pvCookie - Memory passed down from the client code that 349 * called the original API function, starting the operation. May be 350 * NULL. 351 * 352 * @return The client code should return SLP_TRUE if more data is 353 * desired, otherwise SLP_FALSE. 354 */ 355 typedef SLPBoolean SLPCALLBACK SLPSrvTypeCallback( 356 SLPHandle hSLP, 357 const char * pcSrvTypes, 358 SLPError errCode, 359 void * pvCookie); 360 361 /** SLPSrvURLCallback (4.3.3) 362 * 363 * The SLPSrvURLCallback type is the type of the callback function 364 * parameter to SLPFindSrvs() function. If the hSLP handle parameter 365 * was opened asynchronously, the results returned through the callback 366 * MAY be uncollated. If the hSLP handle parameter was opened 367 * synchronously, then the returned results must be collated and 368 * duplicates eliminated. 369 * 370 * @param[in] hSLP - The SLPHandle used to initiate the operation. 371 * 372 * @param[in] pcSrvURL - A character buffer containing the returned 373 * service URL. May be NULL if errCode not SLP_OK. 374 * 375 * @param[in] sLifetime - An unsigned short giving the life time of the 376 * service advertisement, in seconds. The value must be an unsigned 377 * integer less than or equal to SLP_LIFETIME_MAXIMUM. 378 * 379 * @param[in] errCode - An error code indicating if an error occurred 380 * during the operation. The callback should check this error code 381 * before processing the parameters. If the error code is other than 382 * SLP_OK, then the API library may choose to terminate the outstanding 383 * operation. SLP_LAST_CALL is returned when no more services are 384 * available and the callback will not be called again. 385 * 386 * @param[in] pvCookie - Memory passed down from the client code that 387 * called the original API function, starting the operation. May be 388 * NULL. 389 * 390 * @return The client code should return SLP_TRUE if more data is 391 * desired, otherwise SLP_FALSE. 392 */ 393 typedef SLPBoolean SLPCALLBACK SLPSrvURLCallback( 394 SLPHandle hSLP, 395 const char * pcSrvURL, 396 unsigned short sLifetime, 397 SLPError errCode, 398 void * pvCookie); 399 400 /** SLPAttrCallback (4.3.4) 401 * 402 * The SLPAttrCallback type is the type of the callback function 403 * parameter to SLPFindAttrs() function. 404 * 405 * @par 406 * The behavior of the callback differs depending on whether the 407 * attribute request was by URL or by service type. If the 408 * SLPFindAttrs() operation was originally called with a URL, the 409 * callback is called once regardless of whether the handle was opened 410 * asynchronously or synchronously. The pcAttrList parameter contains 411 * the requested attributes as a comma separated list (or is empty if no 412 * attributes matched the original tag list). 413 * 414 * @par 415 * If the SLPFindAttrs() operation was originally called with a service 416 * type, the value of pcAttrList and calling behavior depend on whether 417 * the handle was opened asynchronously or synchronously. If the handle 418 * was opened asynchronously, the callback is called every time the API 419 * library has results from a remote agent. The pcAttrList parameter 420 * MAY be uncollated between calls. It contains a comma separated list 421 * with the results from the agent that immediately returned results. 422 * If the handle was opened synchronously, the results must be collated 423 * from all returning agents and the callback is called once, with the 424 * pcAttrList parameter set to the collated result. 425 * 426 * @param[in] hSLP - The SLPHandle used to initiate the operation. 427 * 428 * @param[in] pcAttrList - A character buffer containing a comma 429 * separated, null terminated list of attribute id/value assignments, 430 * in SLP wire format; i.e. "(attr-id=attr-value-list)" [RFC 2608]. 431 * 432 * @param[in] errCode - An error code indicating if an error occurred 433 * during the operation. The callback should check this error code 434 * before processing the parameters. If the error code is other than 435 * SLP_OK, then the API library may choose to terminate the 436 * outstanding operation. 437 * 438 * @param[in] pvCookie - Memory passed down from the client code that 439 * called the original API function, starting the operation. May be 440 * NULL. 441 * 442 * @return The client code should return SLP_TRUE if more data is 443 * desired, otherwise SLP_FALSE. 444 */ 445 typedef SLPBoolean SLPCALLBACK SLPAttrCallback( 446 SLPHandle hSLP, 447 const char * pcAttrList, 448 SLPError errCode, 449 void * pvCookie); 450 451 /*========================================================================= 452 * SLPOpen (4.4.1) 453 */ 454 SLPEXP SLPError SLPAPI SLPOpen( 455 const char * pcLang, 456 SLPBoolean isAsync, 457 SLPHandle * phSLP); 458 459 /*========================================================================= 460 * SLPClose (4.4.2) 461 */ 462 SLPEXP void SLPAPI SLPClose(SLPHandle hSLP); 463 464 /*========================================================================= 465 * SLPReg (4.5.1) 466 */ 467 SLPEXP SLPError SLPAPI SLPReg( 468 SLPHandle hSLP, 469 const char * pcSrvURL, 470 unsigned short usLifetime, 471 const char * pcSrvType, 472 const char * pcAttrs, 473 SLPBoolean fresh, 474 SLPRegReport callback, 475 void * pvCookie); 476 477 /*========================================================================= 478 * SLPDereg (4.5.2) 479 */ 480 SLPEXP SLPError SLPAPI SLPDereg( 481 SLPHandle hSLP, 482 const char * pcSrvURL, 483 SLPRegReport callback, 484 void * pvCookie); 485 486 /*========================================================================= 487 * SLPDelAttrs (4.5.3) 488 */ 489 SLPEXP SLPError SLPAPI SLPDelAttrs( 490 SLPHandle hSLP, 491 const char * pcURL, 492 const char * pcAttrs, 493 SLPRegReport callback, 494 void * pvCookie); 495 496 /*========================================================================= 497 * SLPFindSrvTypes (4.5.4) 498 */ 499 SLPEXP SLPError SLPAPI SLPFindSrvTypes( 500 SLPHandle hSLP, 501 const char * pcNamingAuthority, 502 const char * pcScopeList, 503 SLPSrvTypeCallback callback, 504 void * pvCookie); 505 506 /*========================================================================= 507 * SLPFindSrvs (4.5.5) 508 */ 509 SLPEXP SLPError SLPAPI SLPFindSrvs( 510 SLPHandle hSLP, 511 const char * pcServiceType, 512 const char * pcScopeList, 513 const char * pcSearchFilter, 514 SLPSrvURLCallback callback, 515 void * pvCookie); 516 517 /*========================================================================= 518 * SLPFindAttrs (4.5.6) 519 */ 520 SLPEXP SLPError SLPAPI SLPFindAttrs( 521 SLPHandle hSLP, 522 const char * pcURLOrServiceType, 523 const char * pcScopeList, 524 const char * pcAttrIds, 525 SLPAttrCallback callback, 526 void * pvCookie); 527 528 /*========================================================================= 529 * SLPGetRefreshInterval (4.6.1) 530 */ 531 SLPEXP unsigned short SLPAPI SLPGetRefreshInterval(void); 532 533 /*========================================================================= 534 * SLPFindScopes (4.6.2) 535 */ 536 SLPEXP SLPError SLPAPI SLPFindScopes( 537 SLPHandle hSLP, 538 char ** ppcScopeList); 539 540 /*========================================================================= 541 * SLPParseSrvURL (4.6.3) 542 */ 543 SLPEXP SLPError SLPAPI SLPParseSrvURL( 544 const char * pcSrvURL, 545 SLPSrvURL ** ppSrvURL); 546 547 /*========================================================================= 548 * SLPEscape (4.6.4) 549 */ 550 SLPEXP SLPError SLPAPI SLPEscape( 551 const char * pcInbuf, 552 char ** ppcOutBuf, 553 SLPBoolean isTag); 554 555 /*========================================================================= 556 * SLPUnescape (4.6.5) 557 */ 558 SLPEXP SLPError SLPAPI SLPUnescape( 559 const char * pcInbuf, 560 char ** ppcOutBuf, 561 SLPBoolean isTag); 562 563 /*========================================================================= 564 * SLPFree (4.6.6) 565 */ 566 SLPEXP void SLPAPI SLPFree(void * pvMem); 567 568 /*========================================================================= 569 * SLPGetProperty (4.6.7) 570 */ 571 SLPEXP const char * SLPAPI SLPGetProperty(const char * pcName); 572 573 /*========================================================================= 574 * SLPSetProperty (4.6.8) - only partially implemented - can successfully 575 * be called as long as SLPGetProperty has not yet been called. 576 */ 577 SLPEXP void SLPAPI SLPSetProperty( 578 const char * pcName, 579 const char * pcValue); 580 581 /*========================================================================= 582 * SLPSetAppPropertyFile (post RFC 2614) 583 */ 584 SLPEXP SLPError SLPAPI SLPSetAppPropertyFile( 585 const char * pathname); 586 587 /*========================================================================= 588 * SLPParseAttrs (post RFC 2614) 589 */ 590 SLPEXP SLPError SLPAPI SLPParseAttrs( 591 const char * pcAttrList, 592 const char * pcAttrId, 593 char ** ppcAttrVal); 594 595 /*========================================================================= 596 * SLPAssociateIFList (post RFC 2614) 597 */ 598 SLPEXP SLPError SLPAPI SLPAssociateIFList( 599 SLPHandle hSLP, 600 const char * McastIFList); 601 602 /*========================================================================= 603 * SLPAssociateIP (post RFC 2614) 604 */ 605 SLPEXP SLPError SLPAPI SLPAssociateIP( 606 SLPHandle hSLP, 607 const char * unicast_ip); 608 609 #if __cplusplus 610 } 611 #endif 612 613 /*! @} */ 614 615 #endif /* SLP_H_INCLUDED */ 616 617 /*=========================================================================*/ 618