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

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