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