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

   1 /*
   2  * Copyright 2000, OpenLDAP Foundation, All Rights Reserved.
   3  * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
   4  */
   5
   6 #ifndef LDAP_CONNECTION_H
   7 #define LDAP_CONNECTION_H
   8
   9 #include <LDAPSearchResults.h>
  10 #include <LDAPExtResult.h>
  11 #include <LDAPAsynConnection.h>
  12
  13 /** Main class for synchronous LDAP-Communication
  14  *
  15  * The class represent a LDAP-Connection to perform synchronous
  16  * LDAP-Operations. This provides methodes for the different
  17  * LDAP-Operations. All the methods for the LDAP-operations block until
  18  * all results for the operation are received or until an error occurs
  19  */
  20 class LDAPConnection : private LDAPAsynConnection {
  21
  22     public :
  23         /**
  24          * Constant for the Search-Operation to indicate a Base-Level
  25          * Search
  26          */
  27         static const int SEARCH_BASE;
  28
  29         /**
  30          * Constant for the Search-Operation to indicate a One-Level
  31          * Search
  32          */
  33         static const int SEARCH_ONE;
  34
  35         /**
  36          * Constant for the Search-Operation to indicate a Subtree
  37          * Search
  38          */
  39         static const int SEARCH_SUB;
  40
  41         /** This Constructor initializes synchronous LDAP-Connection
  42          *
  43          * During execution of this constructor no network communication
  44          * is performed. Just some internal data structure are initialized
  45          * @param hostname Name (or IP-Adress) of the destination host
  46          * @param port Port the LDAP server is running on
  47          * @param cons Default constraints to use with operations over
  48          *      this connection
  49          */
  50         LDAPConnection(const string& hostname="localhost", int port=389,
  51                 LDAPConstraints* cons=new LDAPConstraints());
  52
  53         /**
  54          * Destructor
  55          */
  56         ~LDAPConnection();
  57
  58         /**
  59          * Initzializes a synchronous connection to a server.
  60          *
  61          * There is actually no
  62          * communication to the server. Just the object is initialized
  63          * (e.g. this method is called within the
  64          * LDAPConnection(char*,int,LDAPConstraints) constructor.)
  65          * @param hostname  The Name or IP-Address of the destination
  66          *             LDAP-Server
  67          * @param port      The Network Port the server is running on
  68          */
  69         void init(const string& hostname, int port);
  70
  71         /**
  72          * Start TLS on this connection.  This isn't in the constructor,
  73          * because it could fail (i.e. server doesn't have SSL cert, client
  74          * api wasn't compiled against OpenSSL, etc.).  If you need TLS,
  75          * then you should error if this call fails with an error code.
  76          */
  77         int start_tls();
  78
  79         /**
  80          * Performs a simple authentication with the server
  81          *
  82          * @throws LDAPReferralException if a referral is received
  83          * @throws LDAPException for any other error occuring during the
  84          *              operation
  85          * @param dn    The name of the entry to bind as
  86          * @param passwd    The cleartext password for the entry
  87          */
  88         void bind(const string& dn="", const string& passwd="",
  89                 LDAPConstraints* cons=0);
  90
  91         /**
  92          * Performs the UNBIND-operation on the destination server
  93          *
  94          * @throws LDAPException in any case of an error
  95          */
  96         void unbind();
  97
  98         /**
  99          * Performs a COMPARE-operation on an entery of the destination
 100          * server.
 101          *
 102          * @throws LDAPReferralException if a referral is received
 103          * @throws LDAPException for any other error occuring during the
 104          *              operation
 105          * @param dn    Distinguished name of the entry for which the compare
 106          *              should be performed
 107          * @param attr  An Attribute (one (!) value) to use for the
 108          *      compare operation
 109          * @param cons  A set of constraints that should be used with this
 110          *              request
 111          * @returns The result of the compare operation. true if the
 112          *      attr-parameter matched an Attribute of the entry. false if it
 113          *      did not match
 114          */
 115         bool compare(const string& dn, const LDAPAttribute& attr,
 116                 LDAPConstraints* cons=0);
 117
 118         /**
 119          * Deletes an entry from the directory
 120          *
 121          * This method performs the DELETE operation on the server
 122          * @throws LDAPReferralException if a referral is received
 123          * @throws LDAPException for any other error occuring during the
 124          *              operation
 125          * @param dn    Distinguished name of the entry that should be deleted
 126          * @param cons  A set of constraints that should be used with this
 127          *              request
 128          */
 129         void del(const string& dn, const LDAPConstraints* cons=0);
 130
 131         /**
 132          * Use this method to perform the ADD-operation
 133          *
 134          * @throws LDAPReferralException if a referral is received
 135          * @throws LDAPException for any other error occuring during the
 136          *              operation
 137          * @param le    the entry to add to the directory
 138          * @param cons  A set of constraints that should be used with this
 139          *              request
 140          */
 141         void add(const LDAPEntry* le, const LDAPConstraints* cons=0);
 142
 143         /**
 144          * To modify the attributes of an entry, this method can be used
 145          *
 146          * @throws LDAPReferralException if a referral is received
 147          * @throws LDAPException for any other error occuring during the
 148          *              operation
 149          * @param dn    The DN of the entry which should be modified
 150          * @param mods  A set of modifications for that entry.
 151          * @param cons  A set of constraints that should be used with this
 152          *              request
 153          */
 154         void modify(const string& dn, const LDAPModList* mods,
 155                 const LDAPConstraints* cons=0);
 156
 157         /**
 158          * This method performs the ModDN-operation.
 159          *
 160          * It can be used to rename or move an entry by modifing its DN.
 161          *
 162          * @throws LDAPReferralException if a referral is received
 163          * @throws LDAPException for any other error occuring during the
 164          *              operation
 165          * @param dn    The DN that should be modified
 166          * @param newRDN    If the RDN of the entry should be modified the
 167          *                  new RDN can be put here.
 168          * @param delOldRDN If the old RDN should be removed from the
 169          *                  entry's attribute this parameter has to be
 170          *                  "true"
 171          * @param newParentDN   If the entry should be moved inside the
 172          *                      DIT, the DN of the new parent of the entry
 173          *                      can be given here.
 174          * @param cons  A set of constraints that should be used with this
 175          *              request
 176          */
 177         void rename(const string& dn, const string& newRDN,
 178                 bool delOldRDN=false, const string& newParentDN="",
 179                 const LDAPConstraints* cons=0);
 180
 181         /**
 182          * This method can be used for the sync. SEARCH-operation.
 183          *
 184          * @throws LDAPReferralException if a referral is received
 185          * @throws LDAPException for any other error occuring during the
 186          *              operation
 187          * @param base The distinguished name of the starting point for the
 188          *      search
 189          * @param scope The scope of the search. Possible values: <BR>
 190          *      LDAPAsynConnection::SEARCH_BASE, <BR>
 191          *      LDAPAsynConnection::SEARCH_ONE, <BR>
 192          *      LDAPAsynConnection::SEARCH_SUB
 193          * @param filter The string representation of a search filter to
 194          *      use with this operation
 195          * @param attrsOnly true if only the attributes names (no values)
 196          *      should be returned
 197          * @param cons A set of constraints that should be used with this
 198          *      request
 199          * @returns A pointer to a LDAPSearchResults-object that can be
 200          *      used to read the results of the search.
 201          */
 202         LDAPSearchResults* search(const string& base, int scope=0,
 203                 const string& filter="objectClass=*",
 204                 const StringList& attrs=StringList(), bool attrsOnly=false,
 205                 const LDAPConstraints* cons=0);
 206
 207         /**
 208          * This method is for extended LDAP-Operations.
 209          *
 210          * @throws LDAPReferralException if a referral is received
 211          * @throws LDAPException for any other error occuring during the
 212          *              operation
 213          * @param oid The Object Identifier of the Extended Operation that
 214          *          should be performed.
 215          * @param strint If the Extended Operation needs some additional
 216          *          data it can be passed to the server by this parameter.
 217          * @param cons A set of constraints that should be used with this
 218          *      request
 219          * @returns The result of the Extended Operation as an
 220          *      pointer to a LDAPExtResult-object.
 221          */
 222         LDAPExtResult* extOperation(const string& oid, const string&
 223                 value="", const LDAPConstraints *const = 0);
 224
 225         const string& getHost() const;
 226
 227         int getPort() const;
 228
 229         void setConstraints(LDAPConstraints *cons);
 230
 231         const LDAPConstraints* getConstraints() const ;
 232
 233         /**
 234          * Turn on caching, maxmem is in MB and timeout is in seconds.
 235          * maxmem can be zero if you want to restrict caching by timeout only.
 236          */
 237         int enableCache(long timeout, long maxmem);
 238         /// disable caching.
 239         void disableCache();
 240         /// is cacheEnabled?
 241         bool getCacheEnabled();
 242         /// uncache a specific dn.  Used internally by methods that write.
 243         void uncache_entry(string &dn);
 244         /// used to clear the cache.  Probably should be used after creating
 245         /// an object that a cached search should find.
 246         void flush_cache();
 247
 248 };
 249
 250 #endif //LDAP_CONNECTION_H