xref: /illumos-gate/usr/src/lib/libldap5/include/ldap/ldappr.h (revision 1da57d551424de5a9d469760be7c4b4d4f10a755)
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