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