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