usr/src/lib/libslp/clib/slp.h

   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 */