1// $OpenLDAP$
2/*
3 * Copyright 2000-2011 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 */
21class 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
242