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