Back to index

lightning-sunbird  0.9+nobinonly
ldap-extension.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is Mozilla Communicator client code, released
00015  * March 31, 1998.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-1999
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /* ldap-extension.h - extensions to the ldap c api specification */
00039 
00040 #ifndef _LDAP_EXTENSION_H
00041 #define _LDAP_EXTENSION_H
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif
00046 
00047 #define LDAP_PORT_MAX           65535           /* API extension */
00048 #define LDAP_VERSION1           1               /* API extension */
00049 #define LDAP_VERSION            LDAP_VERSION2   /* API extension */
00050 
00051 
00052 /*
00053  * C LDAP features we support that are not (yet) part of the LDAP C API
00054  * Internet Draft.  Use the ldap_get_option() call with an option value of
00055  * LDAP_OPT_API_FEATURE_INFO to retrieve information about a feature.
00056  *
00057  * Note that this list is incomplete; it includes only the most widely
00058  * used extensions.  Also, the version is 1 for all of these for now.
00059  */
00060 #define LDAP_API_FEATURE_SERVER_SIDE_SORT       1
00061 #define LDAP_API_FEATURE_VIRTUAL_LIST_VIEW      1
00062 #define LDAP_API_FEATURE_PERSISTENT_SEARCH      1
00063 #define LDAP_API_FEATURE_PROXY_AUTHORIZATION    1
00064 #define LDAP_API_FEATURE_X_LDERRNO              1
00065 #define LDAP_API_FEATURE_X_MEMCACHE             1
00066 #define LDAP_API_FEATURE_X_IO_FUNCTIONS         1
00067 #define LDAP_API_FEATURE_X_EXTIO_FUNCTIONS      1
00068 #define LDAP_API_FEATURE_X_DNS_FUNCTIONS        1
00069 #define LDAP_API_FEATURE_X_MEMALLOC_FUNCTIONS   1
00070 #define LDAP_API_FEATURE_X_THREAD_FUNCTIONS     1
00071 #define LDAP_API_FEATURE_X_EXTHREAD_FUNCTIONS   1
00072 #define LDAP_API_FEATURE_X_GETLANGVALUES        1
00073 #define LDAP_API_FEATURE_X_CLIENT_SIDE_SORT     1
00074 #define LDAP_API_FEATURE_X_URL_FUNCTIONS        1
00075 #define LDAP_API_FEATURE_X_FILTER_FUNCTIONS     1
00076 
00077 #define LDAP_ROOT_DSE           ""              /* API extension */
00078 
00079 #define LDAP_OPT_DESC                   0x01    /*  1 */
00080 
00081 #define NULLMSG ((LDAPMessage *)0)
00082 
00083 /*built-in SASL methods */
00084 #define LDAP_SASL_EXTERNAL      "EXTERNAL"      /* TLS/SSL extension */
00085 
00086 /* possible error codes we can be returned */
00087 #define LDAP_PARTIAL_RESULTS            0x09    /* 9 (UMich LDAPv2 extn) */
00088 #define NAME_ERROR(n)   ((n & 0xf0) == 0x20)
00089 
00090 #define LDAP_SORT_CONTROL_MISSING       0x3C    /* 60 (server side sort extn) */
00091 #define LDAP_INDEX_RANGE_ERROR          0x3D    /* 61 (VLV extn) */
00092 
00093 /*
00094  * LDAPv3 server controls we know about
00095  */
00096 #define LDAP_CONTROL_MANAGEDSAIT        "2.16.840.1.113730.3.4.2"
00097 #define LDAP_CONTROL_SORTREQUEST        "1.2.840.113556.1.4.473"
00098 #define LDAP_CONTROL_SORTRESPONSE       "1.2.840.113556.1.4.474"
00099 #define LDAP_CONTROL_PERSISTENTSEARCH   "2.16.840.1.113730.3.4.3"
00100 #define LDAP_CONTROL_ENTRYCHANGE        "2.16.840.1.113730.3.4.7"
00101 #define LDAP_CONTROL_VLVREQUEST         "2.16.840.1.113730.3.4.9"
00102 #define LDAP_CONTROL_VLVRESPONSE        "2.16.840.1.113730.3.4.10"
00103 #define LDAP_CONTROL_PROXYAUTH          "2.16.840.1.113730.3.4.12" /* version 1
00104 */
00105 #define LDAP_CONTROL_PROXIEDAUTH        "2.16.840.1.113730.3.4.18" /* version 2
00106 */
00107 
00108 /* Authentication request and response controls */
00109 #define LDAP_CONTROL_AUTH_REQUEST       "2.16.840.1.113730.3.4.16"
00110 #define LDAP_CONTROL_AUTH_RESPONSE      "2.16.840.1.113730.3.4.15"
00111 
00112 /* Password information sent back to client */
00113 #define LDAP_CONTROL_PWEXPIRED          "2.16.840.1.113730.3.4.4"
00114 #define LDAP_CONTROL_PWEXPIRING         "2.16.840.1.113730.3.4.5"
00115 
00116 /* Suppress virtual/inherited attribute values */
00117 #define LDAP_CONTROL_REAL_ATTRS_ONLY      "2.16.840.1.113730.3.4.17"
00118 
00119 /* Only return virtual/inherited attribute values */
00120 #define LDAP_CONTROL_VIRTUAL_ATTRS_ONLY   "2.16.840.1.113730.3.4.19"
00121 
00122 
00123 LDAP_API(void) LDAP_CALL ldap_ber_free( BerElement *ber, int freebuf );
00124 
00125 /*
00126  * Server side sorting of search results (an LDAPv3 extension --
00127  * LDAP_API_FEATURE_SERVER_SIDE_SORT)
00128  */
00129 typedef struct LDAPsortkey {    /* structure for a sort-key */
00130         char *  sk_attrtype;
00131         char *  sk_matchruleoid;
00132         int     sk_reverseorder;
00133 } LDAPsortkey;
00134 
00135 LDAP_API(int) LDAP_CALL ldap_create_sort_control( LDAP *ld,
00136         LDAPsortkey **sortKeyList, const char ctl_iscritical,
00137         LDAPControl **ctrlp );
00138 LDAP_API(int) LDAP_CALL ldap_parse_sort_control( LDAP *ld,
00139         LDAPControl **ctrls, unsigned long *result, char **attribute );
00140 
00141 LDAP_API(void) LDAP_CALL ldap_free_sort_keylist( LDAPsortkey **sortKeyList );
00142 LDAP_API(int) LDAP_CALL ldap_create_sort_keylist( LDAPsortkey ***sortKeyList,
00143         const char *string_rep );
00144 
00145 
00146 /*
00147  * Virtual list view (an LDAPv3 extension -- LDAP_API_FEATURE_VIRTUAL_LIST_VIEW)
00148  */
00149 /*
00150  * structure that describes a VirtualListViewRequest control.
00151  * note that ldvlist_index and ldvlist_size are only relevant to
00152  * ldap_create_virtuallist_control() if ldvlist_attrvalue is NULL.
00153  */
00154 typedef struct ldapvirtuallist {
00155     unsigned long   ldvlist_before_count;       /* # entries before target */
00156     unsigned long   ldvlist_after_count;        /* # entries after target */
00157     char            *ldvlist_attrvalue;         /* jump to this value */
00158     unsigned long   ldvlist_index;              /* list offset */
00159     unsigned long   ldvlist_size;               /* number of items in vlist */
00160     void            *ldvlist_extradata;         /* for use by application */
00161 } LDAPVirtualList;
00162 
00163 /*
00164  * VLV functions:
00165  */
00166 LDAP_API(int) LDAP_CALL ldap_create_virtuallist_control( LDAP *ld,
00167         LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );
00168 
00169 LDAP_API(int) LDAP_CALL ldap_parse_virtuallist_control( LDAP *ld,
00170         LDAPControl **ctrls, unsigned long *target_posp,
00171         unsigned long *list_sizep, int *errcodep );
00172 
00173 /*
00174  * Routines for creating persistent search controls and for handling
00175  * "entry changed notification" controls (an LDAPv3 extension --
00176  * LDAP_API_FEATURE_PERSISTENT_SEARCH)
00177  */
00178 #define LDAP_CHANGETYPE_ADD             1
00179 #define LDAP_CHANGETYPE_DELETE          2
00180 #define LDAP_CHANGETYPE_MODIFY          4
00181 #define LDAP_CHANGETYPE_MODDN           8
00182 #define LDAP_CHANGETYPE_ANY             (1|2|4|8)
00183 LDAP_API(int) LDAP_CALL ldap_create_persistentsearch_control( LDAP *ld,
00184         int changetypes, int changesonly, int return_echg_ctls,
00185         char ctl_iscritical, LDAPControl **ctrlp );
00186 LDAP_API(int) LDAP_CALL ldap_parse_entrychange_control( LDAP *ld,
00187         LDAPControl **ctrls, int *chgtypep, char **prevdnp,
00188         int *chgnumpresentp, long *chgnump );
00189 
00190 /*
00191  * Routines for creating Proxied Authorization controls (an LDAPv3
00192  * extension -- LDAP_API_FEATURE_PROXY_AUTHORIZATION)
00193  * ldap_create_proxyauth_control() is for the old (version 1) control.
00194  * ldap_create_proxiedauth_control() is for the newer (version 2) control.
00195  */
00196 LDAP_API(int) LDAP_CALL ldap_create_proxyauth_control( LDAP *ld,
00197         const char *dn, const char ctl_iscritical, LDAPControl **ctrlp );
00198 LDAP_API(int) LDAP_CALL ldap_create_proxiedauth_control( LDAP *ld,
00199         const char *authzid, LDAPControl **ctrlp );
00200 
00201 /*
00202  * Functions to get and set LDAP error information (API extension --
00203  * LDAP_API_FEATURE_X_LDERRNO )
00204  *
00205  * By using LDAP_OPT_THREAD_FN_PTRS, you can arrange for the error info. to
00206  * be thread-specific.
00207  */
00208 LDAP_API(int) LDAP_CALL ldap_get_lderrno( LDAP *ld, char **m, char **s );
00209 LDAP_API(int) LDAP_CALL ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );
00210 
00211 
00212 /*
00213  * LDAP URL functions and definitions (an API extension --
00214  * LDAP_API_FEATURE_X_URL_FUNCTIONS)
00215  */
00216 /*
00217  * types for ldap URL handling
00218  */
00219 typedef struct ldap_url_desc {
00220     char                *lud_host;
00221     int                 lud_port;
00222     char                *lud_dn;
00223     char                **lud_attrs;
00224     int                 lud_scope;
00225     char                *lud_filter;
00226     unsigned long       lud_options;
00227 #define LDAP_URL_OPT_SECURE     0x01
00228     char        *lud_string;    /* for internal use only */
00229 } LDAPURLDesc;
00230 
00231 #define NULLLDAPURLDESC ((LDAPURLDesc *)NULL)
00232 
00233 /*
00234  * possible errors returned by ldap_url_parse()
00235  */
00236 #define LDAP_URL_ERR_NOTLDAP    1       /* URL doesn't begin with "ldap://" */
00237 #define LDAP_URL_ERR_NODN       2       /* URL has no DN (required) */
00238 #define LDAP_URL_ERR_BADSCOPE   3       /* URL scope string is invalid */
00239 #define LDAP_URL_ERR_MEM        4       /* can't allocate memory space */
00240 #define LDAP_URL_ERR_PARAM      5       /* bad parameter to an URL function */
00241 #define LDAP_URL_UNRECOGNIZED_CRITICAL_EXTENSION 6
00242 
00243 /*
00244  * URL functions:
00245  */
00246 LDAP_API(int) LDAP_CALL ldap_is_ldap_url( const char *url );
00247 LDAP_API(int) LDAP_CALL ldap_url_parse( const char *url, LDAPURLDesc **ludpp );
00248 LDAP_API(void) LDAP_CALL ldap_free_urldesc( LDAPURLDesc *ludp );
00249 LDAP_API(int) LDAP_CALL ldap_url_search( LDAP *ld, const char *url,
00250         int attrsonly );
00251 LDAP_API(int) LDAP_CALL ldap_url_search_s( LDAP *ld, const char *url,
00252         int attrsonly, LDAPMessage **res );
00253 LDAP_API(int) LDAP_CALL ldap_url_search_st( LDAP *ld, const char *url,
00254         int attrsonly, struct timeval *timeout, LDAPMessage **res );
00255 
00256 
00257 /*
00258  * Function to dispose of an array of LDAPMod structures (an API extension).
00259  * Warning: don't use this unless the mods array was allocated using the
00260  * same memory allocator as is being used by libldap.
00261  */
00262 LDAP_API(void) LDAP_CALL ldap_mods_free( LDAPMod **mods, int freemods );
00263 
00264 /*
00265  * SSL option (an API extension):
00266  */
00267 #define LDAP_OPT_SSL                    0x0A    /* 10 - API extension */
00268 
00269 /*
00270  * Referral hop limit (an API extension):
00271  */
00272 #define LDAP_OPT_REFERRAL_HOP_LIMIT     0x10    /* 16 - API extension */
00273 
00274 /*
00275  * Rebind callback function (an API extension)
00276  */
00277 #define LDAP_OPT_REBIND_FN              0x06    /* 6 - API extension */
00278 #define LDAP_OPT_REBIND_ARG             0x07    /* 7 - API extension */
00279 typedef int (LDAP_CALL LDAP_CALLBACK LDAP_REBINDPROC_CALLBACK)( LDAP *ld,
00280         char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg);
00281 LDAP_API(void) LDAP_CALL ldap_set_rebind_proc( LDAP *ld,
00282         LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );
00283 
00284 /*
00285  * Thread function callbacks (an API extension --
00286  * LDAP_API_FEATURE_X_THREAD_FUNCTIONS).
00287  */
00288 #define LDAP_OPT_THREAD_FN_PTRS         0x05    /* 5 - API extension */
00289 
00290 /*
00291  * Thread callback functions:
00292  */
00293 typedef void *(LDAP_C LDAP_CALLBACK LDAP_TF_MUTEX_ALLOC_CALLBACK)( void );
00294 typedef void (LDAP_C LDAP_CALLBACK LDAP_TF_MUTEX_FREE_CALLBACK)( void *m );
00295 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_MUTEX_LOCK_CALLBACK)( void *m );
00296 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_MUTEX_UNLOCK_CALLBACK)( void *m );
00297 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_GET_ERRNO_CALLBACK)( void );
00298 typedef void (LDAP_C LDAP_CALLBACK LDAP_TF_SET_ERRNO_CALLBACK)( int e );
00299 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_GET_LDERRNO_CALLBACK)(
00300         char **matchedp, char **errmsgp, void *arg );
00301 typedef void    (LDAP_C LDAP_CALLBACK LDAP_TF_SET_LDERRNO_CALLBACK)( int err,
00302         char *matched, char *errmsg, void *arg );
00303 
00304 /*
00305  * Structure to hold thread function pointers:
00306  */
00307 struct ldap_thread_fns {
00308         LDAP_TF_MUTEX_ALLOC_CALLBACK *ltf_mutex_alloc;
00309         LDAP_TF_MUTEX_FREE_CALLBACK *ltf_mutex_free;
00310         LDAP_TF_MUTEX_LOCK_CALLBACK *ltf_mutex_lock;
00311         LDAP_TF_MUTEX_UNLOCK_CALLBACK *ltf_mutex_unlock;
00312         LDAP_TF_GET_ERRNO_CALLBACK *ltf_get_errno;
00313         LDAP_TF_SET_ERRNO_CALLBACK *ltf_set_errno;
00314         LDAP_TF_GET_LDERRNO_CALLBACK *ltf_get_lderrno;
00315         LDAP_TF_SET_LDERRNO_CALLBACK *ltf_set_lderrno;
00316         void    *ltf_lderrno_arg;
00317 };
00318 
00319 /*
00320  * Extended I/O function callbacks option (an API extension --
00321  * LDAP_API_FEATURE_X_EXTIO_FUNCTIONS).
00322  */
00323 #define LDAP_X_OPT_EXTIO_FN_PTRS   (LDAP_OPT_PRIVATE_EXTENSION_BASE + 0x0F00)
00324         /* 0x4000 + 0x0F00 = 0x4F00 = 20224 - API extension */
00325 
00326 /*
00327  * These extended I/O function callbacks echo the BSD socket API but accept
00328  * an extra pointer parameter at the end of their argument list that can
00329  * be used by client applications for their own needs.  For some of the calls,
00330  * the pointer is a session argument of type struct lextiof_session_private *
00331  * that is associated with the LDAP session handle (LDAP *).  For others, the
00332  * pointer is a socket specific struct lextiof_socket_private * argument that
00333  * is associated with a particular socket (a TCP connection).
00334  *
00335  * The lextiof_session_private and lextiof_socket_private structures are not
00336  * defined by the LDAP C API; users of this extended I/O interface should
00337  * define these themselves.
00338  *
00339  * The combination of the integer socket number (i.e., lpoll_fd, which is
00340  * the value returned by the CONNECT callback) and the application specific
00341  * socket argument (i.e., lpoll_socketarg, which is the value set in *sockargpp
00342  * by the CONNECT callback) must be unique.
00343  *
00344  * The types for the extended READ and WRITE callbacks are actually in lber.h.
00345  *
00346  * The CONNECT callback gets passed both the session argument (sessionarg)
00347  * and a pointer to a socket argument (socketargp) so it has the
00348  * opportunity to set the socket-specific argument.  The CONNECT callback
00349  * also takes a timeout parameter whose value can be set by calling
00350  * ldap_set_option( ld, LDAP_X_OPT_..., &val ).  The units used for the
00351  * timeout parameter are milliseconds.
00352  *
00353  * A POLL interface is provided instead of a select() one.  The timeout is
00354  * in milliseconds.
00355  *
00356  * A NEWHANDLE callback function is also provided.  It is called right
00357  * after the LDAP session handle is created, e.g., during ldap_init().
00358  * If the NEWHANDLE callback returns anything other than LDAP_SUCCESS,
00359  * the session handle allocation fails.
00360  *
00361  * A DISPOSEHANDLE callback function is also provided.  It is called right
00362  * before the LDAP session handle and its contents are destroyed, e.g.,
00363  * during ldap_unbind().
00364  */
00365 
00366 /*
00367  * Special timeout values for poll and connect:
00368  */
00369 #define LDAP_X_IO_TIMEOUT_NO_WAIT       0       /* return immediately */
00370 #define LDAP_X_IO_TIMEOUT_NO_TIMEOUT    (-1)    /* block indefinitely */
00371 
00372 /* LDAP poll()-like descriptor:
00373  */
00374 typedef struct ldap_x_pollfd {     /* used by LDAP_X_EXTIOF_POLL_CALLBACK */
00375     int         lpoll_fd;          /* integer file descriptor / socket */
00376     struct lextiof_socket_private
00377                 *lpoll_socketarg;
00378                                    /* pointer socket and for use by */
00379                                    /* application */
00380     short       lpoll_events;      /* requested event */
00381     short       lpoll_revents;     /* returned event */
00382 } LDAP_X_PollFD;
00383 
00384 /* Event flags for lpoll_events and lpoll_revents:
00385  */
00386 #define LDAP_X_POLLIN    0x01  /* regular data ready for reading */
00387 #define LDAP_X_POLLPRI   0x02  /* high priority data available */
00388 #define LDAP_X_POLLOUT   0x04  /* ready for writing */
00389 #define LDAP_X_POLLERR   0x08  /* error occurred -- only in lpoll_revents */
00390 #define LDAP_X_POLLHUP   0x10  /* connection closed -- only in lpoll_revents */
00391 #define LDAP_X_POLLNVAL  0x20  /* invalid lpoll_fd -- only in lpoll_revents */
00392 
00393 /* Options passed to LDAP_X_EXTIOF_CONNECT_CALLBACK to modify socket behavior:
00394  */
00395 #define LDAP_X_EXTIOF_OPT_NONBLOCKING   0x01  /* turn on non-blocking mode */
00396 #define LDAP_X_EXTIOF_OPT_SECURE        0x02  /* turn on 'secure' mode */
00397 
00398 
00399 /* extended I/O callback function prototypes:
00400  */
00401 typedef int     (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_CONNECT_CALLBACK )(
00402             const char *hostlist, int port, /* host byte order */
00403             int timeout /* milliseconds */,
00404             unsigned long options, /* bitmapped options */
00405             struct lextiof_session_private *sessionarg,
00406             struct lextiof_socket_private **socketargp );
00407 typedef int     (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_CLOSE_CALLBACK )(
00408             int s, struct lextiof_socket_private *socketarg );
00409 typedef int     (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_POLL_CALLBACK)(
00410             LDAP_X_PollFD fds[], int nfds, int timeout /* milliseconds */,
00411             struct lextiof_session_private *sessionarg );
00412 typedef int     (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_NEWHANDLE_CALLBACK)(
00413             LDAP *ld, struct lextiof_session_private *sessionarg );
00414 typedef void    (LDAP_C LDAP_CALLBACK LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK)(
00415             LDAP *ld, struct lextiof_session_private *sessionarg );
00416 
00417 
00418 /* Structure to hold extended I/O function pointers:
00419  */
00420 struct ldap_x_ext_io_fns {
00421         /* lextiof_size should always be set to LDAP_X_EXTIO_FNS_SIZE */
00422         int                                     lextiof_size;
00423         LDAP_X_EXTIOF_CONNECT_CALLBACK          *lextiof_connect;
00424         LDAP_X_EXTIOF_CLOSE_CALLBACK            *lextiof_close;
00425         LDAP_X_EXTIOF_READ_CALLBACK             *lextiof_read;
00426         LDAP_X_EXTIOF_WRITE_CALLBACK            *lextiof_write;
00427         LDAP_X_EXTIOF_POLL_CALLBACK             *lextiof_poll;
00428         LDAP_X_EXTIOF_NEWHANDLE_CALLBACK        *lextiof_newhandle;
00429         LDAP_X_EXTIOF_DISPOSEHANDLE_CALLBACK    *lextiof_disposehandle;
00430         void                                    *lextiof_session_arg;
00431         LDAP_X_EXTIOF_WRITEV_CALLBACK           *lextiof_writev;
00432 };
00433 #define LDAP_X_EXTIO_FNS_SIZE   sizeof(struct ldap_x_ext_io_fns)
00434 
00435 /*
00436  * Utility functions for parsing space-separated host lists (useful for
00437  * implementing an extended I/O CONNECT callback function).
00438  */
00439 struct ldap_x_hostlist_status;
00440 LDAP_API(int) LDAP_CALL ldap_x_hostlist_first( const char *hostlist,
00441         int defport, char **hostp, int *portp /* host byte order */,
00442         struct ldap_x_hostlist_status **statusp );
00443 LDAP_API(int) LDAP_CALL ldap_x_hostlist_next( char **hostp,
00444         int *portp /* host byte order */, struct ldap_x_hostlist_status *status
00445 );
00446 LDAP_API(void) LDAP_CALL ldap_x_hostlist_statusfree(
00447         struct ldap_x_hostlist_status *status );
00448 
00449 /*
00450  * Client side sorting of entries (an API extension --
00451  * LDAP_API_FEATURE_X_CLIENT_SIDE_SORT)
00452  */
00453 /*
00454  * Client side sorting callback functions:
00455  */
00456 typedef const struct berval* (LDAP_C LDAP_CALLBACK
00457         LDAP_KEYGEN_CALLBACK)( void *arg, LDAP *ld, LDAPMessage *entry );
00458 typedef int (LDAP_C LDAP_CALLBACK
00459         LDAP_KEYCMP_CALLBACK)( void *arg, const struct berval*,
00460         const struct berval* );
00461 typedef void (LDAP_C LDAP_CALLBACK
00462         LDAP_KEYFREE_CALLBACK)( void *arg, const struct berval* );
00463 typedef int (LDAP_C LDAP_CALLBACK
00464         LDAP_CMP_CALLBACK)(const char *val1, const char *val2);
00465 typedef int (LDAP_C LDAP_CALLBACK
00466         LDAP_VALCMP_CALLBACK)(const char **val1p, const char **val2p);
00467 
00468 /*
00469  * Client side sorting functions:
00470  */
00471 LDAP_API(int) LDAP_CALL ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
00472         void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
00473         LDAP_KEYFREE_CALLBACK *fre );
00474 LDAP_API(int) LDAP_CALL ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
00475         char **attr, LDAP_CMP_CALLBACK *cmp );
00476 LDAP_API(int) LDAP_CALL ldap_sort_entries( LDAP *ld, LDAPMessage **chain,
00477         char *attr, LDAP_CMP_CALLBACK *cmp );
00478 LDAP_API(int) LDAP_CALL ldap_sort_values( LDAP *ld, char **vals,
00479         LDAP_VALCMP_CALLBACK *cmp );
00480 LDAP_API(int) LDAP_C LDAP_CALLBACK ldap_sort_strcasecmp( const char **a,
00481         const char **b );
00482 
00483 
00484 /*
00485  * Filter functions and definitions (an API extension --
00486  * LDAP_API_FEATURE_X_FILTER_FUNCTIONS)
00487  */
00488 /*
00489  * Structures, constants, and types for filter utility routines:
00490  */
00491 typedef struct ldap_filt_info {
00492         char                    *lfi_filter;
00493         char                    *lfi_desc;
00494         int                     lfi_scope;      /* LDAP_SCOPE_BASE, etc */
00495         int                     lfi_isexact;    /* exact match filter? */
00496         struct ldap_filt_info   *lfi_next;
00497 } LDAPFiltInfo;
00498 
00499 #define LDAP_FILT_MAXSIZ        1024
00500 
00501 typedef struct ldap_filt_list LDAPFiltList; /* opaque filter list handle */
00502 typedef struct ldap_filt_desc LDAPFiltDesc; /* opaque filter desc handle */
00503 
00504 /*
00505  * Filter utility functions:
00506  */
00507 LDAP_API(LDAPFiltDesc *) LDAP_CALL ldap_init_getfilter( char *fname );
00508 LDAP_API(LDAPFiltDesc *) LDAP_CALL ldap_init_getfilter_buf( char *buf,
00509         long buflen );
00510 LDAP_API(LDAPFiltInfo *) LDAP_CALL ldap_getfirstfilter( LDAPFiltDesc *lfdp,
00511         char *tagpat, char *value );
00512 LDAP_API(LDAPFiltInfo *) LDAP_CALL ldap_getnextfilter( LDAPFiltDesc *lfdp );
00513 LDAP_API(int) LDAP_CALL ldap_set_filter_additions( LDAPFiltDesc *lfdp,
00514         char *prefix, char *suffix );
00515 LDAP_API(int) LDAP_CALL ldap_create_filter( char *buf, unsigned long buflen,
00516         char *pattern, char *prefix, char *suffix, char *attr,
00517         char *value, char **valwords );
00518 LDAP_API(void) LDAP_CALL ldap_getfilter_free( LDAPFiltDesc *lfdp );
00519 
00520 /*
00521  * Friendly mapping structure and routines (an API extension)
00522  */
00523 typedef struct friendly {
00524         char    *f_unfriendly;
00525         char    *f_friendly;
00526 } *FriendlyMap;
00527 LDAP_API(char *) LDAP_CALL ldap_friendly_name( char *filename, char *name,
00528         FriendlyMap *map );
00529 LDAP_API(void) LDAP_CALL ldap_free_friendlymap( FriendlyMap *map );
00530 
00531 /*
00532  * In Memory Cache (an API extension -- LDAP_API_FEATURE_X_MEMCACHE)
00533  */
00534 typedef struct ldapmemcache  LDAPMemCache;  /* opaque in-memory cache handle */
00535 
00536 LDAP_API(int) LDAP_CALL ldap_memcache_init( unsigned long ttl,
00537         unsigned long size, char **baseDNs, struct ldap_thread_fns *thread_fns,
00538         LDAPMemCache **cachep );
00539 LDAP_API(int) LDAP_CALL ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );
00540 LDAP_API(int) LDAP_CALL ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );
00541 LDAP_API(void) LDAP_CALL ldap_memcache_flush( LDAPMemCache *cache, char *dn,
00542         int scope );
00543 LDAP_API(void) LDAP_CALL ldap_memcache_destroy( LDAPMemCache *cache );
00544 LDAP_API(void) LDAP_CALL ldap_memcache_update( LDAPMemCache *cache );
00545 
00546 /*
00547  * Timeout value for nonblocking connect call
00548  */
00549 #define LDAP_X_OPT_CONNECT_TIMEOUT    (LDAP_OPT_PRIVATE_EXTENSION_BASE + 0x0F01)
00550         /* 0x4000 + 0x0F01 = 0x4F01 = 20225 - API extension */
00551 
00552 /*
00553  * Memory allocation callback functions (an API extension --
00554  * LDAP_API_FEATURE_X_MEMALLOC_FUNCTIONS).  These are global and can
00555  * not be set on a per-LDAP session handle basis.  Install your own
00556  * functions by making a call like this:
00557  *    ldap_set_option( NULL, LDAP_OPT_MEMALLOC_FN_PTRS, &memalloc_fns );
00558  *
00559  * look in lber.h for the function typedefs themselves.
00560  */
00561 #define LDAP_OPT_MEMALLOC_FN_PTRS       0x61    /* 97 - API extension */
00562 
00563 struct ldap_memalloc_fns {
00564         LDAP_MALLOC_CALLBACK    *ldapmem_malloc;
00565         LDAP_CALLOC_CALLBACK    *ldapmem_calloc;
00566         LDAP_REALLOC_CALLBACK   *ldapmem_realloc;
00567         LDAP_FREE_CALLBACK      *ldapmem_free;
00568 };
00569 
00570 
00571 /*
00572  * Memory allocation functions (an API extension)
00573  */
00574 void *ldap_x_malloc( size_t size );
00575 void *ldap_x_calloc( size_t nelem, size_t elsize );
00576 void *ldap_x_realloc( void *ptr, size_t size );
00577 void ldap_x_free( void *ptr );
00578 
00579 /*
00580  * Server reconnect (an API extension).
00581  */
00582 #define LDAP_OPT_RECONNECT              0x62    /* 98 - API extension */
00583 
00584 
00585 /*
00586  * Extra thread callback functions (an API extension --
00587  * LDAP_API_FEATURE_X_EXTHREAD_FUNCTIONS)
00588  */
00589 #define LDAP_OPT_EXTRA_THREAD_FN_PTRS  0x65     /* 101 - API extension */
00590 
00591 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_MUTEX_TRYLOCK_CALLBACK)( void *m );
00592 typedef void *(LDAP_C LDAP_CALLBACK LDAP_TF_SEMA_ALLOC_CALLBACK)( void );
00593 typedef void (LDAP_C LDAP_CALLBACK LDAP_TF_SEMA_FREE_CALLBACK)( void *s );
00594 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_SEMA_WAIT_CALLBACK)( void *s );
00595 typedef int (LDAP_C LDAP_CALLBACK LDAP_TF_SEMA_POST_CALLBACK)( void *s );
00596 typedef void *(LDAP_C LDAP_CALLBACK LDAP_TF_THREADID_CALLBACK)(void);
00597 
00598 struct ldap_extra_thread_fns {
00599         LDAP_TF_MUTEX_TRYLOCK_CALLBACK *ltf_mutex_trylock;
00600         LDAP_TF_SEMA_ALLOC_CALLBACK *ltf_sema_alloc;
00601         LDAP_TF_SEMA_FREE_CALLBACK *ltf_sema_free;
00602         LDAP_TF_SEMA_WAIT_CALLBACK *ltf_sema_wait;
00603         LDAP_TF_SEMA_POST_CALLBACK *ltf_sema_post;
00604         LDAP_TF_THREADID_CALLBACK *ltf_threadid_fn;
00605 };
00606 
00607 /*
00608  * Debugging level (an API extension)
00609  */
00610 #define LDAP_OPT_DEBUG_LEVEL            0x6E    /* 110 - API extension */
00611 /* On UNIX, there's only one copy of ldap_debug */
00612 /* On NT, each dll keeps its own module_ldap_debug, which */
00613 /* points to the process' ldap_debug and needs initializing after load */
00614 #ifdef _WIN32
00615 extern int              *module_ldap_debug;
00616 typedef void (*set_debug_level_fn_t)(int*);
00617 #endif
00618 
00619 #ifdef LDAP_DNS
00620 #define LDAP_OPT_DNS                    0x0C    /* 12 - API extension */
00621 #endif
00622 
00623 /*
00624  * UTF-8 routines (should these move into libnls?)
00625  */
00626 /* number of bytes in character */
00627 LDAP_API(int) LDAP_CALL ldap_utf8len( const char* );
00628 /* find next character */
00629 LDAP_API(char*) LDAP_CALL ldap_utf8next( char* );
00630 /* find previous character */
00631 LDAP_API(char*) LDAP_CALL ldap_utf8prev( char* );
00632 /* copy one character */
00633 LDAP_API(int) LDAP_CALL ldap_utf8copy( char* dst, const char* src );
00634 /* total number of characters */
00635 LDAP_API(size_t) LDAP_CALL ldap_utf8characters( const char* );
00636 /* get one UCS-4 character, and move *src to the next character */
00637 LDAP_API(unsigned long) LDAP_CALL ldap_utf8getcc( const char** src );
00638 /* UTF-8 aware strtok_r() */
00639 LDAP_API(char*) LDAP_CALL ldap_utf8strtok_r( char* src, const char* brk, char**
00640 next);
00641 
00642 /* like isalnum(*s) in the C locale */
00643 LDAP_API(int) LDAP_CALL ldap_utf8isalnum( char* s );
00644 /* like isalpha(*s) in the C locale */
00645 LDAP_API(int) LDAP_CALL ldap_utf8isalpha( char* s );
00646 /* like isdigit(*s) in the C locale */
00647 LDAP_API(int) LDAP_CALL ldap_utf8isdigit( char* s );
00648 /* like isxdigit(*s) in the C locale */
00649 LDAP_API(int) LDAP_CALL ldap_utf8isxdigit(char* s );
00650 /* like isspace(*s) in the C locale */
00651 LDAP_API(int) LDAP_CALL ldap_utf8isspace( char* s );
00652 
00653 #define LDAP_UTF8LEN(s)  ((0x80 & *(unsigned char*)(s)) ?   ldap_utf8len (s) : 1)
00654 #define LDAP_UTF8NEXT(s) ((0x80 & *(unsigned char*)(s)) ?   ldap_utf8next(s) : ( s)+1)
00655 #define LDAP_UTF8INC(s)  ((0x80 & *(unsigned char*)(s)) ? s=ldap_utf8next(s) : ++s)
00656 
00657 #define LDAP_UTF8PREV(s)   ldap_utf8prev(s)
00658 #define LDAP_UTF8DEC(s) (s=ldap_utf8prev(s))
00659 
00660 #define LDAP_UTF8COPY(d,s) ((0x80 & *(unsigned char*)(s)) ? ldap_utf8copy(d,s) : ((*(d) = *(s)), 1))
00661 #define LDAP_UTF8GETCC(s) ((0x80 & *(unsigned char*)(s)) ? ldap_utf8getcc (&s) : *s++)
00662 #define LDAP_UTF8GETC(s) ((0x80 & *(unsigned char*)(s)) ? ldap_utf8getcc ((const char**)&s) : *s++)
00663 
00664 
00665 #ifdef __cplusplus
00666 }
00667 #endif
00668 #endif /* _LDAP_EXTENSION_H */
00669