1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright (c) 1999 by Sun Microsystems, Inc. 24 * All rights reserved. 25 */ 26 27 #ifndef _SLP_H 28 #define _SLP_H 29 30 /* 31 * This file contains definitions for the Service Location Protocol 32 * C API bindings. More detailed descriptions can be found in the 33 * slp_api(3n) man page. 34 */ 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /* 41 * The SLPURLLifetime enum contains URL lifetime values, in seconds, 42 * that are frequently used. If a service is registered with a lifetime 43 * of SLP_LIFETIME_MAXIMUM, the registration will be effectively 44 * permanent, never aging out as long as the SA process is alive. 45 */ 46 typedef enum { 47 SLP_LIFETIME_DEFAULT = 10800, 48 SLP_LIFETIME_MAXIMUM = 65535 49 } SLPURLLifetime; 50 51 /* 52 * The SLPBoolean enum is used as a boolean flag. 53 */ 54 typedef enum { 55 SLP_FALSE = 0, 56 SLP_TRUE = 1 57 } SLPBoolean; 58 59 /* 60 * The SLPSrvURL structure is filled in by the SLPParseSrvURL() function 61 * with information parsed from a character buffer containing URL. 62 * The fields correspond to different parts of the URL. Note that 63 * the structure is conformant with the standard Berkeley sockets 64 * struct servent, with the exception that the pointer to an array of 65 * characters for aliases (s_aliases field) is replaced by the pointer 66 * to host name (s_pcHost field). 67 */ 68 typedef struct srvurl { 69 char *s_pcSrvType; /* service type name */ 70 char *s_pcHost; /* host identification information */ 71 int s_iPort; /* port number, or zero if none */ 72 char *s_pcNetFamily; /* network address family identifier */ 73 char *s_pcSrvPart; /* remainder of the URL */ 74 } SLPSrvURL; 75 76 /* 77 * The SLPHandle type is returned by SLPOpen() and is a parameter to all 78 * SLP functions. It serves as a handle for all resources allocated on 79 * behalf of the process by the SLP library. The type is opaque, since 80 * the exact nature differs depending on the implementation. 81 */ 82 typedef void* SLPHandle; 83 84 /* 85 * The SLPError enum contains error codes that are returned from API 86 * functions. 87 */ 88 typedef enum { 89 SLP_LAST_CALL = 1, 90 SLP_OK = 0, 91 SLP_LANGUAGE_NOT_SUPPORTED = -1, 92 SLP_PARSE_ERROR = -2, 93 SLP_INVALID_REGISTRATION = -3, 94 SLP_SCOPE_NOT_SUPPORTED = -4, 95 SLP_AUTHENTICATION_ABSENT = -6, 96 SLP_AUTHENTICATION_FAILED = -7, 97 SLP_INVALID_UPDATE = -13, 98 SLP_NOT_IMPLEMENTED = -17, 99 SLP_BUFFER_OVERFLOW = -18, 100 SLP_NETWORK_TIMED_OUT = -19, 101 SLP_NETWORK_INIT_FAILED = -20, 102 SLP_MEMORY_ALLOC_FAILED = -21, 103 SLP_PARAMETER_BAD = -22, 104 SLP_NETWORK_ERROR = -23, 105 SLP_INTERNAL_SYSTEM_ERROR = -24, 106 SLP_HANDLE_IN_USE = -25, 107 SLP_TYPE_ERROR = -26, 108 SLP_SECURITY_UNAVAILABLE = -128 109 } SLPError; 110 111 /* 112 * The SLPRegReport callback type is the type of the callback function 113 * to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. 114 */ 115 typedef void 116 SLPRegReport( 117 SLPHandle hSLP, /* operation SLPHandle */ 118 SLPError errCode, /* error code */ 119 void *pvCookie /* client code cookie */ 120 ); 121 122 /* 123 * The SLPSrvTypeCallback type is the type of the callback function 124 * parameter to SLPFindSrvTypes() function. 125 */ 126 typedef SLPBoolean 127 SLPSrvTypeCallback( 128 SLPHandle hSLP, /* operation SLPHandle */ 129 const char *pcSrvTypes, /* list of service types */ 130 SLPError errCode, /* error code */ 131 void *pvCookie /* client code cookie */ 132 ); 133 134 /* 135 * The SLPSrvURLCallback type is the type of the callback function 136 * parameter to SLPFindSrvs() function. The client should return a 137 */ 138 typedef SLPBoolean 139 SLPSrvURLCallback( 140 SLPHandle hSLP, /* operation SLPHandle */ 141 const char *pcSrvURL, /* the returned service URL */ 142 unsigned short usLifetime, /* life time of the service advert */ 143 SLPError errCode, /* error code */ 144 void *pvCookie /* client code cookie */ 145 ); 146 147 /* 148 * The SLPAttrCallback type is the type of the callback function 149 * parameter to SLPFindAttrs() function. 150 */ 151 typedef SLPBoolean 152 SLPAttrCallback( 153 SLPHandle hSLP, /* operation SLPHandle */ 154 const char *pcAttrList, /* attribute id/value assignments */ 155 SLPError errCode, /* error code */ 156 void *pvCookie /* client code cookie */ 157 ); 158 159 extern SLPError 160 SLPOpen( 161 const char *pcLang, /* natural language locale */ 162 SLPBoolean isAsync, /* asynchronous if true */ 163 SLPHandle *phSLP /* pointer to resulting handle */ 164 ); 165 166 /* 167 * Frees all resources associated with the handle 168 */ 169 extern void SLPClose( 170 SLPHandle hSLP /* handle to be closed */ 171 ); 172 173 /* 174 * Registers the URL in pcSrvURL having the lifetime usLifetime with the 175 * attribute list in pcAttrs. 176 */ 177 extern SLPError 178 SLPReg( 179 SLPHandle hSLP, /* operation SLPHandle */ 180 const char *pcSrvURL, /* the URL to register */ 181 const unsigned short usLifetime, /* life time of the service advert */ 182 const char *pcSrvType, /* the service type */ 183 const char *pcAttrs, /* attributes of the advertisement */ 184 SLPBoolean fresh, /* fresh registration if true */ 185 SLPRegReport callback, /* receives completion status */ 186 void *pvCookie /* client code cookie */ 187 ); 188 189 /* 190 * Deregisters the advertisment for URL pURL in all scopes where the 191 * service is registered and all language locales, not just the locale 192 * of the SLPHandle. 193 */ 194 extern SLPError 195 SLPDereg( 196 SLPHandle hSLP, /* operation SLPHandle */ 197 const char *pcURL, /* the URL to deregister */ 198 SLPRegReport callback, /* receives completion status */ 199 void *pvCookie /* client code cookie */ 200 ); 201 202 /* 203 * Delete the selected attributes in the locale of the SLPHandle. 204 */ 205 extern SLPError 206 SLPDelAttrs( 207 SLPHandle hSLP, /* operation SLPHandle */ 208 const char *pcURL, /* URL for attrs to deregister */ 209 const char *pcAttrs, /* attributes to deregister */ 210 SLPRegReport callback, /* receives completion status */ 211 void *pvCookie /* client code cookie */ 212 ); 213 214 /* 215 * The SLPFindSrvType() function issues an SLP service type request 216 * for service types in the scopes indicated by the pcScopeList. The 217 * results are returned through the callback parameter. 218 */ 219 extern SLPError 220 SLPFindSrvTypes( 221 SLPHandle hSLP, /* operation SLPHandle */ 222 const char *pcNamingAuthority, /* naming authority to search */ 223 const char *pcScopeList, /* scopes to search */ 224 SLPSrvTypeCallback callback, /* receives results */ 225 void *pvCookie /* client code cookie */ 226 ); 227 228 /* 229 * Issue the query for services on the language specific SLPHandle and 230 * return the results through the callback. 231 */ 232 extern SLPError 233 SLPFindSrvs( 234 SLPHandle hSLP, /* operation SLPHandle */ 235 const char *pcServiceType, /* service type string */ 236 const char *pcScopeList, /* scopes to search */ 237 const char *pcSearchFilter, /* LDAPv3 Search Filter */ 238 SLPSrvURLCallback callback, /* receives results */ 239 void *pvCookie /* client code cookie */ 240 ); 241 242 /* 243 * This function returns service attributes matching the attribute ids 244 * for the indicated full or partial URL. 245 */ 246 extern SLPError 247 SLPFindAttrs( 248 SLPHandle hSLP, /* operation SLPHandle */ 249 const char *pcURL, /* the full or partial URL */ 250 const char *pcScopeList, /* scopes to search */ 251 const char *pcAttrIds, /* which attribute values to return */ 252 SLPAttrCallback callback, /* receives results */ 253 void *pvCookie /* client code cookie */ 254 ); 255 256 /* 257 * Returns the minimum refresh interval, in seconds, that any SA 258 * should use when refreshing registrations. If 0, there is no 259 * minimum interval, and the SA can use what it pleases. 260 */ 261 extern unsigned short 262 SLPGetRefreshInterval(); 263 264 /* 265 * Sets ppcScopeList parameter to a pointer to a comma separated list 266 * including all available scope values. 267 */ 268 extern SLPError 269 SLPFindScopes( 270 SLPHandle hSLP, /* operation SLPHandle */ 271 char **ppcScopeList /* pointer to result */ 272 ); 273 274 /* 275 * Parses the URL passed in as the argument into a service URL structure 276 * and return it in the ppSrvURL pointer. 277 */ 278 extern SLPError 279 SLPParseSrvURL( 280 char *pcSrvURL, /* URL string to parse */ 281 SLPSrvURL **ppSrvURL /* pointer to result */ 282 ); 283 284 /* 285 * Frees memory returned from SLPParseSrvURL(), SLPEscape(), 286 * SLPUnescape(), and SLPFindScopes(). 287 */ 288 extern void 289 SLPFree( 290 void *pvMem /* pointer to memory to free */ 291 ); 292 293 /* 294 * Process the input string in pcInbuf and escape any SLP reserved 295 * characters. 296 */ 297 extern SLPError 298 SLPEscape( 299 const char *pcInbuf, /* buffer to process */ 300 char **ppcOutBuf, /* pointer to result */ 301 SLPBoolean isTag /* if true, check for bad tag chars */ 302 ); 303 304 /* 305 * Process the input string in pcInbuf and unescape any SLP reserved 306 * characters. 307 */ 308 extern SLPError 309 SLPUnescape( 310 const char *pcInbuf, /* buffer to process */ 311 char **ppcOutbuf, /* pointer to result */ 312 SLPBoolean isTag /* if true, check for bad tag chars */ 313 ); 314 315 /* 316 * Returns the value of the corresponding SLP property name. The 317 * returned string is owned by the library and MUST NOT be freed. 318 */ 319 extern const char * 320 SLPGetProperty( 321 const char *pcName /* property name */ 322 ); 323 324 /* 325 * Sets the value of the SLP property to the new value. The pcValue 326 * parameter should be the property value as a string. 327 */ 328 extern void 329 SLPSetProperty( 330 const char *pcName, /* property name */ 331 const char *pcValue /* property value */ 332 ); 333 334 /* 335 * Maps err_code to an SLP error string. The returned string should not 336 * be overwritten. 337 */ 338 extern const char * 339 slp_strerror( 340 SLPError err_code /* SLP error code */ 341 ); 342 343 #ifdef __cplusplus 344 } 345 #endif 346 347 #endif /* _SLP_H */ 348