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 std::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 std::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.).
  75          * @throws LDAPException if the TLS Layer could not be setup
  76          * correctly
  77          */
  78         void start_tls();
  79
  80         /**
  81          * Performs a simple authentication with the server
  82          *
  83          * @throws LDAPReferralException if a referral is received
  84          * @throws LDAPException for any other error occuring during the
  85          *              operation
  86          * @param dn    The name of the entry to bind as
  87          * @param passwd    The cleartext password for the entry
  88          */
  89         void bind(const std::string& dn="", const std::string& passwd="",
  90                 LDAPConstraints* cons=0);
  91
  92         /**
  93          * Performs the UNBIND-operation on the destination server
  94          *
  95          * @throws LDAPException in any case of an error
  96          */
  97         void unbind();
  98
  99         /**
 100          * Performs a COMPARE-operation on an entery of the destination
 101          * server.
 102          *
 103          * @throws LDAPReferralException if a referral is received
 104          * @throws LDAPException for any other error occuring during the
 105          *              operation
 106          * @param dn    Distinguished name of the entry for which the compare
 107          *              should be performed
 108          * @param attr  An Attribute (one (!) value) to use for the
 109          *      compare operation
 110          * @param cons  A set of constraints that should be used with this
 111          *              request
 112          * @returns The result of the compare operation. true if the
 113          *      attr-parameter matched an Attribute of the entry. false if it
 114          *      did not match
 115          */
 116         bool compare(const std::string& dn, const LDAPAttribute& attr,
 117                 LDAPConstraints* cons=0);
 118
 119         /**
 120          * Deletes an entry from the directory
 121          *
 122          * This method performs the DELETE operation on the server
 123          * @throws LDAPReferralException if a referral is received
 124          * @throws LDAPException for any other error occuring during the
 125          *              operation
 126          * @param dn    Distinguished name of the entry that should be deleted
 127          * @param cons  A set of constraints that should be used with this
 128          *              request
 129          */
 130         void del(const std::string& dn, const LDAPConstraints* cons=0);
 131
 132         /**
 133          * Use this method to perform the ADD-operation
 134          *
 135          * @throws LDAPReferralException if a referral is received
 136          * @throws LDAPException for any other error occuring during the
 137          *              operation
 138          * @param le    the entry to add to the directory
 139          * @param cons  A set of constraints that should be used with this
 140          *              request
 141          */
 142         void add(const LDAPEntry* le, const LDAPConstraints* cons=0);
 143
 144         /**
 145          * To modify the attributes of an entry, this method can be used
 146          *
 147          * @throws LDAPReferralException if a referral is received
 148          * @throws LDAPException for any other error occuring during the
 149          *              operation
 150          * @param dn    The DN of the entry which should be modified
 151          * @param mods  A set of modifications for that entry.
 152          * @param cons  A set of constraints that should be used with this
 153          *              request
 154          */
 155         void modify(const std::string& dn, const LDAPModList* mods,
 156                 const LDAPConstraints* cons=0);
 157
 158         /**
 159          * This method performs the ModDN-operation.
 160          *
 161          * It can be used to rename or move an entry by modifing its DN.
 162          *
 163          * @throws LDAPReferralException if a referral is received
 164          * @throws LDAPException for any other error occuring during the
 165          *              operation
 166          * @param dn    The DN that should be modified
 167          * @param newRDN    If the RDN of the entry should be modified the
 168          *                  new RDN can be put here.
 169          * @param delOldRDN If the old RDN should be removed from the
 170          *                  entry's attribute this parameter has to be
 171          *                  "true"
 172          * @param newParentDN   If the entry should be moved inside the
 173          *                      DIT, the DN of the new parent of the entry
 174          *                      can be given here.
 175          * @param cons  A set of constraints that should be used with this
 176          *              request
 177          */
 178         void rename(const std::string& dn, const std::string& newRDN,
 179                 bool delOldRDN=false, const std::string& newParentDN="",
 180                 const LDAPConstraints* cons=0);
 181
 182         /**
 183          * This method can be used for the sync. SEARCH-operation.
 184          *
 185          * @throws LDAPReferralException if a referral is received
 186          * @throws LDAPException for any other error occuring during the
 187          *              operation
 188          * @param base The distinguished name of the starting point for the
 189          *      search
 190          * @param scope The scope of the search. Possible values: <BR>
 191          *      LDAPAsynConnection::SEARCH_BASE, <BR>
 192          *      LDAPAsynConnection::SEARCH_ONE, <BR>
 193          *      LDAPAsynConnection::SEARCH_SUB
 194          * @param filter The std::string representation of a search filter to
 195          *      use with this operation
 196          * @param attrsOnly true if only the attributes names (no values)
 197          *      should be returned
 198          * @param cons A set of constraints that should be used with this
 199          *      request
 200          * @returns A pointer to a LDAPSearchResults-object that can be
 201          *      used to read the results of the search.
 202          */
 203         LDAPSearchResults* search(const std::string& base, int scope=0,
 204                 const std::string& filter="objectClass=*",
 205                 const StringList& attrs=StringList(), bool attrsOnly=false,
 206                 const LDAPConstraints* cons=0);
 207
 208         /**
 209          * This method is for extended LDAP-Operations.
 210          *
 211          * @throws LDAPReferralException if a referral is received
 212          * @throws LDAPException for any other error occuring during the
 213          *              operation
 214          * @param oid The Object Identifier of the Extended Operation that
 215          *          should be performed.
 216          * @param strint If the Extended Operation needs some additional
 217          *          data it can be passed to the server by this parameter.
 218          * @param cons A set of constraints that should be used with this
 219          *      request
 220          * @returns The result of the Extended Operation as an
 221          *      pointer to a LDAPExtResult-object.
 222          */
 223         LDAPExtResult* extOperation(const std::string& oid, const std::string&
 224                 value="", const LDAPConstraints *const = 0);
 225
 226         const std::string& getHost() const;
 227
 228         int getPort() const;
 229
 230         void setConstraints(LDAPConstraints *cons);
 231
 232         const LDAPConstraints* getConstraints() const ;
 233 };
 234
 235 #endif //LDAP_CONNECTION_H