Back to index

lightning-sunbird  0.9+nobinonly
ldappr.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 #ifndef LDAP_PR_H
00039 #define LDAP_PR_H
00040 
00041 #include "nspr.h"
00042 
00043 /*
00044  * ldappr.h - prototypes for functions that tie libldap into NSPR (Netscape
00045  *     Portable Runtime).
00046  */
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 /*
00053  * Function: prldap_init().
00054  *
00055  * Create a new LDAP session handle, but with NSPR I/O, threading, and DNS
00056  * functions installed.
00057  *
00058  * Pass a non-zero value for the 'shared' parameter if you plan to use
00059  * this LDAP * handle from more than one thread.
00060  *
00061  * Returns an LDAP session handle (or NULL if an error occurs).
00062  *
00063  * NOTE: If you want to use IPv6, you must use prldap creating a LDAP handle
00064  * with this function prldap_init.  Prldap_init installs the appropriate
00065  * set of NSPR functions and prevents calling deprecated functions accidentally.
00066  */
00067 LDAP * LDAP_CALL prldap_init( const char *defhost, int defport, int shared );
00068 
00069 
00070 /*
00071  * Function: prldap_install_routines().
00072  *
00073  * Install NSPR I/O, threading, and DNS functions so they will be used by
00074  * 'ld'.
00075  *
00076  * If 'ld' is NULL, the functions are installed as the default functions
00077  * for all new LDAP * handles).
00078  *
00079  * Pass a non-zero value for the 'shared' parameter if you plan to use
00080  * this LDAP * handle from more than one thread.
00081  *
00082  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
00083  */
00084 int LDAP_CALL prldap_install_routines( LDAP *ld, int shared );
00085 
00086 
00087 /*
00088  * Function: prldap_set_session_option().
00089  *
00090  * Given an LDAP session handle or a session argument such is passed to
00091  * SOCKET, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, set
00092  * an option that affects the prldap layer.
00093  *
00094  * If 'ld' and 'session" are both NULL, the option is set as the default
00095  * for all new prldap sessions.
00096  *
00097  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
00098  */
00099 int LDAP_CALL prldap_set_session_option( LDAP *ld, void *sessionarg,
00100        int option, ... );
00101 
00102 
00103 /*
00104  * Function: prldap_get_session_option().
00105  *
00106  * Given an LDAP session handle or a session argument such is passed to
00107  * SOCKET, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, retrieve
00108  * the setting for an option that affects the prldap layer.
00109  *
00110  * If 'ld' and 'session" are both NULL, the default option value for all new
00111  * new prldap sessions is retrieved.
00112  *
00113  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
00114  */
00115 int LDAP_CALL prldap_get_session_option( LDAP *ld, void *sessionarg,
00116        int option, ... );
00117 
00118 
00119 /*
00120  * Available options.
00121  */
00122 /*
00123  * PRLDAP_OPT_IO_MAX_TIMEOUT: set the maximum time in milliseconds to
00124  * block waiting for a network I/O operation to complete.
00125  *
00126  * Data type: int.
00127  *
00128  * These two special values from ldap-extension.h can also be used;
00129  *
00130  *    LDAP_X_IO_TIMEOUT_NO_TIMEOUT
00131  *    LDAP_X_IO_TIMEOUT_NO_WAIT
00132  */
00133 #define PRLDAP_OPT_IO_MAX_TIMEOUT         1
00134 
00135 
00154 /*
00155  * Data structure for session information.
00156  * seinfo_size should be set to PRLDAP_SESSIONINFO_SIZE before use.
00157  */
00158 struct prldap_session_private;
00159 
00160 typedef struct prldap_session_info {
00161        int                         seinfo_size;
00162        struct prldap_session_private      *seinfo_appdata;
00163 } PRLDAPSessionInfo;
00164 #define PRLDAP_SESSIONINFO_SIZE    sizeof( PRLDAPSessionInfo )
00165 
00166 
00167 /*
00168  * Function: prldap_set_session_info().
00169  *
00170  * Given an LDAP session handle or a session argument such is passed to
00171  * SOCKET, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
00172  * set some application-specific data.  If ld is NULL, arg is used.  If
00173  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
00174  *
00175  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
00176  */
00177 int LDAP_CALL prldap_set_session_info( LDAP *ld, void *sessionarg,
00178        PRLDAPSessionInfo *seip );
00179 
00180 
00181 /*
00182  * Function: prldap_get_session_info().
00183  *
00184  * Given an LDAP session handle or a session argument such is passed to
00185  * SOCKET, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
00186  * retrieve some application-specific data.  If ld is NULL, arg is used.  If
00187  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
00188  *
00189  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
00190  * which case the fields in the structure that seip points to are filled in).
00191  */
00192 int LDAP_CALL prldap_get_session_info( LDAP *ld, void *sessionarg,
00193        PRLDAPSessionInfo *seip );
00194 
00195 
00196 /*
00197  * Data structure for socket specific information.
00198  * Note: soinfo_size should be set to PRLDAP_SOCKETINFO_SIZE before use.
00199  */
00200 struct prldap_socket_private;
00201 typedef struct prldap_socket_info {
00202        int                         soinfo_size;
00203        PRFileDesc                  *soinfo_prfd;
00204        struct prldap_socket_private       *soinfo_appdata;
00205 } PRLDAPSocketInfo;
00206 #define PRLDAP_SOCKETINFO_SIZE     sizeof( PRLDAPSocketInfo )
00207 
00208 
00209 /*
00210  * Function: prldap_set_socket_info().
00211  *
00212  * Given an integer fd and a socket argument such as those passed to the
00213  * extended I/O callback functions, set socket specific information.
00214  *
00215  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
00216  *
00217  * Note: it is only safe to change soinfo_prfd from within the SOCKET
00218  * extended I/O callback function.
00219  */
00220 int LDAP_CALL prldap_set_socket_info( int fd, void *socketarg,
00221                                    PRLDAPSocketInfo *soip );
00222 
00223 /*
00224  * Function: prldap_get_socket_info().
00225  *
00226  * Given an integer fd and a socket argument such as those passed to the
00227  * extended I/O callback functions, retrieve socket specific information.
00228  *
00229  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
00230  * which case the fields in the structure that soip points to are filled in).
00231  */
00232 int LDAP_CALL prldap_get_socket_info( int fd, void *socketarg,
00233                                    PRLDAPSocketInfo *soip );
00234 
00235 #ifdef __cplusplus
00236 }
00237 #endif
00238 #endif /* !defined(LDAP_PR_H) */