17c478bd9Sstevel@tonic-gate /*
2*da80a4abSjanga  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
37c478bd9Sstevel@tonic-gate  * Use is subject to license terms.
47c478bd9Sstevel@tonic-gate  */
57c478bd9Sstevel@tonic-gate 
67c478bd9Sstevel@tonic-gate /*
77c478bd9Sstevel@tonic-gate  * The contents of this file are subject to the Netscape Public
87c478bd9Sstevel@tonic-gate  * License Version 1.1 (the "License"); you may not use this file
97c478bd9Sstevel@tonic-gate  * except in compliance with the License. You may obtain a copy of
107c478bd9Sstevel@tonic-gate  * the License at http://www.mozilla.org/NPL/
117c478bd9Sstevel@tonic-gate  *
127c478bd9Sstevel@tonic-gate  * Software distributed under the License is distributed on an "AS
137c478bd9Sstevel@tonic-gate  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
147c478bd9Sstevel@tonic-gate  * implied. See the License for the specific language governing
157c478bd9Sstevel@tonic-gate  * rights and limitations under the License.
167c478bd9Sstevel@tonic-gate  *
177c478bd9Sstevel@tonic-gate  * The Original Code is Mozilla Communicator client code, released
187c478bd9Sstevel@tonic-gate  * March 31, 1998.
197c478bd9Sstevel@tonic-gate  *
207c478bd9Sstevel@tonic-gate  * The Initial Developer of the Original Code is Netscape
217c478bd9Sstevel@tonic-gate  * Communications Corporation. Portions created by Netscape are
227c478bd9Sstevel@tonic-gate  * Copyright (C) 1998-1999 Netscape Communications Corporation. All
237c478bd9Sstevel@tonic-gate  * Rights Reserved.
247c478bd9Sstevel@tonic-gate  *
257c478bd9Sstevel@tonic-gate  * Contributor(s):
267c478bd9Sstevel@tonic-gate  */
277c478bd9Sstevel@tonic-gate 
287c478bd9Sstevel@tonic-gate #ifndef LDAP_PR_H
297c478bd9Sstevel@tonic-gate #define LDAP_PR_H
307c478bd9Sstevel@tonic-gate 
317c478bd9Sstevel@tonic-gate #include "nspr.h"
327c478bd9Sstevel@tonic-gate 
337c478bd9Sstevel@tonic-gate /*
347c478bd9Sstevel@tonic-gate  * ldappr.h - prototypes for functions that tie libldap into NSPR (Netscape
357c478bd9Sstevel@tonic-gate  *	Portable Runtime).
367c478bd9Sstevel@tonic-gate  */
377c478bd9Sstevel@tonic-gate 
387c478bd9Sstevel@tonic-gate #ifdef __cplusplus
397c478bd9Sstevel@tonic-gate extern "C" {
407c478bd9Sstevel@tonic-gate #endif
417c478bd9Sstevel@tonic-gate 
427c478bd9Sstevel@tonic-gate /*
437c478bd9Sstevel@tonic-gate  * Function: prldap_init().
447c478bd9Sstevel@tonic-gate  *
457c478bd9Sstevel@tonic-gate  * Create a new LDAP session handle, but with NSPR I/O, threading, and DNS
467c478bd9Sstevel@tonic-gate  * functions installed.
477c478bd9Sstevel@tonic-gate  *
487c478bd9Sstevel@tonic-gate  * Pass a non-zero value for the 'shared' parameter if you plan to use
497c478bd9Sstevel@tonic-gate  * this LDAP * handle from more than one thread.
507c478bd9Sstevel@tonic-gate  *
517c478bd9Sstevel@tonic-gate  * Returns an LDAP session handle (or NULL if an error occurs).
527c478bd9Sstevel@tonic-gate  */
537c478bd9Sstevel@tonic-gate LDAP * LDAP_CALL prldap_init( const char *defhost, int defport, int shared );
547c478bd9Sstevel@tonic-gate 
557c478bd9Sstevel@tonic-gate 
567c478bd9Sstevel@tonic-gate /*
577c478bd9Sstevel@tonic-gate  * Function: prldap_install_routines().
587c478bd9Sstevel@tonic-gate  *
597c478bd9Sstevel@tonic-gate  * Install NSPR I/O, threading, and DNS functions so they will be used by
607c478bd9Sstevel@tonic-gate  * 'ld'.
617c478bd9Sstevel@tonic-gate  *
627c478bd9Sstevel@tonic-gate  * If 'ld' is NULL, the functions are installed as the default functions
637c478bd9Sstevel@tonic-gate  * for all new LDAP * handles).
647c478bd9Sstevel@tonic-gate  *
657c478bd9Sstevel@tonic-gate  * Pass a non-zero value for the 'shared' parameter if you plan to use
667c478bd9Sstevel@tonic-gate  * this LDAP * handle from more than one thread.
677c478bd9Sstevel@tonic-gate  *
687c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
697c478bd9Sstevel@tonic-gate  */
707c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_install_routines( LDAP *ld, int shared );
717c478bd9Sstevel@tonic-gate 
727c478bd9Sstevel@tonic-gate 
737c478bd9Sstevel@tonic-gate /*
747c478bd9Sstevel@tonic-gate  * Function: prldap_set_session_option().
757c478bd9Sstevel@tonic-gate  *
767c478bd9Sstevel@tonic-gate  * Given an LDAP session handle or a session argument such is passed to
777c478bd9Sstevel@tonic-gate  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, set
787c478bd9Sstevel@tonic-gate  * an option that affects the prldap layer.
797c478bd9Sstevel@tonic-gate  *
807c478bd9Sstevel@tonic-gate  * If 'ld' and 'session" are both NULL, the option is set as the default
817c478bd9Sstevel@tonic-gate  * for all new prldap sessions.
827c478bd9Sstevel@tonic-gate  *
837c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
847c478bd9Sstevel@tonic-gate  */
857c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_set_session_option( LDAP *ld, void *sessionarg,
867c478bd9Sstevel@tonic-gate 	int option, ... );
877c478bd9Sstevel@tonic-gate 
887c478bd9Sstevel@tonic-gate 
897c478bd9Sstevel@tonic-gate /*
907c478bd9Sstevel@tonic-gate  * Function: prldap_get_session_option().
917c478bd9Sstevel@tonic-gate  *
927c478bd9Sstevel@tonic-gate  * Given an LDAP session handle or a session argument such is passed to
937c478bd9Sstevel@tonic-gate  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks, retrieve
947c478bd9Sstevel@tonic-gate  * the setting for an option that affects the prldap layer.
957c478bd9Sstevel@tonic-gate  *
967c478bd9Sstevel@tonic-gate  * If 'ld' and 'session" are both NULL, the default option value for all new
977c478bd9Sstevel@tonic-gate  * new prldap sessions is retrieved.
987c478bd9Sstevel@tonic-gate  *
997c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
1007c478bd9Sstevel@tonic-gate  */
1017c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_get_session_option( LDAP *ld, void *sessionarg,
1027c478bd9Sstevel@tonic-gate 	int option, ... );
1037c478bd9Sstevel@tonic-gate 
1047c478bd9Sstevel@tonic-gate 
1057c478bd9Sstevel@tonic-gate 
1067c478bd9Sstevel@tonic-gate /*
1077c478bd9Sstevel@tonic-gate  * Available options.
1087c478bd9Sstevel@tonic-gate  */
1097c478bd9Sstevel@tonic-gate /*
1107c478bd9Sstevel@tonic-gate  * PRLDAP_OPT_IO_MAX_TIMEOUT: set the maximum time in milliseconds to
1117c478bd9Sstevel@tonic-gate  * block waiting for a network I/O operation to complete.
1127c478bd9Sstevel@tonic-gate  *
1137c478bd9Sstevel@tonic-gate  * Data type: int.
1147c478bd9Sstevel@tonic-gate  *
1157c478bd9Sstevel@tonic-gate  * These two special values from ldap-extension.h can also be used;
1167c478bd9Sstevel@tonic-gate  *
1177c478bd9Sstevel@tonic-gate  *    LDAP_X_IO_TIMEOUT_NO_TIMEOUT
1187c478bd9Sstevel@tonic-gate  *    LDAP_X_IO_TIMEOUT_NO_WAIT
1197c478bd9Sstevel@tonic-gate  */
1207c478bd9Sstevel@tonic-gate #define PRLDAP_OPT_IO_MAX_TIMEOUT		1
1217c478bd9Sstevel@tonic-gate 
1227c478bd9Sstevel@tonic-gate 
1237c478bd9Sstevel@tonic-gate /**
1247c478bd9Sstevel@tonic-gate  ** Note: the types and functions below are only useful for developers
1257c478bd9Sstevel@tonic-gate  ** who need to layer one or more custom extended I/O functions on top of
1267c478bd9Sstevel@tonic-gate  ** the standard NSPR I/O functions installed by a call to prldap_init()
1277c478bd9Sstevel@tonic-gate  ** or prldap_install_routines().  Layering can be accomplished after
1287c478bd9Sstevel@tonic-gate  ** prldap_init() or prldap_install_routines() has completed successfully
1297c478bd9Sstevel@tonic-gate  ** by:
1307c478bd9Sstevel@tonic-gate  **
1317c478bd9Sstevel@tonic-gate  **   1) Calling ldap_get_option( ..., LDAP_X_OPT_EXTIO_FN_PTRS, ... ).
1327c478bd9Sstevel@tonic-gate  **
1337c478bd9Sstevel@tonic-gate  **   2) Saving the function pointer of one or more of the standard functions.
1347c478bd9Sstevel@tonic-gate  **
1357c478bd9Sstevel@tonic-gate  **   3) Replacing one or more standard functions in the ldap_x_ext_io_fns
1367c478bd9Sstevel@tonic-gate  **      struct	with new functions that optionally do some preliminary work,
1377c478bd9Sstevel@tonic-gate  **      call the standard function (via the function pointer saved in step 2),
1387c478bd9Sstevel@tonic-gate  **      and optionally do some followup work.
1397c478bd9Sstevel@tonic-gate  */
1407c478bd9Sstevel@tonic-gate 
1417c478bd9Sstevel@tonic-gate /*
1427c478bd9Sstevel@tonic-gate  * Data structure for session information.
1437c478bd9Sstevel@tonic-gate  * seinfo_size should be set to PRLDAP_SESSIONINFO_SIZE before use.
1447c478bd9Sstevel@tonic-gate  */
1457c478bd9Sstevel@tonic-gate struct prldap_session_private;
1467c478bd9Sstevel@tonic-gate 
1477c478bd9Sstevel@tonic-gate typedef struct prldap_session_info {
1487c478bd9Sstevel@tonic-gate 	int				seinfo_size;
1497c478bd9Sstevel@tonic-gate 	struct prldap_session_private	*seinfo_appdata;
1507c478bd9Sstevel@tonic-gate } PRLDAPSessionInfo;
1517c478bd9Sstevel@tonic-gate #define PRLDAP_SESSIONINFO_SIZE	sizeof( PRLDAPSessionInfo )
1527c478bd9Sstevel@tonic-gate 
1537c478bd9Sstevel@tonic-gate 
1547c478bd9Sstevel@tonic-gate /*
1557c478bd9Sstevel@tonic-gate  * Function: prldap_set_session_info().
1567c478bd9Sstevel@tonic-gate  *
1577c478bd9Sstevel@tonic-gate  * Given an LDAP session handle or a session argument such is passed to
1587c478bd9Sstevel@tonic-gate  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
1597c478bd9Sstevel@tonic-gate  * set some application-specific data.  If ld is NULL, arg is used.  If
1607c478bd9Sstevel@tonic-gate  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
1617c478bd9Sstevel@tonic-gate  *
1627c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
1637c478bd9Sstevel@tonic-gate  */
1647c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_set_session_info( LDAP *ld, void *sessionarg,
1657c478bd9Sstevel@tonic-gate 	PRLDAPSessionInfo *seip );
1667c478bd9Sstevel@tonic-gate 
1677c478bd9Sstevel@tonic-gate 
1687c478bd9Sstevel@tonic-gate /*
1697c478bd9Sstevel@tonic-gate  * Function: prldap_get_session_info().
1707c478bd9Sstevel@tonic-gate  *
1717c478bd9Sstevel@tonic-gate  * Given an LDAP session handle or a session argument such is passed to
1727c478bd9Sstevel@tonic-gate  * CONNECT, POLL, NEWHANDLE, or DISPOSEHANDLE extended I/O callbacks,
1737c478bd9Sstevel@tonic-gate  * retrieve some application-specific data.  If ld is NULL, arg is used.  If
1747c478bd9Sstevel@tonic-gate  * both ld and arg are NULL, LDAP_PARAM_ERROR is returned.
1757c478bd9Sstevel@tonic-gate  *
1767c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
1777c478bd9Sstevel@tonic-gate  * which case the fields in the structure that seip points to are filled in).
1787c478bd9Sstevel@tonic-gate  */
1797c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_get_session_info( LDAP *ld, void *sessionarg,
1807c478bd9Sstevel@tonic-gate 	PRLDAPSessionInfo *seip );
1817c478bd9Sstevel@tonic-gate 
1827c478bd9Sstevel@tonic-gate 
1837c478bd9Sstevel@tonic-gate /*
1847c478bd9Sstevel@tonic-gate  * Data structure for socket specific information.
1857c478bd9Sstevel@tonic-gate  * Note: soinfo_size should be set to PRLDAP_SOCKETINFO_SIZE before use.
1867c478bd9Sstevel@tonic-gate  */
1877c478bd9Sstevel@tonic-gate struct prldap_socket_private;
1887c478bd9Sstevel@tonic-gate typedef struct prldap_socket_info {
1897c478bd9Sstevel@tonic-gate 	int				soinfo_size;
1907c478bd9Sstevel@tonic-gate 	PRFileDesc			*soinfo_prfd;
1917c478bd9Sstevel@tonic-gate 	struct prldap_socket_private	*soinfo_appdata;
1927c478bd9Sstevel@tonic-gate } PRLDAPSocketInfo;
1937c478bd9Sstevel@tonic-gate #define PRLDAP_SOCKETINFO_SIZE	sizeof( PRLDAPSocketInfo )
1947c478bd9Sstevel@tonic-gate 
1957c478bd9Sstevel@tonic-gate 
1967c478bd9Sstevel@tonic-gate /*
1977c478bd9Sstevel@tonic-gate  * Function: prldap_set_socket_info().
1987c478bd9Sstevel@tonic-gate  *
1997c478bd9Sstevel@tonic-gate  * Given an integer fd and a socket argument such as those passed to the
2007c478bd9Sstevel@tonic-gate  * extended I/O callback functions, set socket specific information.
2017c478bd9Sstevel@tonic-gate  *
2027c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well).
2037c478bd9Sstevel@tonic-gate  *
2047c478bd9Sstevel@tonic-gate  * Note: it is only safe to change soinfo_prfd from within the SOCKET
2057c478bd9Sstevel@tonic-gate  * extended I/O callback function.
2067c478bd9Sstevel@tonic-gate  */
2077c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_set_socket_info( int fd, void *socketarg,
2087c478bd9Sstevel@tonic-gate 					PRLDAPSocketInfo *soip );
2097c478bd9Sstevel@tonic-gate 
2107c478bd9Sstevel@tonic-gate /*
2117c478bd9Sstevel@tonic-gate  * Function: prldap_get_socket_info().
2127c478bd9Sstevel@tonic-gate  *
2137c478bd9Sstevel@tonic-gate  * Given an integer fd and a socket argument such as those passed to the
2147c478bd9Sstevel@tonic-gate  * extended I/O callback functions, retrieve socket specific information.
2157c478bd9Sstevel@tonic-gate  *
2167c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
2177c478bd9Sstevel@tonic-gate  * which case the fields in the structure that soip points to are filled in).
2187c478bd9Sstevel@tonic-gate  */
2197c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_get_socket_info( int fd, void *socketarg,
2207c478bd9Sstevel@tonic-gate 					PRLDAPSocketInfo *soip );
2217c478bd9Sstevel@tonic-gate 
2227c478bd9Sstevel@tonic-gate /*
2237c478bd9Sstevel@tonic-gate  * Function: prldap_get_default_socket_info().
2247c478bd9Sstevel@tonic-gate  *
2257c478bd9Sstevel@tonic-gate  * Given an LDAP session handle, retrieve socket specific information.
2267c478bd9Sstevel@tonic-gate  * If ld is NULL, LDAP_PARAM_ERROR is returned.
2277c478bd9Sstevel@tonic-gate  *
2287c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
2297c478bd9Sstevel@tonic-gate  * which case the fields in the structure that soip points to are filled in).
2307c478bd9Sstevel@tonic-gate  */
2317c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );
2327c478bd9Sstevel@tonic-gate 
2337c478bd9Sstevel@tonic-gate /*
2347c478bd9Sstevel@tonic-gate  * Function: prldap_set_default_socket_info().
2357c478bd9Sstevel@tonic-gate  *
2367c478bd9Sstevel@tonic-gate  * Given an LDAP session handle, set socket specific information.
2377c478bd9Sstevel@tonic-gate  * If ld is NULL, LDAP_PARAM_ERROR is returned.
2387c478bd9Sstevel@tonic-gate  *
2397c478bd9Sstevel@tonic-gate  * Returns an LDAP API error code (LDAP_SUCCESS if all goes well, in
2407c478bd9Sstevel@tonic-gate  * which case the fields in the structure that soip points to are filled in).
2417c478bd9Sstevel@tonic-gate  */
2427c478bd9Sstevel@tonic-gate int LDAP_CALL prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );
2437c478bd9Sstevel@tonic-gate 
2447c478bd9Sstevel@tonic-gate #ifdef __cplusplus
2457c478bd9Sstevel@tonic-gate }
2467c478bd9Sstevel@tonic-gate #endif
2477c478bd9Sstevel@tonic-gate #endif /* !defined(LDAP_PR_H) */
248