1 /* 2 * Copyright 2002 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 #ifndef _SOLARIS_SDK /* Not used, left in to stay in sync with iplanet */ 76 /* 77 * Function: prldap_set_session_option(). 78 * 79 * Given an LDAP session handle or a session argument such is passed to 80 * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, set 81 * an option that affects the prldap layer. 82 * 83 * If 'ld' and 'session" are both NULL, the option is set as the default 84 * for all new prldap sessions. 85 * 86 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well). 87 */ 88 int LDAP_CALL prldap_set_session_option( LDAP *ld, void *sessionarg, 89 int option, ... ); 90 91 92 /* 93 * Function: prldap_get_session_option(). 94 * 95 * Given an LDAP session handle or a session argument such is passed to 96 * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, retrieve 97 * the setting for an option that affects the prldap layer. 98 * 99 * If 'ld' and 'session" are both NULL, the default option value for all new 100 * new prldap sessions is retrieved. 101 * 102 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well). 103 */ 104 int LDAP_CALL prldap_get_session_option( LDAP *ld, void *sessionarg, 105 int option, ... ); 106 107 108 109 /* 110 * Available options. 111 */ 112 /* 113 * PRLDAP_OPT_IO_MAX_TIMEOUT: set the maximum time in milliseconds to 114 * block waiting for a network I/O operation to complete. 115 * 116 * Data type: int. 117 * 118 * These two special values from ldap-extension.h can also be used; 119 * 120 * LDAP_X_IO_TIMEOUT_NO_TIMEOUT 121 * LDAP_X_IO_TIMEOUT_NO_WAIT 122 */ 123 #define PRLDAP_OPT_IO_MAX_TIMEOUT 1 124 #endif /* !_SOLARIS_SDK */ 125 126 127 /** 128 ** Note: the types and functions below are only useful for developers 129 ** who need to layer one or more custom extended I/O functions on top of 130 ** the standard NSPR I/O functions installed by a call to prldap_init() 131 ** or prldap_install_routines(). Layering can be accomplished after 132 ** prldap_init() or prldap_install_routines() has completed successfully 133 ** by: 134 ** 135 ** 1) Calling ldap_get_option( ..., LDAP_X_OPT_EXTIO_FN_PTRS, ... ). 136 ** 137 ** 2) Saving the function pointer of one or more of the standard functions. 138 ** 139 ** 3) Replacing one or more standard functions in the ldap_x_ext_io_fns 140 ** struct with new functions that optionally do some preliminary work, 141 ** call the standard function (via the function pointer saved in step 2), 142 ** and optionally do some followup work. 143 */ 144 145 /* 146 * Data structure for session information. 147 * seinfo_size should be set to PRLDAP_SESSIONINFO_SIZE before use. 148 */ 149 struct prldap_session_private; 150 151 typedef struct prldap_session_info { 152 int seinfo_size; 153 struct prldap_session_private *seinfo_appdata; 154 } PRLDAPSessionInfo; 155 #define PRLDAP_SESSIONINFO_SIZE sizeof( PRLDAPSessionInfo ) 156 157 158 /* 159 * Function: prldap_set_session_info(). 160 * 161 * Given an LDAP session handle or a session argument such is passed to 162 * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, 163 * set some application-specific data. If ld is NULL, arg is used. If 164 * both ld and arg are NULL, LDAP_PARAM_ERROR is returned. 165 * 166 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well). 167 */ 168 int LDAP_CALL prldap_set_session_info( LDAP *ld, void *sessionarg, 169 PRLDAPSessionInfo *seip ); 170 171 172 /* 173 * Function: prldap_get_session_info(). 174 * 175 * Given an LDAP session handle or a session argument such is passed to 176 * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, 177 * retrieve some application-specific data. If ld is NULL, arg is used. If 178 * both ld and arg are NULL, LDAP_PARAM_ERROR is returned. 179 * 180 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in 181 * which case the fields in the structure that seip points to are filled in). 182 */ 183 int LDAP_CALL prldap_get_session_info( LDAP *ld, void *sessionarg, 184 PRLDAPSessionInfo *seip ); 185 186 187 /* 188 * Data structure for socket specific information. 189 * Note: soinfo_size should be set to PRLDAP_SOCKETINFO_SIZE before use. 190 */ 191 struct prldap_socket_private; 192 typedef struct prldap_socket_info { 193 int soinfo_size; 194 PRFileDesc *soinfo_prfd; 195 struct prldap_socket_private *soinfo_appdata; 196 } PRLDAPSocketInfo; 197 #define PRLDAP_SOCKETINFO_SIZE sizeof( PRLDAPSocketInfo ) 198 199 200 /* 201 * Function: prldap_set_socket_info(). 202 * 203 * Given an integer fd and a socket argument such as those passed to the 204 * extended I/O callback functions, set socket specific information. 205 * 206 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well). 207 * 208 * Note: it is only safe to change soinfo_prfd from within the SOCKET 209 * extended I/O callback function. 210 */ 211 int LDAP_CALL prldap_set_socket_info( int fd, void *socketarg, 212 PRLDAPSocketInfo *soip ); 213 214 /* 215 * Function: prldap_get_socket_info(). 216 * 217 * Given an integer fd and a socket argument such as those passed to the 218 * extended I/O callback functions, retrieve socket specific information. 219 * 220 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in 221 * which case the fields in the structure that soip points to are filled in). 222 */ 223 int LDAP_CALL prldap_get_socket_info( int fd, void *socketarg, 224 PRLDAPSocketInfo *soip ); 225 226 /* 227 * Function: prldap_get_default_socket_info(). 228 * 229 * Given an LDAP session handle, retrieve socket specific information. 230 * If ld is NULL, LDAP_PARAM_ERROR is returned. 231 * 232 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in 233 * which case the fields in the structure that soip points to are filled in). 234 */ 235 int LDAP_CALL prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip ); 236 237 /* 238 * Function: prldap_set_default_socket_info(). 239 * 240 * Given an LDAP session handle, set socket specific information. 241 * If ld is NULL, LDAP_PARAM_ERROR is returned. 242 * 243 * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in 244 * which case the fields in the structure that soip points to are filled in). 245 */ 246 int LDAP_CALL prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip ); 247 248 #ifdef __cplusplus 249 } 250 #endif 251 #endif /* !defined(LDAP_PR_H) */ 252