apr_ldap_init.h

Go to the documentation of this file.
00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as
00002  * applicable.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * @file apr_ldap_init.h
00019  * @brief  APR-UTIL LDAP ldap_init() functions
00020  */
00021 #ifndef APR_LDAP_INIT_H
00022 #define APR_LDAP_INIT_H
00023 
00024 /**
00025  * @defgroup APR_Util_LDAP LDAP
00026  * @ingroup APR_Util
00027  * @{
00028  */
00029 
00030 #include "apr_ldap.h"
00031 
00032 #if APR_HAS_LDAP
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif /* __cplusplus */
00037 
00038 /**
00039  * APR LDAP SSL Initialise function
00040  *
00041  * This function initialises SSL on the underlying LDAP toolkit
00042  * if this is necessary.
00043  *
00044  * If a CA certificate is provided, this is set, however the setting
00045  * of certificates via this method has been deprecated and will be removed in
00046  * APR v2.0.
00047  *
00048  * The apr_ldap_set_option() function with the APR_LDAP_OPT_TLS_CERT option
00049  * should be used instead to set certificates.
00050  *
00051  * If SSL support is not available on this platform, or a problem
00052  * was encountered while trying to set the certificate, the function
00053  * will return APR_EGENERAL. Further LDAP specific error information
00054  * can be found in result_err.
00055  * @param pool The pool to use
00056  * @param cert_auth_file The name of the certificate to use, can be NULL
00057  * @param cert_file_type The type of certificate specified. See the
00058  * apr_ldap_set_option() APR_LDAP_OPT_TLS_CERT option for details.
00059  * @param result_err The returned result
00060  */
00061 APU_DECLARE(int) apr_ldap_ssl_init(apr_pool_t *pool,
00062                                    const char *cert_auth_file,
00063                                    int cert_file_type,
00064                                    apr_ldap_err_t **result_err);
00065 
00066 /**
00067  * APR LDAP SSL De-Initialise function
00068  *
00069  * This function tears down any SSL certificate setup previously
00070  * set using apr_ldap_ssl_init(). It should be called to clean
00071  * up if a graceful restart of a service is attempted.
00072  * @todo currently we do not check whether apr_ldap_ssl_init()
00073  * has been called first - we probably should.
00074  */
00075 APU_DECLARE(int) apr_ldap_ssl_deinit(void);
00076 
00077 /**
00078  * APR LDAP initialise function
00079  *
00080  * This function is responsible for initialising an LDAP
00081  * connection in a toolkit independant way. It does the
00082  * job of ldap_init() from the C api.
00083  *
00084  * It handles both the SSL and non-SSL case, and attempts
00085  * to hide the complexity setup from the user. This function
00086  * assumes that any certificate setup necessary has already
00087  * been done.
00088  *
00089  * If SSL or STARTTLS needs to be enabled, and the underlying
00090  * toolkit supports it, the following values are accepted for
00091  * secure:
00092  *
00093  * APR_LDAP_NONE: No encryption
00094  * APR_LDAP_SSL: SSL encryption (ldaps://)
00095  * APR_LDAP_STARTTLS: Force STARTTLS on ldap://
00096  * @remark The Novell toolkit is only able to set the SSL mode via this
00097  * function. To work around this limitation, set the SSL mode here if no
00098  * per connection client certificates are present, otherwise set secure
00099  * APR_LDAP_NONE here, then set the per connection client certificates,
00100  * followed by setting the SSL mode via apr_ldap_set_option(). As Novell
00101  * does not support per connection client certificates, this problem is
00102  * worked around while still being compatible with other LDAP toolkits.
00103  * @param pool The pool to use
00104  * @param ldap The LDAP handle
00105  * @param hostname The name of the host to connect to. This can be either a
00106  * DNS name, or an IP address.
00107  * @param portno The port to connect to
00108  * @param secure The security mode to set
00109  * @param result_err The returned result
00110  */
00111 APU_DECLARE(int) apr_ldap_init(apr_pool_t *pool,
00112                                LDAP **ldap,
00113                                const char *hostname,
00114                                int portno,
00115                                int secure,
00116                                apr_ldap_err_t **result_err);
00117 
00118 /**
00119  * APR LDAP info function
00120  *
00121  * This function returns a string describing the LDAP toolkit
00122  * currently in use. The string is placed inside result_err->reason.
00123  * @param pool The pool to use
00124  * @param result_err The returned result
00125  */
00126 APU_DECLARE(int) apr_ldap_info(apr_pool_t *pool,
00127                                apr_ldap_err_t **result_err);
00128 
00129 #ifdef __cplusplus
00130 }
00131 #endif
00132 
00133 #endif /* APR_HAS_LDAP */
00134 
00135 /** @} */
00136 
00137 #endif /* APR_LDAP_URL_H */

Generated on Tue Aug 21 21:34:15 2007 for Apache Portable Runtime by  doxygen 1.5.2