xref: /titanic_50/usr/src/lib/libldap5/include/ldap/ldappr.h (revision 3d729aecc03ea6ebb9bd5d56b8dccd24f57daa41)
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