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

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