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