From 26421a5254f7359594b8c23e8577518be0e419d1 Mon Sep 17 00:00:00 2001
From: Ralf Haferkamp <ralf@openldap.org>
Date: Thu, 18 Feb 2010 16:23:40 +0000
Subject: [PATCH] TlsOptions documentation

---
 contrib/ldapc++/src/TlsOptions.h | 124 ++++++++++++++++++++++++++++---
 1 file changed, 114 insertions(+), 10 deletions(-)

diff --git a/contrib/ldapc++/src/TlsOptions.h b/contrib/ldapc++/src/TlsOptions.h
index f442f68ef4..0865fb240c 100644
--- a/contrib/ldapc++/src/TlsOptions.h
+++ b/contrib/ldapc++/src/TlsOptions.h
@@ -8,10 +8,24 @@
 #include <string>
 #include <ldap.h>
 
+/**
+ * Class to access the global (and connection specific) TLS Settings
+ * To access the global TLS Settings just instantiate a TlsOption object
+ * using the default constructor.
+ *
+ * To access connection specific settings instantiate a TlsOption object
+ * through the getTlsOptions() method from the corresponding
+ * LDAPConnection/LDAPAsynConnection object.
+ *
+ */
 class TlsOptions {
     public:
+
+        /**
+         * Available TLS Options
+         */
         enum tls_option {
-            CACERTFILE=0,
+            CACERTFILE=0, 
             CACERTDIR,
             CERTFILE,
             KEYFILE,
@@ -21,18 +35,14 @@ class TlsOptions {
             RANDOM_FILE,
             CRLCHECK,
             DHFILE,
+            /// @cond
             LASTOPT /* dummy */
+            /// @endcond
         };
 
-        TlsOptions();
-        void setOption(tls_option opt, const std::string& value) const;
-        void setOption(tls_option opt, int value) const;
-        void setOption(tls_option opt, void *value) const;
-
-        int getIntOption(tls_option opt) const;
-        std::string getStringOption(tls_option opt) const;
-        void getOption(tls_option opt, void *value ) const;
-        
+        /**
+         * Possible Values for the REQUIRE_CERT option
+         */
         enum verifyMode {
             NEVER=0,
             HARD,
@@ -41,12 +51,106 @@ class TlsOptions {
             TRY
         };
 
+        /**
+         * Possible Values for the CRLCHECK option
+         */
         enum crlMode {
             CRL_NONE=0,
             CRL_PEER,
             CRL_ALL
         };
 
+
+        /**
+         * Default constructor. Gives access to the global TlsSettings
+         */
+        TlsOptions();
+
+        /**
+         * Set string valued options.
+         * @param opt The following string valued options are available:
+         *      - TlsOptions::CACERTFILE 
+         *      - TlsOptions::CACERTDIR
+         *      - TlsOptions::CERTFILE
+         *      - TlsOptions::KEYFILE
+         *      - TlsOptions::CIPHER_SUITE
+         *      - TlsOptions::RANDOM_FILE
+         *      - TlsOptions::DHFILE
+         *  @param value The value to apply to that option, 
+         *      - TlsOptions::CACERTFILE:
+         *          The path to the file containing all recognized Certificate
+         *          Authorities
+         *      - TlsOptions::CACERTDIR:
+         *          The path to a directory containing individual files of all
+         *          recognized Certificate Authority certificates
+         *      - TlsOptions::CERTFILE:
+         *          The path to the client certificate
+         *      - TlsOptions::KEYFILE:
+         *          The path to the file containing the private key matching the 
+         *          Certificate that as configured with TlsOptions::CERTFILE
+         *      - TlsOptions::CIPHER_SUITE
+         *          Specifies the cipher suite and preference order
+         *      - TlsOptions::RANDOM_FILE
+         *          Specifies the file to obtain random bits from when 
+         *          /dev/[u]random is not available.
+         *      - TlsOptions::DHFILE
+         *          File containing DH parameters
+         */
+        void setOption(tls_option opt, const std::string& value) const;
+
+        /** 
+         * Set integer valued options.
+         * @param opt The following string valued options are available:
+         *      - TlsOptions::REQUIRE_CERT
+         *      - TlsOptions::PROTOCOL_MIN
+         *      - TlsOptions::CRLCHECK
+         * @param value The value to apply to that option, 
+         *      - TlsOptions::REQUIRE_CERT:
+         *          Possible Values (For details see the ldap.conf(5) man-page):
+         *              - TlsOptions::NEVER
+         *              - TlsOptions::DEMAND
+         *              - TlsOptions::ALLOW
+         *              - TlsOptions::TRY
+         *      - TlsOptions::PROTOCOL_MIN
+         *      - TlsOptions::CRLCHECK
+         *          Possible Values:
+         *              - TlsOptions::CRL_NONE
+         *              - TlsOptions::CRL_PEER
+         *              - TlsOptions::CRL_ALL
+         */
+        void setOption(tls_option opt, int value) const;
+
+        /**
+         * Generic setOption variant. Generally you should prefer to use one 
+         * of the other variants
+         */
+        void setOption(tls_option opt, void *value) const;
+
+        /**
+         * Read integer valued options
+         * @return Option value
+         * @throws LDAPException in case of error (invalid on non-integer 
+         *      valued option is requested)
+         */
+        int getIntOption(tls_option opt) const;
+
+        /**
+         * Read string valued options
+         * @return Option value
+         * @throws LDAPException in case of error (invalid on non-string 
+         *      valued option is requested)
+         */
+        std::string getStringOption(tls_option opt) const;
+
+        /**
+         * Read options value. Usually you should prefer to use either 
+         * getIntOption() or getStringOption()
+         * @param value points to a buffer containing the option value
+         * @throws LDAPException in case of error (invalid on non-string 
+         *      valued option is requested)
+         */
+        void getOption(tls_option opt, void *value ) const;
+        
     private:
         TlsOptions( LDAP* ld );
         void newCtx() const;
-- 
2.39.5