git.sur5r.net Git - openldap/blob - contrib/ldapc++/src/LDAPAsynConnection.h

   1 /*
   2  * Copyright 2000, OpenLDAP Foundation, All Rights Reserved.
   3  * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
   4  */
   5
   6
   7 #ifndef LDAP_ASYN_CONNECTION_H
   8 #define LDAP_ASYN_CONNECTION_H
   9
  10 #include<iostream>
  11 #include<string>
  12
  13 #include<ldap.h>
  14 #include<lber.h>
  15
  16 #include <LDAPMessageQueue.h>
  17 #include <LDAPConstraints.h>
  18 #include <LDAPModification.h>
  19 #include <LDAPModList.h>
  20 #include <LDAPUrl.h>
  21 #include <LDAPUrlList.h>
  22
  23 class LDAPEntry;
  24 class LDAPAttribute;
  25
  26 //* Main class for an asynchronous LDAP connection
  27 /**
  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, ..)
  39  *    <BR>
  40  * 6. Use the return LDAPMessageQueue to obtain the results of the operation
  41  * <BR>
  42  * 7. Close the connection (feature not implemented yet :) ) <BR>
  43  */
  44 class LDAPAsynConnection{
  45     public :
  46         /**
  47          * Constant for the Search-Operation to indicate a Base-Level
  48          * Search
  49          */
  50         static const int SEARCH_BASE=0;
  51
  52         /**
  53          * Constant for the Search-Operation to indicate a One-Level
  54          * Search
  55          */
  56         static const int SEARCH_ONE=1;
  57
  58         /**
  59          * Constant for the Search-Operation to indicate a subtree
  60          * Search
  61          */
  62         static const int SEARCH_SUB=2;
  63 //        static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
  64 //        static const int SEARCH_ONE=LDAP_SCOPE_ONELEVEL;
  65 //        static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
  66
  67         /** Construtor that initializes a connection to a server
  68          * @param hostname Name (or IP-Adress) of the destination host
  69          * @param port Port the LDAP server is running on
  70          * @param cons Default constraints to use with operations over
  71          *      this connection
  72          */
  73         LDAPAsynConnection(const std::string& hostname=std::string("localhost"),
  74                 int port=389, LDAPConstraints *cons=new LDAPConstraints() );
  75
  76         //* Destructor
  77         virtual ~LDAPAsynConnection();
  78
  79         /**
  80          * Initializes a connection to a server.
  81          *
  82          * There actually no
  83          * communication to the server. Just the object is initialized
  84          * (e.g. this method is called within the
  85          * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.)
  86          * @param hostname  The Name or IP-Address of the destination
  87          *             LDAP-Server
  88          * @param port      The Network Port the server is running on
  89          */
  90         void init(const std::string& hostname, int port);
  91
  92         /**
  93          * Start TLS on this connection.  This isn't in the constructor,
  94          * because it could fail (i.e. server doesn't have SSL cert, client
  95          * api wasn't compiled against OpenSSL, etc.).
  96          * @throws LDAPException if the TLS Layer could not be setup
  97          * correctly
  98          */
  99         void start_tls();
 100
 101         /** Simple authentication to a LDAP-Server
 102          *
 103          * @throws LDAPException If the Request could not be sent to the
 104          *      destination server, a LDAPException-object contains the
 105          *      error that occured.
 106          * This method does a simple (username, password) bind to the server.
 107          * Other, saver, authentcation methods are provided later
 108          * @param dn the distiguished name to bind as
 109          * @param passwd cleartext password to use
 110          */
 111         LDAPMessageQueue* bind(const std::string& dn="", const std::string& passwd="",
 112                 const LDAPConstraints *cons=0);
 113
 114         /** Performing a search on a directory tree.
 115          *
 116          * Use the search method to perform a search on the LDAP-Directory
 117          * @throws LDAPException If the Request could not be sent to the
 118          *      destination server, a LDAPException-object contains the
 119          *      error that occured.
 120          * @param base The distinguished name of the starting point for the
 121          *      search operation
 122          * @param scope The scope of the search. Possible values: <BR>
 123          *      LDAPAsynConnection::SEARCH_BASE, <BR>
 124          *      LDAPAsynConnection::SEARCH_ONE, <BR>
 125          *      LDAPAsynConnection::SEARCH_SUB
 126          * @param filter The std::string representation of a search filter to
 127          *      use with this operation
 128          * @param attrsOnly true if only the attributes names (no values)
 129          *      should be returned
 130          * @param cons A set of constraints that should be used with this
 131          *      request
 132          */
 133         LDAPMessageQueue* search(const std::string& base="", int scope=0,
 134                                  const std::string& filter="objectClass=*",
 135                                  const StringList& attrs=StringList(),
 136                                  bool attrsOnly=false,
 137                                  const LDAPConstraints *cons=0);
 138
 139         /** Delete an entry from the directory
 140          *
 141          * This method sends a delete request to the server
 142          * @throws LDAPException If the Request could not be sent to the
 143          *      destination server, a LDAPException-object contains the
 144          *      error that occured.
 145          * @param dn    Distinguished name of the entry that should be deleted
 146          * @param cons  A set of constraints that should be used with this
 147          *              request
 148          */
 149         LDAPMessageQueue* del(const std::string& dn, const LDAPConstraints *cons=0);
 150
 151         /**
 152          * Perform the COMPARE-operation on an attribute
 153          *
 154          * @throws LDAPException If the Request could not be sent to the
 155          *      destination server, a LDAPException-object contains the
 156          *      error that occured.
 157          * @param dn    Distinguished name of the entry for which the compare
 158          *              should be performed
 159          * @param attr  An Attribute (one (!) value) to use for the
 160          *      compare operation
 161          * @param cons  A set of constraints that should be used with this
 162          *              request
 163          */
 164         LDAPMessageQueue* compare(const std::string& dn,
 165                 const LDAPAttribute& attr,
 166                 const LDAPConstraints *cons=0);
 167
 168         /** Add an entry to the directory
 169          *
 170          * @throws LDAPException If the Request could not be sent to the
 171          *      destination server, a LDAPException-object contains the
 172          *      error that occured.
 173          * @param le The entry that will be added to the directory
 174          */
 175         LDAPMessageQueue* add( const LDAPEntry* le,
 176                 const LDAPConstraints *const=0);
 177
 178         /** Apply modifications to attributes of an entry
 179          *
 180          * @throws LDAPException If the Request could not be sent to the
 181          *      destination server, a LDAPException-object contains the
 182          *      error that occured.
 183          * @param dn Distiguished Name of the Entry to modify
 184          * @param modlist A set of modification that should be applied
 185          *      to the Entry
 186          * @param cons  A set of constraints that should be used with this
 187          *              request
 188          */
 189         LDAPMessageQueue* modify(const std::string& dn,
 190                 const LDAPModList *modlist,
 191                 const LDAPConstraints *cons=0);
 192
 193         /** modify the DN of an entry
 194          *
 195          * @throws LDAPException If the Request could not be sent to the
 196          *      destination server, a LDAPException-object contains the
 197          *      error that occured.
 198          * @param dn            DN to modify
 199          * @param newRDN        The new relative DN for the entry
 200          * @param delOldRDN     true=The old RDN will be removed from the
 201          *                      attributes <BR>
 202          *                      false=The old RDN will still be present in the
 203          *                      attributes of the entry
 204          * @param newParentDN   The DN of the new parent entry of the entry
 205          *                      0 to keep the old one
 206          */
 207         LDAPMessageQueue* rename(const std::string& dn,
 208                 const std::string& newRDN,
 209                 bool delOldRDN=false, const std::string& newParentDN="",
 210                 const LDAPConstraints* cons=0);
 211
 212         /** Perform a LDAP extended Operation
 213          *
 214          * @throws LDAPException If the Request could not be sent to the
 215          *      destination server, a LDAPException-object contains the
 216          *      error that occured.
 217          * @param oid The dotted decimal representation of the extended
 218          *      Operation that should be performed
 219          * @param value The data asociated with this operation
 220          * @param cons  A set of constraints that should be used with this
 221          *              request
 222          */
 223         LDAPMessageQueue* extOperation(const std::string& oid,
 224                 const std::string& value="", const LDAPConstraints *cons=0);
 225
 226         /** End an outstanding request
 227          *
 228          * @param q All outstanding request related to this LDAPMessageQueue
 229          *      will be abandoned
 230          */
 231         void abandon(LDAPMessageQueue *q);
 232
 233         /**
 234          * Performs the UNBIND-operation on the destination server
 235          *
 236          * @throws LDAPException in any case of an error
 237          */
 238         void unbind();
 239
 240         /**
 241          * @returns The C-APIs LDAP-structure that is associated with the
 242          *      current connection
 243          */
 244         LDAP* getSessionHandle() const ;
 245
 246         /**
 247          * @returns The Hostname of the destination server of the
 248          *      connection.
 249          */
 250         const std::string& getHost() const;
 251
 252         /**
 253          * @returns The Port to which this connection is connecting to on
 254          *      the remote server.
 255          */
 256         int getPort() const;
 257
 258         /** Change the default constraints of the connection
 259          *
 260          * @parameter cons cons New LDAPConstraints to use with the connection
 261          */
 262         void setConstraints(LDAPConstraints *cons);
 263
 264         /** Get the default constraints of the connection
 265          *
 266          * @return Pointer to the LDAPConstraints-Object that is currently
 267          *      used with the Connection
 268          */
 269         const LDAPConstraints* getConstraints() const;
 270
 271         /**
 272          * This method is used internally for automatic referral chasing.
 273          * It tries to bind to a destination server of the URLs of a
 274          * referral.
 275          *
 276          * @throws LDAPException in any case of an error
 277          * @param urls Contains a std::list of LDAP-Urls that indicate the
 278          *      destinations of a referral
 279          * @param usedUrl After this method has successfully bind to one of
 280          *      the Destination URLs this parameter contains the URLs
 281          *      which was contacted.
 282          * @param cons An LDAPConstraints-Object that should be used for
 283          *      the new connection. If this object contains a
 284          *      LDAPRebind-object it is used to bind to the new server
 285          */
 286         LDAPAsynConnection* referralConnect(const LDAPUrlList& urls,
 287                 LDAPUrlList::const_iterator& usedUrl,
 288                 const LDAPConstraints* cons) const;
 289
 290     private :
 291         /**
 292          * Private copy constructor. So nobody can call it.
 293          */
 294         LDAPAsynConnection(const LDAPAsynConnection& lc){};
 295
 296         /**
 297          * A pointer to the C-API LDAP-structure that is associated with
 298          * this connection
 299          */
 300         LDAP *cur_session;
 301
 302         /**
 303          * A pointer to the default LDAPConstrains-object that is used when
 304          * no LDAPConstraints-parameter is provided with a call for a
 305          * LDAP-operation
 306          */
 307         LDAPConstraints *m_constr;
 308
 309         /**
 310          * The name of the destination host
 311          */
 312         std::string m_host;
 313
 314         /**
 315          * The port the destination server is running on.
 316          */
 317         int m_port;
 318
 319  protected:
 320         /**
 321          * Is caching enabled?
 322          */
 323         bool m_cacheEnabled;
 324 };
 325 #endif //LDAP_ASYN_CONNECTION_H
 326
 327