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
36namespace 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 */
43class 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