1 | /* |
2 | This file is part of libkldap. |
3 | Copyright (c) 2004-2006 Szombathelyi György <gyurco@freemail.hu> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2 of the License, or (at your option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KLDAP_LDAPOPERATION_H |
22 | #define KLDAP_LDAPOPERATION_H |
23 | |
24 | #include "kldap_export.h" |
25 | #include "ldapconnection.h" |
26 | #include "ldapcontrol.h" |
27 | #include "ldapobject.h" |
28 | #include "ldapdn.h" |
29 | #include "ldapserver.h" |
30 | #include "ldapurl.h" |
31 | |
32 | #include <QtCore/QByteArray> |
33 | #include <QtCore/QList> |
34 | #include <QtCore/QString> |
35 | |
36 | namespace KLDAP { |
37 | |
38 | /** |
39 | * @brief |
40 | * This class allows sending an ldap operation |
41 | * (search, rename, modify, delete, compare, exop) to an LDAP server. |
42 | */ |
43 | class KLDAP_EXPORT LdapOperation |
44 | { |
45 | public: |
46 | typedef enum { |
47 | Mod_None, Mod_Add, Mod_Replace, Mod_Del |
48 | } ModType; |
49 | |
50 | typedef enum { |
51 | RES_BIND = 0x61, |
52 | RES_SEARCH_ENTRY = 0x64, |
53 | RES_SEARCH_REFERENCE = 0x73, |
54 | RES_SEARCH_RESULT = 0x65, |
55 | RES_MODIFY = 0x67, |
56 | RES_ADD = 0x69, |
57 | RES_DELETE = 0x69, |
58 | RES_MODDN = 0x6d, |
59 | RES_COMPARE = 0x6f, |
60 | RES_EXTENDED = 0x78, |
61 | RES_EXTENDED_PARTIAL = 0x79 |
62 | } ResultType; |
63 | |
64 | typedef struct { |
65 | ModType type; |
66 | QString attr; |
67 | QList<QByteArray> values; |
68 | } ModOp ; |
69 | |
70 | typedef QList<ModOp> ModOps; |
71 | |
72 | enum SASL_Fields { |
73 | SASL_Authname = 0x1, |
74 | SASL_Authzid = 0x2, |
75 | SASL_Realm = 0x4, |
76 | SASL_Password = 0x8 |
77 | }; |
78 | |
79 | struct SASL_Credentials { |
80 | int fields; |
81 | QString authname; |
82 | QString authzid; |
83 | QString realm; |
84 | QString password; |
85 | }; |
86 | |
87 | typedef int (SASL_Callback_Proc) ( SASL_Credentials &cred, void *data ); |
88 | |
89 | struct SASL_Data { |
90 | SASL_Callback_Proc *proc; |
91 | void *data; |
92 | SASL_Credentials creds; |
93 | }; |
94 | |
95 | LdapOperation(); |
96 | LdapOperation( LdapConnection &conn ); |
97 | virtual ~LdapOperation(); |
98 | |
99 | /** |
100 | * Sets the connection object. Without living connection object, |
101 | * LDAP operations are not possible. |
102 | * @param the connection object to set |
103 | */ |
104 | void setConnection( LdapConnection &conn ); |
105 | /** |
106 | * Returns the connection object. |
107 | */ |
108 | LdapConnection &connection(); |
109 | /** |
110 | * Sets the client controls which will sent with each operation. |
111 | */ |
112 | void setClientControls( const LdapControls &ctrls ); |
113 | /** |
114 | * Sets the server controls which will sent with each operation. |
115 | */ |
116 | void setServerControls( const LdapControls &ctrls ); |
117 | /** |
118 | * Returns the client controls (which set by setClientControls()). |
119 | */ |
120 | LdapControls clientControls() const; |
121 | /** |
122 | * Returns the server controls (which set by setServerControls()). |
123 | */ |
124 | LdapControls serverControls() const; |
125 | |
126 | /** |
127 | * Binds to the server which specified in the connection object. |
128 | * Can do simple or SASL bind. Returns a message id if successful, negative value if not. |
129 | */ |
130 | int bind( const QByteArray &creds = QByteArray(), |
131 | SASL_Callback_Proc *saslproc = NULL, void *data = NULL ); |
132 | |
133 | /** |
134 | * Binds to the server which specified in the connection object. |
135 | * Can do simple or SASL bind. This is the synchronous version. |
136 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
137 | */ |
138 | int bind_s( SASL_Callback_Proc *saslproc = NULL, void *data = NULL ); |
139 | |
140 | /** |
141 | * Starts a search operation with the given base DN, scope, filter and |
142 | * result attributes. Returns a message id if successful, -1 if not. |
143 | */ |
144 | int search( const LdapDN &base, LdapUrl::Scope scope, |
145 | const QString &filter, const QStringList &attrs ); |
146 | /** |
147 | * Starts an addition operation. |
148 | * Returns a message id if successful, -1 if not. |
149 | * @param object the additional operation to start |
150 | */ |
151 | int add( const LdapObject &object ); |
152 | /** |
153 | * Adds the specified object to the LDAP database. |
154 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
155 | * @param object the object to add to LDAP database |
156 | */ |
157 | int add_s( const LdapObject &object ); |
158 | /** |
159 | * Starts an addition operation. This version accepts ModOps not LdapObject. |
160 | * Returns a message id if successful, -1 if not. |
161 | * @param dn the LdapDN operation to start |
162 | * @param ops the ModOps operation to start |
163 | */ |
164 | int add( const LdapDN &dn, const ModOps &ops ); |
165 | /** |
166 | * Adds the specified object to the LDAP database. This version accepts ModOps not LdapObject. |
167 | * This is the synchronous version. |
168 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
169 | * @param dn the LdapDN object to add |
170 | * @param ops the ModOps object to add |
171 | */ |
172 | int add_s( const LdapDN &dn, const ModOps &ops ); |
173 | /** |
174 | * Starts a modrdn operation on given DN, changing its RDN to newRdn, |
175 | * changing its parent to newSuperior (if it's not empty), and deletes |
176 | * the old dn if deleteold is true. |
177 | * Returns a message id if successful, -1 if not. |
178 | */ |
179 | int rename( const LdapDN &dn, const QString &newRdn, |
180 | const QString &newSuperior, bool deleteold = true ); |
181 | /** |
182 | * Performs a modrdn operation on given DN, changing its RDN to newRdn, |
183 | * changing its parent to newSuperior (if it's not empty), and deletes |
184 | * the old dn if deleteold is true. This is the synchronous version. |
185 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
186 | */ |
187 | int rename_s( const LdapDN &dn, const QString &newRdn, |
188 | const QString &newSuperior, bool deleteold = true ); |
189 | /** |
190 | * Starts a delete operation on the given DN. |
191 | * Returns a message id if successful, -1 if not. |
192 | */ |
193 | int del( const LdapDN &dn ); |
194 | /** |
195 | * Deletes the given DN. This is the synchronous version. |
196 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
197 | * @param dn the dn to delete |
198 | */ |
199 | int del_s( const LdapDN &dn ); |
200 | /** |
201 | * Starts a modify operation on the given DN. |
202 | * Returns a message id if successful, -1 if not. |
203 | * @param dn the DN to start modify operation on |
204 | */ |
205 | int modify( const LdapDN &dn, const ModOps &ops ); |
206 | /** |
207 | * Performs a modify operation on the given DN. |
208 | * This is the synchronous version. |
209 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
210 | */ |
211 | int modify_s( const LdapDN &dn, const ModOps &ops ); |
212 | /** |
213 | * Starts a compare operation on the given DN, compares the specified |
214 | * attribute with the given value. |
215 | * Returns a message id if successful, -1 if not. |
216 | */ |
217 | int compare( const LdapDN &dn, const QString &attr, const QByteArray &value ); |
218 | /** |
219 | * Performs a compare operation on the given DN, compares the specified |
220 | * attribute with the given value. This is the synchronous version. |
221 | * Returns KLDAP_COMPARE_TRUE if the entry contains the attribute value |
222 | * and KLDAP_COMPARE_FALSE if it does not. Otherwise, some error code |
223 | * is returned. |
224 | */ |
225 | int compare_s( const LdapDN &dn, const QString &attr, const QByteArray &value ); |
226 | /** |
227 | * Starts an extended operation specified with oid and data. |
228 | * Returns a message id if successful, -1 if not. |
229 | */ |
230 | int exop( const QString &oid, const QByteArray &data ); |
231 | /** |
232 | * Performs an extended operation specified with oid and data. |
233 | * This is the synchronous version. |
234 | * Returns KLDAP_SUCCESS id if successful, else an LDAP error code. |
235 | */ |
236 | int exop_s( const QString &oid, const QByteArray &data ); |
237 | /** |
238 | * Abandons a long-running operation. Requires the message id. |
239 | */ |
240 | int abandon( int id ); |
241 | /** |
242 | * Waits for up to \p msecs milliseconds for a result message from the LDAP |
243 | * server. If \p msecs is -1, then this function will block indefinitely. |
244 | * If \p msecs is 0, then this function will return immediately, that is it |
245 | * will perform a poll for a result message. |
246 | * |
247 | * Returns the type of the result LDAP message (RES_XXX constants). |
248 | * -1 if error occurred, 0 if the timeout value elapsed. Note! |
249 | * Return code -1 means that fetching the message resulted in error, |
250 | * not the LDAP operation error. Call connection().ldapErrorCode() to |
251 | * determine if the operation succeeded. |
252 | */ |
253 | int waitForResult( int id, int msecs = -1 ); |
254 | /** |
255 | * Returns the result object if result() returned RES_SEARCH_ENTRY. |
256 | */ |
257 | LdapObject object() const; |
258 | /** |
259 | * Returns the server controls from the returned ldap message (grabbed |
260 | * by result()). |
261 | */ |
262 | LdapControls controls() const; |
263 | /** |
264 | * Returns the OID of the extended operation response (result |
265 | * returned RES_EXTENDED). |
266 | */ |
267 | QByteArray extendedOid() const; |
268 | /** |
269 | * Returns the data from the extended operation response (result |
270 | * returned RES_EXTENDED). |
271 | */ |
272 | QByteArray extendedData() const; |
273 | /** |
274 | * The server might supply a matched DN string in the message indicating |
275 | * how much of a name in a request was recognized. This can be grabbed by |
276 | * matchedDn(). |
277 | */ |
278 | QString matchedDn() const; |
279 | /** |
280 | * This function returns the referral strings from the parsed message |
281 | * (if any). |
282 | */ |
283 | QList<QByteArray> referrals() const; |
284 | /** |
285 | * Returns the server response for a bind request (result |
286 | * returned RES_BIND). |
287 | */ |
288 | QByteArray serverCred() const; |
289 | |
290 | private: |
291 | class LdapOperationPrivate; |
292 | LdapOperationPrivate *const d; |
293 | |
294 | Q_DISABLE_COPY( LdapOperation ) |
295 | }; |
296 | |
297 | } |
298 | |
299 | #endif |
300 | |