From: Ralf Haferkamp Date: Mon, 19 Feb 2001 11:34:28 +0000 (+0000) Subject: - some minor bugfixes X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~1506 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=32671aa898feee3ca88b82a006e422af12472aa8;p=openldap - some minor bugfixes - lots of documentation (javadoc style comments) --- diff --git a/contrib/ldapc++/src/LDAPAsynConnection.cpp b/contrib/ldapc++/src/LDAPAsynConnection.cpp index 1f754e5152..9638717a0f 100644 --- a/contrib/ldapc++/src/LDAPAsynConnection.cpp +++ b/contrib/ldapc++/src/LDAPAsynConnection.cpp @@ -248,6 +248,7 @@ LDAPAsynConnection* LDAPAsynConnection::referralConnect( int port= conUrl->getPort(); DEBUG(LDAP_DEBUG_TRACE," connecting to: " << host << ":" << port << endl); + //Set the new connection's constraints-object ? tmpConn=new LDAPAsynConnection(host.c_str(),port); int err=0; diff --git a/contrib/ldapc++/src/LDAPAsynConnection.h b/contrib/ldapc++/src/LDAPAsynConnection.h index 20e41390ea..43c2b46263 100644 --- a/contrib/ldapc++/src/LDAPAsynConnection.h +++ b/contrib/ldapc++/src/LDAPAsynConnection.h @@ -43,15 +43,28 @@ class LDAPAttribute; */ class LDAPAsynConnection{ public : + /** + * Constant for the Search-Operation to indicate a Base-Level + * Search + */ static const int SEARCH_BASE=0; + + /** + * Constant for the Search-Operation to indicate a One-Level + * Search + */ static const int SEARCH_ONE=1; + + /** + * Constant for the Search-Operation to indicate a subtree + * Search + */ static const int SEARCH_SUB=2; // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE; // static const int SEARCH_ONE=LDAP_SCOPE_ONELEVEL; // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE; - //* Construtor that initializes a connection to a server - /** + /** Construtor that initializes a connection to a server * @param hostname Name (or IP-Adress) of the destination host * @param port Port the LDAP server is running on * @param cons Default constraints to use with operations over @@ -64,15 +77,23 @@ class LDAPAsynConnection{ virtual ~LDAPAsynConnection(); /** - * Initzializes a connection to a server. There actually no + * Initzializes a connection to a server. + * + * There actually no * communication to the server. Just the object is initialized - * (e.g. this method is called with the + * (e.g. this method is called within the * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.) + * @param hostname The Name or IP-Address of the destination + * LDAP-Server + * @param port The Network Port the server is running on */ void init(const string& hostname, int port); - //* Simple authentication to a LDAP-Server - /** + /** Simple authentication to a LDAP-Server + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * This method does a simple (username, password) bind to the server. * Other, saver, authentcation methods are provided later * @param dn the distiguished name to bind as @@ -81,15 +102,20 @@ class LDAPAsynConnection{ LDAPMessageQueue* bind(const string& dn="", const string& passwd="", const LDAPConstraints *cons=0); - //* Performing a search on a directory tree. - /** + /** Performing a search on a directory tree. + * * Use the search method to perform a search on the LDAP-Directory + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param base The distinguished name of the starting point for the * search operation * @param scope The scope of the search. Possible values:
* LDAPAsynConnection::SEARCH_BASE,
* LDAPAsynConnection::SEARCH_ONE,
* LDAPAsynConnection::SEARCH_SUB + * @param filter The string representation of a search filter to + * use with this operation * @param attrsOnly true if only the attributes names (no values) * should be returned * @param cons A set of constraints that should be used with this @@ -101,17 +127,24 @@ class LDAPAsynConnection{ bool attrsOnly=false, const LDAPConstraints *cons=0); - //* Delete an entry from the directory - /** + /** Delete an entry from the directory + * * This method sends a delete request to the server + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param dn Distinguished name of the entry that should be deleted * @param cons A set of constraints that should be used with this * request */ LDAPMessageQueue* del(const string& dn, const LDAPConstraints *cons=0); - //* Perform the compare operation on an attribute - /** + /** + * Perform the COMPARE-operation on an attribute + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param dn Distinguished name of the entry for which the compare * should be performed * @param attr An Attribute (one (!) value) to use for the @@ -122,16 +155,21 @@ class LDAPAsynConnection{ LDAPMessageQueue* compare(const string& dn, const LDAPAttribute& attr, const LDAPConstraints *cons=0); - //* Add an entry to the directory - /** - * @see LDAPEntry + /** Add an entry to the directory + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param le The entry that will be added to the directory */ LDAPMessageQueue* add( const LDAPEntry* le, const LDAPConstraints *const=0); - //* Apply modifications to attributes of an entry - /** + /** Apply modifications to attributes of an entry + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param dn Distiguished Name of the Entry to modify * @param modlist A set of modification that should be applied * to the Entry @@ -141,8 +179,11 @@ class LDAPAsynConnection{ LDAPMessageQueue* modify(const string& dn, const LDAPModList *modlist, const LDAPConstraints *cons=0); - //* modify the DN of an entry - /** + /** modify the DN of an entry + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param dn DN to modify * @param newRDN The new relative DN for the entry * @param delOldRDN true=The old RDN will be removed from the @@ -156,9 +197,11 @@ class LDAPAsynConnection{ bool delOldRDN=false, const string& newParentDN="", const LDAPConstraints* cons=0); - //* Perform a LDAP extended Operation - /** - * e.g. requesting TLS security features + /** Perform a LDAP extended Operation + * + * @throws LDAPException If the Request could not be sent to the + * destination server, a LDAPException-object contains the + * error that occured. * @param oid The dotted decimal representation of the extended * Operation that should be performed * @param value The data asociated with this operation @@ -168,42 +211,98 @@ class LDAPAsynConnection{ LDAPMessageQueue* extOperation(const string& oid, const string& value="", const LDAPConstraints *cons=0); - //* End an outstanding request - /** + /** End an outstanding request + * * @param q All outstanding request related to this LDAPMessageQueue * will be abandoned */ void abandon(LDAPMessageQueue *q); + + /** + * Performs the UNBIND-operation on the destination server + * + * @throws LDAPException in any case of an error + */ void unbind(); + + /** + * @returns The C-APIs LDAP-structure that is associated with the + * current connection + */ LDAP* getSessionHandle() const ; + + /** + * @returns The Hostname of the destination server of the + * connection. + */ const string& getHost() const; + + /** + * @returns The Port to which this connection is connecting to on + * the remote server. + */ int getPort() const; - //* Change the default constraints of the connection - /** - * @cons cons New LDAPConstraints to use with the connection + /** Change the default constraints of the connection + * + * @parameter cons cons New LDAPConstraints to use with the connection */ void setConstraints(LDAPConstraints *cons); - //* Get the default constraints of the connection - /** + /** Get the default constraints of the connection + * * @return Pointer to the LDAPConstraints-Object that is currently * used with the Connection */ const LDAPConstraints* getConstraints() const; - //* used internally only for automatic referral chasing + /** + * This method is used internally for automatic referral chasing. + * It tries to bind to a destination server of the URLs of a + * referral. + * + * @throws LDAPException in any case of an error + * @param urls Contains a list of LDAP-Urls that indicate the + * destinations of a referral + * @param usedUrl After this method has successfully bind to one of + * the Destination URLs this parameter contains the URLs + * which was contacted. + * @param cons An LDAPConstraints-Object that should be used for + * the new connection. If this object contains a + * LDAPRebind-object it is used to bind to the new server + */ LDAPAsynConnection* referralConnect(const LDAPUrlList& urls, LDAPUrlList::const_iterator& usedUrl, const LDAPConstraints* cons) const; private : - // no copy constructor + /** + * Private copy constructor. So nobody can call it. + */ LDAPAsynConnection(const LDAPAsynConnection& lc){}; + + /** + * A pointer to the C-API LDAP-structure that is associated with + * this connection + */ LDAP *cur_session; + + /** + * A pointer to the default LDAPConstrains-object that is used when + * no LDAPConstraints-parameter is provided with a call for a + * LDAP-operation + */ LDAPConstraints *m_constr; + + /** + * The name of the destination host + */ string m_host; + + /** + * The port the destination server is running on. + */ int m_port; }; diff --git a/contrib/ldapc++/src/LDAPAttribute.h b/contrib/ldapc++/src/LDAPAttribute.h index a3e8abdd6e..82b12324a3 100644 --- a/contrib/ldapc++/src/LDAPAttribute.h +++ b/contrib/ldapc++/src/LDAPAttribute.h @@ -14,41 +14,52 @@ #include "StringList.h" -//! Represents the name an value(s) of an Attribute +/** + * Represents the name an value(s) of an Attribute + */ class LDAPAttribute{ public : - //! Default constructor - /*! - * initializes an empty object + /** + * Default constructor. + * initializes an empty object. */ LDAPAttribute(); - //!Copy constructor - /*! + /** + * Copy constructor. * Copies all values of an Attribute to a new one * @param attr The Attribute that should be copied */ LDAPAttribute(const LDAPAttribute& attr); - //! Construct an Attribute with a single string value - /*! + /** + * Construct an Attribute with a single string value * @param name The attribute's name (type) - * @param value The string value of the attribute, if 0 the - * will have no values, for LDAPv3 this values must - * be UTF-8 encoded + * @param value The string value of the attribute, if "" the + * attribute will have no values, for LDAPv3 + * this values must be UTF-8 encoded */ LDAPAttribute(const string& name, const string& value=""); - //! Construct an attribute with multiple string values - /*! + /** + * Construct an attribute with multiple string values * @param name The attribute's name (type) * @param values A 0-terminated array of char*. Each char* specifies * one value of the attribute (UTF-8 encoded) */ LDAPAttribute(const char* name, char **values); + + /** + * Construct an attribute with multiple string values + * @param name The attribute's name (type) + * @param values A list of strings. Each element specifies + * one value of the attribute (UTF-8 or binary + * encoded) + */ LDAPAttribute(const string& name, const StringList& values); - //! Construct an attribute with multiple binary coded values - /*! + + /** + * Construct an attribute with multiple binary coded values * @param name The attribute's name (type) * @param values 0-terminated array of binary attribute values * The BerValue struct is declared as:
@@ -59,30 +70,28 @@ class LDAPAttribute{ */ LDAPAttribute(const char* name, BerValue **values); - //! Destructor + /** + * Destructor + */ ~LDAPAttribute(); - //! Add a single string value(bin/char) to the Attribute - /*! + /** + * Add a single string value(bin/char) to the Attribute * @param value Value that should be added, it is copied inside the * object - * - * @return 0 no problem
- * -1 failure (mem. allocation problem) */ void addValue(const string& value); - //! Add a single binary value to the Attribute - /*! + /** + * Add a single binary value to the Attribute * @param value The binary coded value that should be added to the * Attribute. - * * @return 0 no problem
* -1 failure (mem. allocation problem) */ int addValue(const BerValue *value); - /*! + /** * Set the values of the attribute. If the object contains some values * already, they are deleted * @param values 0-terminated array of char*, each char* @@ -93,7 +102,7 @@ class LDAPAttribute{ */ int setValues(char** values); - /*! + /** * Set the values of the attribute. If the object does already contain * some values, they will be deleted * @param values 0-terminated array of BerValue*, each BerValue @@ -103,53 +112,69 @@ class LDAPAttribute{ * -1 failure (mem. allocation problem) */ int setValues(BerValue** values); + + /** + * Set the values of the attribute. If the object does already contain + * some values, they will be deleted + * @param values A list of string-Objects. Each string is + * representing a string or binary value to add to + * the entry + */ void setValues(const StringList& values); - /*! + + /** + * For interal use only. + * This method is used to translate the values of the Attribute to + * 0-terminated Array of BerValue-structs as used by the C-API * @return The Values of the Attribute as an 0-terminated Array of * BerValue* (is dynamically allocated, delete it after usage) *
* 0-pointer in case of error */ BerValue** getBerValues() const; + + /** + * @return The values of the array as a list of strings + */ const StringList& getValues() const; - /*! - * @return The Number of values of the attribute + + /** + * @return The number of values of the attribute */ int getNumValues() const; - /*! + /** * @return The name(type) of the attribute - *
- * 0-pointer in case of error */ const string& getName() const ; - /*! + /** + * Sets the Attribute's name (type) * @param the new name of the object - * - * @return 0 no problem
- * -1 failure (mem. allocation problem) */ void setName(const string& name); - /*! - * for internal use only + /** + * For internal use only. + * + * This method translate the attribute of the object into a + * LDAPMod-Structure as used by the C-API */ LDAPMod* toLDAPMod() const ; + /** + * @return true If the attribute contains non-printable attributes + */ bool isNotPrintable() const ; private : string m_name; StringList m_values; - /*! - * @return true if the values contains nonprintable characters, - * otherwise false - */ - /*! - * just for debugging at the moment - */ + /** + * This method can be used to dump the data of a LDAPResult-Object. + * It is only useful for debugging purposes at the moment + */ friend ostream& operator << (ostream& s, const LDAPAttribute& attr); }; #endif //#ifndef LDAP_ATTRIBUTE_H diff --git a/contrib/ldapc++/src/LDAPAttributeList.h b/contrib/ldapc++/src/LDAPAttributeList.h index 0a6f64cb6d..8161293364 100644 --- a/contrib/ldapc++/src/LDAPAttributeList.h +++ b/contrib/ldapc++/src/LDAPAttributeList.h @@ -14,6 +14,9 @@ class LDAPMsg; typedef list AttrList; +/** + * This container class is used to store multiple LDAPAttribute-objects. + */ class LDAPAttributeList{ typedef AttrList::const_iterator const_iterator; @@ -21,21 +24,64 @@ class LDAPAttributeList{ AttrList m_attrs; public : + + /** + * Copy-constructor + */ LDAPAttributeList(const LDAPAttributeList& al); - /*! - * @throws LDAPException if msg does not contain an entry + /** + * For internal use only + * + * This constructor is used by the library internally to create a + * list of attributes from a LDAPMessage-struct that was return by + * the C-API */ LDAPAttributeList(const LDAPAsynConnection *ld, LDAPMessage *msg); + + /** + * Constructs an empty list. + */ LDAPAttributeList(); + + /** + * Destructor + */ virtual ~LDAPAttributeList(); + /** + * @return The number of LDAPAttribute-objects that are currently + * stored in this list. + */ size_t size() const; + + /** + * @return A iterator that points to the first element of the list. + */ const_iterator begin() const; + + /** + * @return A iterator that points to the element after the last + * element of the list. + */ const_iterator end() const; + + /** + * Adds one element to the end of the list. + * @param attr The attribute to add to the list. + */ void addAttribute(const LDAPAttribute& attr); + + /** + * Translates the list of Attributes to a 0-terminated array of + * LDAPMod-structures as needed by the C-API + */ LDAPMod** toLDAPModArray() const; + /** + * This method can be used to dump the data of a LDAPResult-Object. + * It is only useful for debugging purposes at the moment + */ friend ostream& operator << (ostream& s, const LDAPAttributeList& al); }; #endif // LDAP_ATTRIBUTE_LIST_H diff --git a/contrib/ldapc++/src/LDAPConnection.cpp b/contrib/ldapc++/src/LDAPConnection.cpp index 5c1d9c78a4..7baa9333a7 100644 --- a/contrib/ldapc++/src/LDAPConnection.cpp +++ b/contrib/ldapc++/src/LDAPConnection.cpp @@ -276,6 +276,39 @@ LDAPSearchResults* LDAPConnection::search(const string& base, int scope, return 0; } +LDAPExtResult* LDAPConnection::extOperation(const string& oid, + const string& value, const LDAPConstraints *cons = 0){ + DEBUG(LDAP_DEBUG_TRACE,"LDAPConnection::extOperation" << endl); + LDAPMessageQueue* msg=0; + LDAPExtResult* res=0; + try{ + msg = LDAPAsynConnection::extOperation(oid,value,cons); + res = (LDAPExtResult*)msg->getNext(); + }catch(LDAPException e){ + delete msg; + delete res; + throw; + } + int resCode=res->getResultCode(); + switch (resCode){ + case LDAPResult::SUCCESS : + delete msg; + return res; + case LDAPResult::REFERRAL : + { + LDAPUrlList urls = res->getReferralUrls(); + delete res; + delete msg; + throw LDAPReferralException(urls); + } + break; + default : + delete res; + delete msg; + throw LDAPException(resCode); + } +} + const string& LDAPConnection::getHost() const{ return LDAPAsynConnection::getHost(); } diff --git a/contrib/ldapc++/src/LDAPConnection.h b/contrib/ldapc++/src/LDAPConnection.h index 11fd746d53..036e54cada 100644 --- a/contrib/ldapc++/src/LDAPConnection.h +++ b/contrib/ldapc++/src/LDAPConnection.h @@ -7,40 +7,219 @@ #define LDAP_CONNECTION_H #include "LDAPSearchResults.h" - +#include "LDAPExtResult.h" #include "LDAPAsynConnection.h" +/** Main class for synchronous LDAP-Communication + * + * The class represent a LDAP-Connection to perform synchronous + * LDAP-Operations. This provides methodes for the different + * LDAP-Operations. All the methods for the LDAP-operations block until + * all results for the operation are received or until an error occurs + */ class LDAPConnection : private LDAPAsynConnection { public : + /** + * Constant for the Search-Operation to indicate a Base-Level + * Search + */ static const int SEARCH_BASE; + + /** + * Constant for the Search-Operation to indicate a One-Level + * Search + */ static const int SEARCH_ONE; + + /** + * Constant for the Search-Operation to indicate a Subtree + * Search + */ static const int SEARCH_SUB; + + /** This Constructor initializes synchronous LDAP-Connection + * + * During execution of this constructor no network communication + * is performed. Just some internal data structure are initialized + * @param hostname Name (or IP-Adress) of the destination host + * @param port Port the LDAP server is running on + * @param cons Default constraints to use with operations over + * this connection + */ LDAPConnection(const string& hostname="localhost", int port=389, LDAPConstraints* cons=0); + + /** + * Destructor + */ ~LDAPConnection(); - + + /** + * Initzializes a synchronous connection to a server. + * + * There is actually no + * communication to the server. Just the object is initialized + * (e.g. this method is called within the + * LDAPConnection(char*,int,LDAPConstraints) constructor.) + * @param hostname The Name or IP-Address of the destination + * LDAP-Server + * @param port The Network Port the server is running on + */ void init(const string& hostname, int port); + + /** + * Performs a simple authentication with the server + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param dn The name of the entry to bind as + * @param passwd The cleartext password for the entry + */ void bind(const string& dn="", const string& passwd="", LDAPConstraints* cons=0); + + /** + * Performs the UNBIND-operation on the destination server + * + * @throws LDAPException in any case of an error + */ void unbind(); - bool compare(const string&, const LDAPAttribute& attr, + + /** + * Performs a COMPARE-operation on an entery of the destination + * server. + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param dn Distinguished name of the entry for which the compare + * should be performed + * @param attr An Attribute (one (!) value) to use for the + * compare operation + * @param cons A set of constraints that should be used with this + * request + * @returns The result of the compare operation. true if the + * attr-parameter matched an Attribute of the entry. false if it + * did not match + */ + bool compare(const string& dn, const LDAPAttribute& attr, LDAPConstraints* cons=0); + + /** + * Deletes an entry from the directory + * + * This method performs the DELETE operation on the server + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param dn Distinguished name of the entry that should be deleted + * @param cons A set of constraints that should be used with this + * request + */ void del(const string& dn, const LDAPConstraints* cons=0); + + /** + * Use this method to perform the ADD-operation + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param le the entry to add to the directory + * @param cons A set of constraints that should be used with this + * request + */ void add(const LDAPEntry* le, const LDAPConstraints* cons=0); + + /** + * To modify the attributes of an entry, this method can be used + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param dn The DN of the entry which should be modified + * @param mods A set of modifications for that entry. + * @param cons A set of constraints that should be used with this + * request + */ void modify(const string& dn, const LDAPModList* mods, const LDAPConstraints* cons=0); + + /** + * This method performs the ModDN-operation. + * + * It can be used to rename or move an entry by modifing its DN. + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param dn The DN that should be modified + * @param newRDN If the RDN of the entry should be modified the + * new RDN can be put here. + * @param delOldRDN If the old RDN should be removed from the + * entry's attribute this parameter has to be + * "true" + * @param newParentDN If the entry should be moved inside the + * DIT, the DN of the new parent of the entry + * can be given here. + * @param cons A set of constraints that should be used with this + * request + */ void rename(const string& dn, const string& newRDN, bool delOldRDN=false, const string& newParentDN="", const LDAPConstraints* cons=0); + + /** + * This method can be used for the sync. SEARCH-operation. + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param base The distinguished name of the starting point for the + * search + * @param scope The scope of the search. Possible values:
+ * LDAPAsynConnection::SEARCH_BASE,
+ * LDAPAsynConnection::SEARCH_ONE,
+ * LDAPAsynConnection::SEARCH_SUB + * @param filter The string representation of a search filter to + * use with this operation + * @param attrsOnly true if only the attributes names (no values) + * should be returned + * @param cons A set of constraints that should be used with this + * request + * @returns A pointer to a LDAPSearchResults-object that can be + * used to read the results of the search. + */ LDAPSearchResults* search(const string& base, int scope=0, const string& filter="objectClass=*", const StringList& attrs=StringList(), bool attrsOnly=false, const LDAPConstraints* cons=0); - + + /** + * This method is for extended LDAP-Operations. + * + * @throws LDAPReferralException if a referral is received + * @throws LDAPException for any other error occuring during the + * operation + * @param oid The Object Identifier of the Extended Operation that + * should be performed. + * @param strint If the Extended Operation needs some additional + * data it can be passed to the server by this parameter. + * @param cons A set of constraints that should be used with this + * request + * @returns The result of the Extended Operation as an + * pointer to a LDAPExtResult-object. + */ + LDAPExtResult* extOperation(const string& oid, const string& + value="", const LDAPConstraints *const = 0); + const string& getHost() const; + int getPort() const; + void setConstraints(LDAPConstraints *cons); + const LDAPConstraints* getConstraints() const ; }; diff --git a/contrib/ldapc++/src/LDAPControl.h b/contrib/ldapc++/src/LDAPControl.h index 35c074749a..bb9394fdde 100644 --- a/contrib/ldapc++/src/LDAPControl.h +++ b/contrib/ldapc++/src/LDAPControl.h @@ -9,22 +9,71 @@ #include #include - +/** + * This class is used to store Controls. Controls are a mechanism to extend + * and modify LDAP-Operations. + */ class LDAPCtrl{ - public : + public : + /** + * Copy-constructor + */ LDAPCtrl(const LDAPCtrl& c); - LDAPCtrl(const char *oid, bool critical, const char *data=0, + + /** + * Constructor. + * @param oid: The Object Identifier of the Control + * @param critical: "true" if the Control should be handled + * critical by the server. + * @param data: If there is data for the control, put it here. + * @param length: The length of the data field + */ + LDAPCtrl(const char *oid, bool critical, const char *data=0, int length=0); + + /** + * Constructor. + * @param oid: The Object Identifier of the Control + * @param critical: "true" if the Control should be handled + * critical by the server. + * @param data: If there is data for the control, put it here. + */ LDAPCtrl(const string& oid, bool critical=false, const string& data=string()); + + /** + * Creates a copy of the Control that "ctrl is pointing to + */ LDAPCtrl(const LDAPControl* ctrl); + + /** + * Destructor + */ ~LDAPCtrl(); - + + /** + * @return The OID of the control + */ string getOID() const; + + /** + * @return The Data of the control as a string-Objekt + */ string getData() const; + + /** + * @return "true" if the control is critical + */ bool isCritical() const; + + /** + * For internal use only. + * + * Translates the control to a LDAPControl-structure as needed by + * the C-API + */ LDAPControl* getControlStruct() const; - + private : string m_oid; string m_data; diff --git a/contrib/ldapc++/src/LDAPControlSet.h b/contrib/ldapc++/src/LDAPControlSet.h index b3e107537d..8ab8a12446 100644 --- a/contrib/ldapc++/src/LDAPControlSet.h +++ b/contrib/ldapc++/src/LDAPControlSet.h @@ -12,21 +12,68 @@ typedef list CtrlList; - +/** + * This container class is used to store multiple LDAPCtrl-objects. + */ class LDAPControlSet { typedef CtrlList::const_iterator const_iterator; public : - LDAPControlSet(); + /** + * Constructs an empty list + */ + LDAPControlSet(); + + + /** + * Copy-constructor + */ LDAPControlSet(const LDAPControlSet& cs); - //!for internal use only - //untested til now. Due to lack of server that return Controls + + /** + * For internal use only + * + * This constructor creates a new LDAPControlSet for a + * 0-terminiated array of LDAPControl-structures as used by the + * C-API + * @param controls: pointer to a 0-terminated array of pointers to + * LDAPControll-structures + * @note: untested til now. Due to lack of server that return + * Controls + */ LDAPControlSet(LDAPControl** controls); + + /** + * Destructor + */ ~LDAPControlSet(); + + /** + * @return The number of LDAPCtrl-objects that are currently + * stored in this list. + */ size_t size() const ; + + /** + * @return A iterator that points to the first element of the list. + */ const_iterator begin() const; + + /** + * @return A iterator that points to the element after the last + * element of the list. + */ const_iterator end() const; + + /** + * Adds one element to the end of the list. + * @param ctrl The Control to add to the list. + */ void add(const LDAPCtrl& ctrl); + /** + * Translates the list to a 0-terminated array of pointers to + * LDAPControl-structures as needed by the C-API + */ LDAPControl** toLDAPControlArray()const ; private : diff --git a/contrib/ldapc++/src/LDAPEntry.h b/contrib/ldapc++/src/LDAPEntry.h index 918f533e8c..e8341604bb 100644 --- a/contrib/ldapc++/src/LDAPEntry.h +++ b/contrib/ldapc++/src/LDAPEntry.h @@ -11,21 +11,69 @@ #include "LDAPAsynConnection.h" #include "LDAPAttributeList.h" +/** + * This class is used to store every kind of LDAP Entry. + */ class LDAPEntry{ public : + /** + * Copy-constructor + */ LDAPEntry(const LDAPEntry& entry); + + /** + * Constructs a new entry (also used as standard constructor). + * + * @param dn The Distinguished Name for the new entry. + * @param attrs The attributes for the new entry. + */ LDAPEntry(const string& dn=string(), const LDAPAttributeList *attrs=new LDAPAttributeList()); + + /** + * Used internally only. + * + * The constructor is used internally to create a LDAPEntry from + * the C-API's data structurs. + */ LDAPEntry(const LDAPAsynConnection *ld, LDAPMessage *msg); + + /** + * Destructor + */ ~LDAPEntry(); + + /** + * Sets the DN-attribute. + * @param dn: The new DN for the entry. + */ void setDN(const string& dn); + + /** + * Sets the attributes of the entry. + * @param attr: A pointer to a list of the new attributes. + */ void setAttributes(LDAPAttributeList *attrs); + + /** + * @returns The current DN of the entry. + */ const string getDN() const ; + + /** + * @returns A const pointer to the attributes of the entry. + */ const LDAPAttributeList* getAttributes() const; + + /** + * This method can be used to dump the data of a LDAPResult-Object. + * It is only useful for debugging purposes at the moment + */ friend ostream& operator << (ostream& s, const LDAPEntry& le); private : + LDAPAttributeList *m_attrs; string m_dn; }; diff --git a/contrib/ldapc++/src/LDAPEntryList.h b/contrib/ldapc++/src/LDAPEntryList.h index b75aed8bca..a081b27911 100644 --- a/contrib/ldapc++/src/LDAPEntryList.h +++ b/contrib/ldapc++/src/LDAPEntryList.h @@ -11,20 +11,53 @@ class LDAPEntry; typedef list EntryList; + +/** + * For internal use only. + * + * This class is used by LDAPSearchResults to store a list of + * LDAPEntry-Objects + */ class LDAPEntryList{ typedef EntryList::const_iterator const_iterator; - private: - EntryList m_entries; - public: + /** + * Copy-Constructor + */ LDAPEntryList(const LDAPEntryList& el); + + /** + * Default-Constructor + */ LDAPEntryList(); + + /** + * Destructor + */ ~LDAPEntryList(); + /** + * @return The number of entries currently stored in the list. + */ size_t size() const; + + /** + * @return An iterator pointing to the first element of the list. + */ const_iterator begin() const; + + /** + * @return An iterator pointing to the end of the list + */ const_iterator end() const; + + /** + * Adds an Entry to the end of the list. + */ void addEntry(const LDAPEntry& e); + + private: + EntryList m_entries; }; #endif // LDAP_ENTRY_LIST_H diff --git a/contrib/ldapc++/src/LDAPException.cpp b/contrib/ldapc++/src/LDAPException.cpp index b4303a337c..f3022d06eb 100644 --- a/contrib/ldapc++/src/LDAPException.cpp +++ b/contrib/ldapc++/src/LDAPException.cpp @@ -40,6 +40,10 @@ const string& LDAPException::getResultMsg() const{ return m_res_string; } +const string& LDAPException::getServerMsg() const{ + return m_err_string; +} + ostream& operator << (ostream& s, LDAPException e){ s << "Error " << e.m_res_code << ": " << e.m_res_string; if (e.m_err_string.size() > 0) { diff --git a/contrib/ldapc++/src/LDAPException.h b/contrib/ldapc++/src/LDAPException.h index df48f39f3c..1bd87f9db2 100644 --- a/contrib/ldapc++/src/LDAPException.h +++ b/contrib/ldapc++/src/LDAPException.h @@ -12,19 +12,60 @@ class LDAPAsynConnection; +/** + * This class is only thrown as an Exception and used to signalize error + * conditions during LDAP-operations + */ class LDAPException{ - - private : - int m_res_code; - string m_res_string; - string m_err_string; public : + /** + * Constructs a LDAPException-object from the parameters + * @param res_code A valid LDAP result code. + * @param err_string An addional error message for the error + * that happend (optional) + */ LDAPException(int res_code, const string& err_string=string()); - LDAPException(const LDAPAsynConnection *lc); + + /** + * Constructs a LDAPException-object from the error state of a + * LDAPAsynConnection-object + * @param lc A LDAP-Connection for that an error has happend. The + * Constructor tries to read its error state. + */ + LDAPException(const LDAPAsynConnection *lc); + + /** + * Destructor + */ virtual ~LDAPException(); + + /** + * @return The Result code of the object + */ + int getResultCode() const; + + /** + * @return The error message that is corresponding to the result + * code . + */ const string& getResultMsg() const; + + /** + * @return The addional error message of the error (if it was set) + */ + const string& getServerMsg() const; + + /** + * This method can be used to dump the data of a LDAPResult-Object. + * It is only useful for debugging purposes at the moment + */ friend ostream& operator << (ostream &s, LDAPException e); + + private : + int m_res_code; + string m_res_string; + string m_err_string; }; #endif //LDAP_EXCEPTION_H diff --git a/contrib/ldapc++/src/LDAPExtResult.h b/contrib/ldapc++/src/LDAPExtResult.h index 1f7aeb63a0..13d0cc9ab2 100644 --- a/contrib/ldapc++/src/LDAPExtResult.h +++ b/contrib/ldapc++/src/LDAPExtResult.h @@ -8,15 +8,37 @@ #include -class LDAPResult; +#include "LDAPResult.h" + class LDAPRequest; +/** + * Object of this class are created by the LDAPMsg::create method if + * results for an Extended Operation were returned by a LDAP server. + */ class LDAPExtResult : public LDAPResult { public : + /** + * Constructor that creates an LDAPExtResult-object from the C-API + * structures + */ LDAPExtResult(const LDAPRequest* req, LDAPMessage* msg); + + /** + * The Destructor + */ virtual ~LDAPExtResult(); + /** + * @returns The OID of the Extended Operation that has returned + * this result. + */ const string& getResponseOid() const; + + /** + * @returns If the result contained data this method will return + * the data to the caller as a string. + */ const string& getResponse() const; private: diff --git a/contrib/ldapc++/src/LDAPMessage.cpp b/contrib/ldapc++/src/LDAPMessage.cpp index 05aede6f6e..c678d965fc 100644 --- a/contrib/ldapc++/src/LDAPMessage.cpp +++ b/contrib/ldapc++/src/LDAPMessage.cpp @@ -16,37 +16,37 @@ LDAPMsg::LDAPMsg(LDAPMessage *msg){ DEBUG(LDAP_DEBUG_CONSTRUCT,"LDAPMsg::LDAPMsg()" << endl); - msgType=ldap_msgtype(msg); + msgType=ldap_msgtype(msg); m_hasControls=false; } LDAPMsg* LDAPMsg::create(const LDAPRequest *req, LDAPMessage *msg){ DEBUG(LDAP_DEBUG_TRACE,"LDAPMsg::create()" << endl); - switch(ldap_msgtype(msg)){ - case SEARCH_ENTRY : - return new LDAPSearchResult(req,msg); - break; - case SEARCH_REFERENCE : - return new LDAPSearchReference(req, msg); - break; + switch(ldap_msgtype(msg)){ + case SEARCH_ENTRY : + return new LDAPSearchResult(req,msg); + break; + case SEARCH_REFERENCE : + return new LDAPSearchReference(req, msg); + break; case EXTENDED_RESPONSE : return new LDAPExtResult(req,msg); break; - default : - return new LDAPResult(req, msg); - } - return 0; + default : + return new LDAPResult(req, msg); + } + return 0; } int LDAPMsg::getMessageType(){ DEBUG(LDAP_DEBUG_TRACE,"LDAPMsg::getMessageType()" << endl); - return msgType; + return msgType; } int LDAPMsg::getMsgID(){ DEBUG(LDAP_DEBUG_TRACE,"LDAPMsg::getMsgID()" << endl); - return msgID; + return msgID; } bool LDAPMsg::hasControls() const{ diff --git a/contrib/ldapc++/src/LDAPMessage.h b/contrib/ldapc++/src/LDAPMessage.h index e5e9121198..130a030b94 100644 --- a/contrib/ldapc++/src/LDAPMessage.h +++ b/contrib/ldapc++/src/LDAPMessage.h @@ -11,14 +11,16 @@ #include "LDAPControlSet.h" class LDAPRequest; -//! Represents an LDAPMsg returned from the server -/*! - * This class is normally not instantiated directly. Normally only +/** + * This class represents any type of LDAP- Message returned + * from the server. + * + * This class is never not instantiated directly. Only * its subclasses are used. The main feature of this class is the * static method create() (see below) */ class LDAPMsg{ - public: + public: //public Constants defining the Message types static const int BIND_RESPONSE=LDAP_RES_BIND; static const int SEARCH_ENTRY=LDAP_RES_SEARCH_ENTRY; @@ -30,29 +32,83 @@ class LDAPMsg{ static const int MODDN_RESPONSE=LDAP_RES_MODDN; static const int COMPARE_RESPONSE=LDAP_RES_COMPARE; static const int EXTENDED_RESPONSE=LDAP_RES_EXTENDED; - - virtual ~LDAPMsg() {} + + /** + * The destructor has no implemenation, because this is an abstract + * class. + */ + virtual ~LDAPMsg() {} - /*! - * Based on msgtype-Value of the *msg-Parameter this method creates - * an Object of one of the subtypes of LDAPMsg (e.g. LDAPSearchResult + /** + * This method is used by the library to parse the results returned + * by the C-API. + * + * Based on msgtype-Value of the *msg-Parameter this method creates + * an Object of one of the subtypes of LDAPMsg (e.g. LDAPSearchResult * or LDAPResult) that represents the same Message as the * *msg-Parameter. *msg is e.g. a Message returned by the C-API's * ldap_result call. - */ - static LDAPMsg* create(const LDAPRequest *req, LDAPMessage *msg); - int getMessageType(); + * @param req The LDAPRequest-object this result message is + * associated with. + * @param msg The LDAPMessage-structure from the C-API that + * contains the LDAP-message to parse. + * @return An Object of one of the subtypes of this class. It + * contains the parsed LDAP-message. + */ + static LDAPMsg* create(const LDAPRequest *req, LDAPMessage *msg); + + /** + * @returns The Type of message that this object contains. Possible + * values are:
+ * BIND_RESPONSE
+ * SEARCH_ENTRY
+ * SEARCH_DONE
+ * SEARCH_REFERENCE
+ * MODIFY_RESPONSE
+ * ADD_RESPONSE
+ * DEL_RESPONSE
+ * MODDN_RESPONSE
+ * COMPARE_RESPONSE
+ * EXTENDED_REPONSE
+ */ + int getMessageType(); + + /** + * @returns The message-ID that the C-API return for the + * Result-message. + */ int getMsgID(); + + /** + * @returns If any Control was sent back by the server this method + * returns true. Otherwise false is returned. + */ bool hasControls() const; + + /** + * @returns Server controls that were sent back by the server. + * @note This feature is not test well yet. + */ const LDAPControlSet& getSrvControls() const; - + protected: - LDAPMsg(LDAPMessage *msg); + /** + * This constructor make a copy of a LDAPMsg-pointer. The object + * itself (no the pointer) is copied. + * Only for internal use. + */ + LDAPMsg(LDAPMessage *msg); + + /** + * This attribute stores Server-Control that were returned with the + * message. + */ LDAPControlSet m_srvControls; + bool m_hasControls; - private: - int msgType; - int msgID; + private: + int msgType; + int msgID; }; #endif //ifndef LDAP_MSG_H diff --git a/contrib/ldapc++/src/LDAPMessageQueue.cpp b/contrib/ldapc++/src/LDAPMessageQueue.cpp index 6d0e614d6f..a5c80a565f 100644 --- a/contrib/ldapc++/src/LDAPMessageQueue.cpp +++ b/contrib/ldapc++/src/LDAPMessageQueue.cpp @@ -123,9 +123,6 @@ LDAPMsg *LDAPMessageQueue::getNext(){ LDAPResult* res_p=(LDAPResult*)ret; switch (res_p->getResultCode()) { case LDAPResult::REFERRAL : - DEBUG(LDAP_DEBUG_TRACE, - "referral chasing to be implemented" - << endl); if(constr->getReferralChase()){ //throws Exception (limit Exceeded) LDAPRequest *refReq=chaseReferral(ret); diff --git a/contrib/ldapc++/src/LDAPMessageQueue.h b/contrib/ldapc++/src/LDAPMessageQueue.h index ca49290193..dcab47e292 100644 --- a/contrib/ldapc++/src/LDAPMessageQueue.h +++ b/contrib/ldapc++/src/LDAPMessageQueue.h @@ -19,12 +19,48 @@ class LDAPUrl; typedef stack LDAPRequestStack; typedef list LDAPRequestList; +/** + * This class is created for the asynchronous LDAP-operations. And can be + * used by the client to retrieve the results of an operation. + */ class LDAPMessageQueue{ public : + + /** + * This creates a new LDAPMessageQueue. For a LDAP-request + * + * @param conn The Request for that is queue can be used to get + * the results. + */ LDAPMessageQueue(LDAPRequest *conn); + /** + * Destructor + */ ~LDAPMessageQueue(); + + /** + * This method reads exactly one Message from the results of a + * Request. + * @throws LDAPException + * @return A pointer to an object of one of the classes that were + * derived from LDAPMsg. The user has to cast it to the + * correct type (e.g. LDAPResult or LDAPSearchResult) + */ LDAPMsg* getNext(); + + /** + * For internat use only. + * + * The method is used to start the automatic referral chasing + */ LDAPRequest* chaseReferral(LDAPMsg* ref); + + /** + * For internal use only + * + * The referral chasing algorithm needs this method to see the + * currently active requests. + */ LDAPRequestStack* getRequestStack(); private : diff --git a/contrib/ldapc++/src/LDAPModList.h b/contrib/ldapc++/src/LDAPModList.h index 0a05a16ed7..6fc1d74afa 100644 --- a/contrib/ldapc++/src/LDAPModList.h +++ b/contrib/ldapc++/src/LDAPModList.h @@ -13,14 +13,33 @@ typedef list ModList; +/** + * This container class is used to store multiple LDAPModification-objects. + */ class LDAPModList{ public : + /** + * Constructs an empty list. + */ LDAPModList(); - LDAPModList(const LDAPModList&); - + + /** + * Copy-constructor + */ + LDAPModList(const LDAPModList&); + + /** + * Adds one element to the end of the list. + * @param mod The LDAPModification to add to the list. + */ void addModification(const LDAPModification &mod); - LDAPMod** toLDAPModArray(); + + /** + * Translates the list to a 0-terminated array of + * LDAPMod-structures as needed by the C-API + */ + LDAPMod** toLDAPModArray(); private : ModList m_modList; diff --git a/contrib/ldapc++/src/LDAPRebindAuth.h b/contrib/ldapc++/src/LDAPRebindAuth.h index c0441b90d5..bf6dfa139b 100644 --- a/contrib/ldapc++/src/LDAPRebindAuth.h +++ b/contrib/ldapc++/src/LDAPRebindAuth.h @@ -8,13 +8,41 @@ #include +/** + * This class represent Authenication information for the case that the + * library is chasing referrals. + * + * The LDAPRebind::getRebindAuth() method returns an object of this type. + * And the library uses it to authentication to the destination server of a + * referral. + * @note currently only SIMPLE authentication is supported by the library + */ class LDAPRebindAuth{ public: + /** + * @param dn The DN that should be used for the authentication + * @param pwd The password that belongs to the DN + */ LDAPRebindAuth(const string& dn="", const string& pwd=""); + + /** + * Copy-constructor + */ LDAPRebindAuth(const LDAPRebindAuth& lra); + + /** + * Destructor + */ virtual ~LDAPRebindAuth(); + /** + * @return The DN that was set in the constructor + */ const string& getDN() const; + + /** + * @return The password that was set in the constructor + */ const string& getPassword() const; private: diff --git a/contrib/ldapc++/src/LDAPReferenceList.h b/contrib/ldapc++/src/LDAPReferenceList.h index 12b3419ea6..7cbe278ef4 100644 --- a/contrib/ldapc++/src/LDAPReferenceList.h +++ b/contrib/ldapc++/src/LDAPReferenceList.h @@ -12,17 +12,51 @@ class LDAPSearchReference; typedef list RefList; +/** + * Container class for storing a list of Search References + * + * Used internally only by LDAPSearchResults + */ class LDAPReferenceList{ typedef RefList::const_iterator const_iterator; public: + /** + * Constructs an empty list. + */ LDAPReferenceList(); + + /** + * Copy-constructor + */ LDAPReferenceList(const LDAPReferenceList& rl); + + /** + * Destructor + */ ~LDAPReferenceList(); + /** + * @return The number of LDAPSearchReference-objects that are + * currently stored in this list. + */ size_t size() const; + + /** + * @return A iterator that points to the first element of the list. + */ const_iterator begin() const; + + /** + * @return A iterator that points to the element after the last + * element of the list. + */ const_iterator end() const; + + /** + * Adds one element to the end of the list. + * @param e The LDAPSearchReference to add to the list. + */ void addReference(const LDAPSearchReference& e); private: diff --git a/contrib/ldapc++/src/LDAPReferralException.h b/contrib/ldapc++/src/LDAPReferralException.h index 1988107acd..8f7a37b531 100644 --- a/contrib/ldapc++/src/LDAPReferralException.h +++ b/contrib/ldapc++/src/LDAPReferralException.h @@ -13,15 +13,30 @@ class LDAPUrlList; +/** + * This class extends LDAPException and is used to signalize Referrals + * there were received during synchronous LDAP-operations + */ class LDAPReferralException : public LDAPException{ - private : - LDAPUrlList m_urlList; - public : + /** + * Creates an object that is initialized with a list of URLs + */ LDAPReferralException(const LDAPUrlList& urls); + + /** + * Destructor + */ ~LDAPReferralException(); + + /** + * @return The List of URLs of the Referral/Search Reference + */ const LDAPUrlList& getUrls(); + + private : + LDAPUrlList m_urlList; }; #endif //LDAP_REFERRAL_EXCEPTION_H diff --git a/contrib/ldapc++/src/LDAPRequest.h b/contrib/ldapc++/src/LDAPRequest.h index 45adabdb3e..172e98c2a5 100644 --- a/contrib/ldapc++/src/LDAPRequest.h +++ b/contrib/ldapc++/src/LDAPRequest.h @@ -13,7 +13,14 @@ class LDAPUrl; -//!virtual class for Requests +/** + * For internal use only + * + * Each request that is sent to a LDAP-server by this library is + * represented by a special object that contains the parameters and some + * other info of the request. This virtual class is the common base classe + * for these specialized request classes. + */ class LDAPRequest{ public : @@ -36,13 +43,34 @@ class LDAPRequest{ int getType()const; int getMsgID() const; int getHopCount() const; + + /** + * @return The LDAPRequest that has created this object. Or 0 if + * this object was not created by another request. + */ const LDAPRequest* getParent() const; + /** + * @return true if this object was created during the automatic + * chasing of referrals. Otherwise false + */ bool isReferral() const; + void unbind() const; + + /** + * This method encodes the request an calls the apprpriate + * functions of the C-API to send the Request to a LDAP-Server + */ virtual LDAPMessageQueue* sendRequest()=0; virtual LDAPRequest* followReferral(LDAPMsg* ref)=0; + + /** + * Compare this request with another on. And returns true if they + * have the same parameters. + */ virtual bool equals(const LDAPRequest* req) const; + bool isCycle() const; protected : diff --git a/contrib/ldapc++/src/LDAPResult.h b/contrib/ldapc++/src/LDAPResult.h index ef2cd57b68..14ff558450 100644 --- a/contrib/ldapc++/src/LDAPResult.h +++ b/contrib/ldapc++/src/LDAPResult.h @@ -4,8 +4,8 @@ */ -#ifndef LDAP_RESPNSE_H -#define LDAP_RESPONSE_H +#ifndef LDAP_RESULT_H +#define LDAP_RESULT_H #include #include @@ -16,6 +16,16 @@ class LDAPRequest; class LDAPAsynConnection; +/** + * This class is for representing LDAP-Result-Messages. + * + * It represents all Messages that were returned + * from LDAP-Operations except for Messages of the Type + * LDAPMsg::SEARCH_ENTRY, LDAPMsg::SEARCH_REFERENCE and + * LDAPMsg::EXTENDED_RESPONSE.
+ * It defines a integer constant for every possible result type that can be + * returned by the server. + */ class LDAPResult : public LDAPMsg{ public : //Error codes from RFC 2251 @@ -85,12 +95,53 @@ class LDAPResult : public LDAPMsg{ static const int CLIENT_LOOP = 96; static const int REFERRAL_LIMIT_EXCEEDED = 97; + /** + * This constructor is called by the LDAPMsg::create method in + * order to parse a LDAPResult-Message + * @param req The request the result is associated with. + * @param msg The LDAPMessage-structure that contains the + * Message. + */ LDAPResult(const LDAPRequest *req, LDAPMessage *msg); + + /** + * The destructor. + */ virtual ~LDAPResult(); + + /** + * @returns The result code of the Message. Possible values are the + * integer constants defined in this class. + */ int getResultCode() const; + + /** + * This method transforms the result code to a human-readable + * result message. + * @returns A string containing the result message. + */ string resToString() const; + + /** + * In some case of error the server may return addional error + * messages. + * @returns The additional error message returned by the server. + */ const string& getErrMsg() const; + + /** + * For messages with a result code of: NO_SUCH_OBJECT, + * ALIAS_PROBLEM, ALIAS_DEREFERENCING_PROBLEM or INVALID_DN_SYNTAX + * the server returns the DN of deepest entry in the DIT that could + * be found for this operation. + * @returns The Matched-DN value that was returned by the server. + */ const string& getMatchedDN() const; + + /** + * @returns If the result code is REFERRAL this methode returns the + * URLs of the referral that was sent by the server. + */ const LDAPUrlList& getReferralUrls() const; private : @@ -99,7 +150,11 @@ class LDAPResult : public LDAPMsg{ string m_errMsg; LDAPUrlList m_referrals; + /** + * This method can be used to dump the data of a LDAPResult-Object. + * It is only useful for debugging purposes at the moment + */ friend ostream& operator<<(ostream &s,LDAPResult &l); }; -#endif //LDAP_RESPONSE_H +#endif //LDAP_RESULT_H diff --git a/contrib/ldapc++/src/LDAPSearchReference.h b/contrib/ldapc++/src/LDAPSearchReference.h index e27fd65137..5cd94fcda9 100644 --- a/contrib/ldapc++/src/LDAPSearchReference.h +++ b/contrib/ldapc++/src/LDAPSearchReference.h @@ -13,11 +13,26 @@ class LDAPRequest; class LDAPUrl; +/** + * This class is used to represent Continuation References that were + * returned during a SEARCH-Operation. + */ class LDAPSearchReference : public LDAPMsg{ public : + /** + * Constructor that create an object from the C-API structures + */ LDAPSearchReference(const LDAPRequest* req, LDAPMessage* msg); + + /** + * The Destructor + */ ~LDAPSearchReference(); + + /** + * @returns The destination URLs that were send with this message + */ const LDAPUrlList& getUrls() const; private : diff --git a/contrib/ldapc++/src/LDAPSearchResult.h b/contrib/ldapc++/src/LDAPSearchResult.h index 4ee1cfad2e..07c2c7f246 100644 --- a/contrib/ldapc++/src/LDAPSearchResult.h +++ b/contrib/ldapc++/src/LDAPSearchResult.h @@ -12,14 +12,33 @@ class LDAPRequest; +/** + * This class is used to represent the result entries of a + * SEARCH-operation. + */ class LDAPSearchResult : public LDAPMsg{ - public: - LDAPSearchResult(const LDAPRequest *req, LDAPMessage *msg); + public: + /** + * Constructor that create an object from the C-API structures + */ + LDAPSearchResult(const LDAPRequest *req, LDAPMessage *msg); + + /** + * Copy-Constructor + */ LDAPSearchResult(const LDAPSearchResult& res); - virtual ~LDAPSearchResult(); - const LDAPEntry* getEntry() const; - + + /** + * The Destructor + */ + virtual ~LDAPSearchResult(); + + /** + * @returns The entry that has been sent with this result message. + */ + const LDAPEntry* getEntry() const; + private: - LDAPEntry *entry; + LDAPEntry *entry; }; #endif //LDAP_SEARCH_RESULT_H diff --git a/contrib/ldapc++/src/LDAPSearchResults.h b/contrib/ldapc++/src/LDAPSearchResults.h index 10d7b425bd..c1d857fa21 100644 --- a/contrib/ldapc++/src/LDAPSearchResults.h +++ b/contrib/ldapc++/src/LDAPSearchResults.h @@ -15,16 +15,40 @@ class LDAPResult; +/** + * The class stores the results of a synchronous SEARCH-Operation + */ class LDAPSearchResults{ + public: + /** + * Default-Constructor + */ + LDAPSearchResults(); + + /** + * For internal use only. + * + * This method read Search result entries from a + * LDAPMessageQueue-object. + * @param msg The message queue to read + */ + LDAPResult* readMessageQueue(LDAPMessageQueue* msg); + + /** + * The methode is used by the client-application to read the + * result entries of the SEARCH-Operation. Every call of this + * method returns one entry. If all entries were read it return 0. + * @throws LDAPReferralException If a Search Reference was + * returned by the server + * @returns A LDAPEntry-object as a result of a SEARCH-Operation or + * 0 if no more entries are there to return. + */ + LDAPEntry* getNext(); private : LDAPEntryList entryList; LDAPReferenceList refList; LDAPEntryList::const_iterator entryPos; LDAPReferenceList::const_iterator refPos; - public: - LDAPSearchResults(); - LDAPResult* readMessageQueue(LDAPMessageQueue* msg); - LDAPEntry* getNext(); }; #endif //LDAP_SEARCH_RESULTS_H diff --git a/contrib/ldapc++/src/LDAPUrl.h b/contrib/ldapc++/src/LDAPUrl.h index fd269e05a8..f72c7ab0bd 100644 --- a/contrib/ldapc++/src/LDAPUrl.h +++ b/contrib/ldapc++/src/LDAPUrl.h @@ -9,29 +9,74 @@ #include #include "StringList.h" + +/** + * This class is used to analyze and store LDAP-Urls as returned by a + * LDAP-Server as Referrals and Search References. LDAP-URLs are defined + * in RFC1959 and have the following format:
+ * + * ldap://host:port/baseDN[?attr[?scope[?filter]]]
+ * + */ class LDAPUrl{ - - protected : - int m_Port; - int m_Scope; - string m_Host; - string m_DN; - string m_Filter; - StringList m_Attrs; - LDAPURLDesc *m_urlDesc; - string m_urlString; public : + /** + * Create a new object from a c-string that contains a LDAP-Url + */ LDAPUrl(const char *url); + + /** + * Destructor + */ ~LDAPUrl(); + /** + * @return The part of the URL that is representing the network + * port + */ int getPort() const; + + /** + * @return The scope part of the URL is returned. + */ int getScope() const; + + /** + * @return The complete URL as a string + */ const string& getURLString() const; + + /** + * @return The hostname or IP-Address of the destination host. + */ const string& getHost() const; + + /** + * @return The Base-DN part of the URL + */ const string& getDN() const; + + + /** + * @return The Filter part of the URL + */ const string& getFilter() const; + + /** + * @return The List of attributes that was in the URL + */ const StringList& getAttrs() const; + + protected : + int m_Port; + int m_Scope; + string m_Host; + string m_DN; + string m_Filter; + StringList m_Attrs; + LDAPURLDesc *m_urlDesc; + string m_urlString; }; #endif //LDAP_URL_H diff --git a/contrib/ldapc++/src/LDAPUrlList.h b/contrib/ldapc++/src/LDAPUrlList.h index 56b6b8baf0..59d5d40522 100644 --- a/contrib/ldapc++/src/LDAPUrlList.h +++ b/contrib/ldapc++/src/LDAPUrlList.h @@ -11,19 +11,58 @@ typedef list UrlList; +/** + * This container class is used to store multiple LDAPUrl-objects. + */ class LDAPUrlList{ typedef UrlList::const_iterator const_iterator; public: + /** + * Constructs an empty list. + */ LDAPUrlList(); + + /** + * Copy-constructor + */ LDAPUrlList(const LDAPUrlList& urls); + + /** + * For internal use only + * + * This constructor is used by the library internally to create a + * list of URLs from a array of C-strings that was return by + * the C-API + */ LDAPUrlList(char** urls); + + /** + * Destructor + */ ~LDAPUrlList(); + /** + * @return The number of LDAPUrl-objects that are currently + * stored in this list. + */ size_t size() const; + + /** + * @return A iterator that points to the first element of the list. + */ const_iterator begin() const; + + /** + * @return A iterator that points to the element after the last + * element of the list. + */ const_iterator end() const; + /** + * Adds one element to the end of the list. + * @param attr The attribute to add to the list. + */ void add(const LDAPUrl& url); private : diff --git a/contrib/ldapc++/src/StringList.h b/contrib/ldapc++/src/StringList.h index f51c4fdcf7..63134040ea 100644 --- a/contrib/ldapc++/src/StringList.h +++ b/contrib/ldapc++/src/StringList.h @@ -10,6 +10,9 @@ #include typedef list ListType; +/** + * Container class to store multiple string-objects + */ class StringList{ typedef ListType::const_iterator const_iterator; @@ -17,16 +20,62 @@ class StringList{ ListType m_data; public: + /** + * Constructs an empty list. + */ StringList(); + + /** + * Copy-constructor + */ StringList(const StringList& sl); + + /** + * For internal use only + * + * This constructor is used by the library internally to create a + * list of string from a array for c-Strings (char*)thar was + * returned by the C-API + */ StringList(char** values); + + /** + * Destructor + */ ~StringList(); + /** + * The methods converts the list to a 0-terminated array of + * c-Strings. + */ char** toCharArray() const; + + /** + * Adds one element to the end of the list. + * @param attr The attribute to add to the list. + */ void add(const string& value); + + /** + * @return The number of strings that are currently + * stored in this list. + */ size_t size() const; + + /** + * @return A iterator that points to the first element of the list. + */ const_iterator begin() const; + + /** + * @return A iterator that points to the element after the last + * element of the list. + */ const_iterator end() const; + + /** + * removes all elements from the list + */ void clear(); }; #endif //STRING_LIST_H