Commit 32671aa8 authored by Ralf Haferkamp's avatar Ralf Haferkamp
Browse files

- some minor bugfixes

- lots of documentation (javadoc style comments)
parent 72cd80f6
......@@ -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;
......
......@@ -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: <BR>
* LDAPAsynConnection::SEARCH_BASE, <BR>
* LDAPAsynConnection::SEARCH_ONE, <BR>
* 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;
};
......
......@@ -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:<BR>
......@@ -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 <BR>
* -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 <BR>
* -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)
* <BR>
* 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
* <BR>
* 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 <BR>
* -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
......@@ -14,6 +14,9 @@ class LDAPMsg;
typedef list<LDAPAttribute> 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
......
......@@ -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();
}
......
......@@ -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