2 * Copyright 2000, OpenLDAP Foundation, All Rights Reserved.
3 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
7 #ifndef LDAP_ASYN_CONNECTION_H
8 #define LDAP_ASYN_CONNECTION_H
16 #include "LDAPMessageQueue.h"
17 #include "LDAPConstraints.h"
18 #include "LDAPModification.h"
19 #include "LDAPModList.h"
21 #include "LDAPUrlList.h"
26 //* Main class for an asynchronous LDAP connection
28 * This class represents an asynchronous connection to an LDAP-Server. It
29 * provides the methods for authentication, and all other LDAP-Operations
30 * (e.g. search, add, delete, etc.)
31 * All of the LDAP-Operations return a pointer to a LDAPMessageQueue-Object,
32 * which can be used to obtain the results of that operation.
33 * A basic example of this class could be like this: <BR>
34 * 1. Create a new LDAPAsynConnection Object: <BR>
35 * 2. Use the init-method to initialize the connection <BR>
36 * 3. Call the bind-method to authenticate to the directory <BR>
37 * 4. Obtain the bind results from the return LDAPMessageQueue-Object <BR>
38 * 5. Perform on of the operations on the directory (add, delete, search, ..)
40 * 6. Use the return LDAPMessageQueue to obtain the results of the operation
42 * 7. Close the connection (feature not implemented yet :) ) <BR>
44 class LDAPAsynConnection{
46 static const int SEARCH_BASE=0;
47 static const int SEARCH_ONE=1;
48 static const int SEARCH_SUB=2;
49 // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
50 // static const int SEARCH_ONE=LDAP_SCOPE_ONELEVEL;
51 // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
53 //* Construtor that initializes a connection to a server
55 * @param hostname Name (or IP-Adress) of the destination host
56 * @param port Port the LDAP server is running on
57 * @param cons Default constraints to use with operations over
60 LDAPAsynConnection(const string& hostname=string("localhost"),
61 int port=389, LDAPConstraints *cons=new LDAPConstraints() );
64 virtual ~LDAPAsynConnection();
67 * Initzializes a connection to a server. There actually no
68 * communication to the server. Just the object is initialized
69 * (e.g. this method is called with the
70 * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.)
72 void init(const string& hostname, int port);
74 //* Simple authentication to a LDAP-Server
76 * This method does a simple (username, password) bind to the server.
77 * Other, saver, authentcation methods are provided later
78 * @param dn the distiguished name to bind as
79 * @param passwd cleartext password to use
81 LDAPMessageQueue* bind(const string& dn="", const string& passwd="",
82 const LDAPConstraints *cons=0);
84 //* Performing a search on a directory tree.
86 * Use the search method to perform a search on the LDAP-Directory
87 * @param base The distinguished name of the starting point for the
89 * @param scope The scope of the search. Possible values: <BR>
90 * LDAPAsynConnection::SEARCH_BASE, <BR>
91 * LDAPAsynConnection::SEARCH_ONE, <BR>
92 * LDAPAsynConnection::SEARCH_SUB
93 * @param attrsOnly true if only the attributes names (no values)
95 * @param cons A set of constraints that should be used with this
98 LDAPMessageQueue* search(const string& base="", int scope=0,
99 const string& filter="objectClass=*",
100 const StringList& attrs=StringList(),
101 bool attrsOnly=false,
102 const LDAPConstraints *cons=0);
104 //* Delete an entry from the directory
106 * This method sends a delete request to the server
107 * @param dn Distinguished name of the entry that should be deleted
108 * @param cons A set of constraints that should be used with this
111 LDAPMessageQueue* del(const string& dn, const LDAPConstraints *cons=0);
113 //* Perform the compare operation on an attribute
115 * @param dn Distinguished name of the entry for which the compare
116 * should be performed
117 * @param attr An Attribute (one (!) value) to use for the
119 * @param cons A set of constraints that should be used with this
122 LDAPMessageQueue* compare(const string& dn, const LDAPAttribute& attr,
123 const LDAPConstraints *cons=0);
125 //* Add an entry to the directory
128 * @param le The entry that will be added to the directory
130 LDAPMessageQueue* add( const LDAPEntry* le,
131 const LDAPConstraints *const=0);
133 //* Apply modifications to attributes of an entry
135 * @param dn Distiguished Name of the Entry to modify
136 * @param modlist A set of modification that should be applied
138 * @param cons A set of constraints that should be used with this
141 LDAPMessageQueue* modify(const string& dn, const LDAPModList *modlist,
142 const LDAPConstraints *cons=0);
144 //* modify the DN of an entry
146 * @param dn DN to modify
147 * @param newRDN The new relative DN for the entry
148 * @param delOldRDN true=The old RDN will be removed from the
150 * false=The old RDN will still be present in the
151 * attributes of the entry
152 * @param newParentDN The DN of the new parent entry of the entry
153 * 0 to keep the old one
155 LDAPMessageQueue* rename(const string& dn, const string& newRDN,
156 bool delOldRDN=false, const string& newParentDN="",
157 const LDAPConstraints* cons=0);
159 //* Perform a LDAP extended Operation
161 * e.g. requesting TLS security features
162 * @param oid The dotted decimal representation of the extended
163 * Operation that should be performed
164 * @param value The data asociated with this operation
165 * @param cons A set of constraints that should be used with this
168 LDAPMessageQueue* extOperation(const string& oid,
169 const string& value="", const LDAPConstraints *cons=0);
171 //* End an outstanding request
173 * @param q All outstanding request related to this LDAPMessageQueue
176 void abandon(LDAPMessageQueue *q);
178 LDAP* getSessionHandle() const ;
179 const string& getHost() const;
182 //* Change the default constraints of the connection
184 * @cons cons New LDAPConstraints to use with the connection
186 void setConstraints(LDAPConstraints *cons);
188 //* Get the default constraints of the connection
190 * @return Pointer to the LDAPConstraints-Object that is currently
191 * used with the Connection
193 const LDAPConstraints* getConstraints() const;
195 //* used internally only for automatic referral chasing
196 LDAPAsynConnection* referralConnect(const LDAPUrlList& urls,
197 LDAPUrlList::const_iterator& usedUrl,
198 const LDAPConstraints* cons) const;
202 // no copy constructor
203 LDAPAsynConnection(const LDAPAsynConnection& lc){};
205 LDAPConstraints *m_constr;
210 #endif //LDAP_ASYN_CONNECTION_H