X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=contrib%2Fldapc%2B%2B%2Fsrc%2FLDAPAsynConnection.h;h=fdef9ccd5f44e6926a291ca3dd3e096d6b27c774;hb=3b695bc6c855ca79136f5f9a184804e73ad06f20;hp=20e41390ea2ef644f656f993b664b2582a173822;hpb=11fbe2a45c64036a08e601270b0d1049f2c57009;p=openldap diff --git a/contrib/ldapc++/src/LDAPAsynConnection.h b/contrib/ldapc++/src/LDAPAsynConnection.h index 20e41390ea..fdef9ccd5f 100644 --- a/contrib/ldapc++/src/LDAPAsynConnection.h +++ b/contrib/ldapc++/src/LDAPAsynConnection.h @@ -13,12 +13,12 @@ #include #include -#include "LDAPMessageQueue.h" -#include "LDAPConstraints.h" -#include "LDAPModification.h" -#include "LDAPModList.h" -#include "LDAPUrl.h" -#include "LDAPUrlList.h" +#include +#include +#include +#include +#include +#include class LDAPEntry; class LDAPAttribute; @@ -43,75 +43,116 @@ 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 * this connection */ - LDAPAsynConnection(const string& hostname=string("localhost"), + LDAPAsynConnection(const std::string& hostname=std::string("localhost"), int port=389, LDAPConstraints *cons=new LDAPConstraints() ); //* Destructor virtual ~LDAPAsynConnection(); /** - * Initzializes a connection to a server. There actually no + * Initializes 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); + void init(const std::string& hostname, int port); - //* Simple authentication to a LDAP-Server /** + * Start TLS on this connection. This isn't in the constructor, + * because it could fail (i.e. server doesn't have SSL cert, client + * api wasn't compiled against OpenSSL, etc.). If you need TLS, + * then you should error if this call fails with an error code. + */ + int start_tls(); + + /** 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 * @param passwd cleartext password to use */ - LDAPMessageQueue* bind(const string& dn="", const string& passwd="", + LDAPMessageQueue* bind(const std::string& dn="", const std::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 std::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 */ - LDAPMessageQueue* search(const string& base="", int scope=0, - const string& filter="objectClass=*", + LDAPMessageQueue* search(const std::string& base="", int scope=0, + const std::string& filter="objectClass=*", const StringList& attrs=StringList(), 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); + LDAPMessageQueue* del(const std::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 @@ -119,30 +160,40 @@ class LDAPAsynConnection{ * @param cons A set of constraints that should be used with this * request */ - LDAPMessageQueue* compare(const string& dn, const LDAPAttribute& attr, + LDAPMessageQueue* compare(const std::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 * @param cons A set of constraints that should be used with this * request */ - LDAPMessageQueue* modify(const string& dn, const LDAPModList *modlist, + LDAPMessageQueue* modify(const std::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 @@ -152,60 +203,139 @@ class LDAPAsynConnection{ * @param newParentDN The DN of the new parent entry of the entry * 0 to keep the old one */ - LDAPMessageQueue* rename(const string& dn, const string& newRDN, - bool delOldRDN=false, const string& newParentDN="", + LDAPMessageQueue* rename(const std::string& dn, + const std::string& newRDN, + bool delOldRDN=false, const std::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 * @param cons A set of constraints that should be used with this * request */ - LDAPMessageQueue* extOperation(const string& oid, - const string& value="", const LDAPConstraints *cons=0); + LDAPMessageQueue* extOperation(const std::string& oid, + const std::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 ; - const string& getHost() const; + + /** + * @returns The Hostname of the destination server of the + * connection. + */ + const std::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 std::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; - + /** + * Turn on caching, maxmem is in MB and timeout is in seconds. + * maxmem can be zero if you want to restrict caching by timeout only. + */ + int enableCache(long timeout, long maxmem); + /// disable caching. + void disableCache(); + /// is cacheEnabled? + bool getCacheEnabled() { return m_cacheEnabled;}; + /// uncache a specific dn. Used internally by methods that write. + void uncache_entry(std::string &dn); + /// used to clear the cache. Probably should be used after creating + /// an object that a cached search should find. + void flush_cache(); + + 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; - string m_host; + + /** + * The name of the destination host + */ + std::string m_host; + + /** + * The port the destination server is running on. + */ int m_port; + protected: + /** + * Is caching enabled? + */ + bool m_cacheEnabled; }; #endif //LDAP_ASYN_CONNECTION_H