usr/src/lib/libldap5/include/ldap/ldappr.h

   1 /*
   2  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
   3  * Use is subject to license terms.
   4  */
   5
   6 #pragma ident   "%Z%%M% %I%     %E% SMI"
   7
   8 /*
   9  * The contents of this file are subject to the Netscape Public
  10  * License Version 1.1 (the "License"); you may not use this file
  11  * except in compliance with the License. You may obtain a copy of
  12  * the License at http://www.mozilla.org/NPL/
  13  *
  14  * Software distributed under the License is distributed on an "AS
  15  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  16  * implied. See the License for the specific language governing
  17  * rights and limitations under the License.
  18  *
  19  * The Original Code is Mozilla Communicator client code, released
  20  * March 31, 1998.
  21  *
  22  * The Initial Developer of the Original Code is Netscape
  23  * Communications Corporation. Portions created by Netscape are
  24  * Copyright (C) 1998-1999 Netscape Communications Corporation. All
  25  * Rights Reserved.
  26  *
  27  * Contributor(s):
  28  */
  29
  30 #ifndef LDAP_PR_H
  31 #define LDAP_PR_H
  32
  33 #include "nspr.h"
  34
  35 /*
  36  * ldappr.h - prototypes for functions that tie libldap into NSPR (Netscape
  37  *      Portable Runtime).
  38  */
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /*
  45  * Function: prldap_init().
  46  *
  47  * Create a new LDAP session handle, but with NSPR I/O, threading, and DNS
  48  * functions installed.
  49  *
  50  * Pass a non-zero value for the 'shared' parameter if you plan to use
  51  * this LDAP * handle from more than one thread.
  52  *
  53  * Returns an LDAP session handle (or NULL if an error occurs).
  54  */
  55 LDAP * LDAP_CALL prldap_init( const char *defhost, int defport, int shared );
  56
  57
  58 /*
  59  * Function: prldap_install_routines().
  60  *
  61  * Install NSPR I/O, threading, and DNS functions so they will be used by
  62  * 'ld'.
  63  *
  64  * If 'ld' is NULL, the functions are installed as the default functions
  65  * for all new LDAP * handles).
  66  *
  67  * Pass a non-zero value for the 'shared' parameter if you plan to use
  68  * this LDAP * handle from more than one thread.
  69  *
  70  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
  71  */
  72 int LDAP_CALL prldap_install_routines( LDAP *ld, int shared );
  73
  74
  75 /*
  76  * Function: prldap_set_session_option().
  77  *
  78  * Given an LDAP session handle or a session argument such is passed to
  79  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, set
  80  * an option that affects the prldap layer.
  81  *
  82  * If 'ld' and 'session" are both NULL, the option is set as the default
  83  * for all new prldap sessions.
  84  *
  85  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
  86  */
  87 int LDAP_CALL prldap_set_session_option( LDAP *ld, void *sessionarg,
  88         int option, ... );
  89
  90
  91 /*
  92  * Function: prldap_get_session_option().
  93  *
  94  * Given an LDAP session handle or a session argument such is passed to
  95  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, retrieve
  96  * the setting for an option that affects the prldap layer.
  97  *
  98  * If 'ld' and 'session" are both NULL, the default option value for all new
  99  * new prldap sessions is retrieved.
 100  *
 101  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
 102  */
 103 int LDAP_CALL prldap_get_session_option( LDAP *ld, void *sessionarg,
 104         int option, ... );
 105
 106
 107
 108 /*
 109  * Available options.
 110  */
 111 /*
 112  * PRLDAP_OPT_IO_MAX_TIMEOUT: set the maximum time in milliseconds to
 113  * block waiting for a network I/O operation to complete.
 114  *
 115  * Data type: int.
 116  *
 117  * These two special values from ldap-extension.h can also be used;
 118  *
 119  *    LDAP_X_IO_TIMEOUT_NO_TIMEOUT
 120  *    LDAP_X_IO_TIMEOUT_NO_WAIT
 121  */
 122 #define PRLDAP_OPT_IO_MAX_TIMEOUT               1
 123
 124
 125 /**
 126  ** Note: the types and functions below are only useful for developers
 127  ** who need to layer one or more custom extended I/O functions on top of
 128  ** the standard NSPR I/O functions installed by a call to prldap_init()
 129  ** or prldap_install_routines().  Layering can be accomplished after
 130  ** prldap_init() or prldap_install_routines() has completed successfully
 131  ** by:
 132  **
 133  **   1) Calling ldap_get_option( ..., LDAP_X_OPT_EXTIO_FN_PTRS, ... ).
 134  **
 135  **   2) Saving the function pointer of one or more of the standard functions.
 136  **
 137  **   3) Replacing one or more standard functions in the ldap_x_ext_io_fns
 138  **      struct with new functions that optionally do some preliminary work,
 139  **      call the standard function (via the function pointer saved in step 2),
 140  **      and optionally do some followup work.
 141  */
 142
 143 /*
 144  * Data structure for session information.
 145  * seinfo_size should be set to PRLDAP_SESSIONINFO_SIZE before use.
 146  */
 147 struct prldap_session_private;
 148
 149 typedef struct prldap_session_info {
 150         int                             seinfo_size;
 151         struct prldap_session_private   *seinfo_appdata;
 152 } PRLDAPSessionInfo;
 153 #define PRLDAP_SESSIONINFO_SIZE sizeof( PRLDAPSessionInfo )
 154
 155
 156 /*
 157  * Function: prldap_set_session_info().
 158  *
 159  * Given an LDAP session handle or a session argument such is passed to
 160  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
 161  * set some application-specific data.  If ld is NULL, arg is used.  If
 162  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
 163  *
 164  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
 165  */
 166 int LDAP_CALL prldap_set_session_info( LDAP *ld, void *sessionarg,
 167         PRLDAPSessionInfo *seip );
 168
 169
 170 /*
 171  * Function: prldap_get_session_info().
 172  *
 173  * Given an LDAP session handle or a session argument such is passed to
 174  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
 175  * retrieve some application-specific data.  If ld is NULL, arg is used.  If
 176  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
 177  *
 178  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
 179  * which case the fields in the structure that seip points to are filled in).
 180  */
 181 int LDAP_CALL prldap_get_session_info( LDAP *ld, void *sessionarg,
 182         PRLDAPSessionInfo *seip );
 183
 184
 185 /*
 186  * Data structure for socket specific information.
 187  * Note: soinfo_size should be set to PRLDAP_SOCKETINFO_SIZE before use.
 188  */
 189 struct prldap_socket_private;
 190 typedef struct prldap_socket_info {
 191         int                             soinfo_size;
 192         PRFileDesc                      *soinfo_prfd;
 193         struct prldap_socket_private    *soinfo_appdata;
 194 } PRLDAPSocketInfo;
 195 #define PRLDAP_SOCKETINFO_SIZE  sizeof( PRLDAPSocketInfo )
 196
 197
 198 /*
 199  * Function: prldap_set_socket_info().
 200  *
 201  * Given an integer fd and a socket argument such as those passed to the
 202  * extended I/O callback functions, set socket specific information.
 203  *
 204  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
 205  *
 206  * Note: it is only safe to change soinfo_prfd from within the SOCKET
 207  * extended I/O callback function.
 208  */
 209 int LDAP_CALL prldap_set_socket_info( int fd, void *socketarg,
 210                                         PRLDAPSocketInfo *soip );
 211
 212 /*
 213  * Function: prldap_get_socket_info().
 214  *
 215  * Given an integer fd and a socket argument such as those passed to the
 216  * extended I/O callback functions, retrieve socket specific information.
 217  *
 218  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
 219  * which case the fields in the structure that soip points to are filled in).
 220  */
 221 int LDAP_CALL prldap_get_socket_info( int fd, void *socketarg,
 222                                         PRLDAPSocketInfo *soip );
 223
 224 /*
 225  * Function: prldap_get_default_socket_info().
 226  *
 227  * Given an LDAP session handle, retrieve socket specific information.
 228  * If ld is NULL, LDAP_PARAM_ERROR is returned.
 229  *
 230  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
 231  * which case the fields in the structure that soip points to are filled in).
 232  */
 233 int LDAP_CALL prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );
 234
 235 /*
 236  * Function: prldap_set_default_socket_info().
 237  *
 238  * Given an LDAP session handle, set socket specific information.
 239  * If ld is NULL, LDAP_PARAM_ERROR is returned.
 240  *
 241  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
 242  * which case the fields in the structure that soip points to are filled in).
 243  */
 244 int LDAP_CALL prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );
 245
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249 #endif /* !defined(LDAP_PR_H) */