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_LDAPSEARCH_H
22#define KLDAP_LDAPSEARCH_H
23
24#include <QtCore/QByteArray>
25#include <QtCore/QList>
26#include <QtCore/QObject>
27#include <QtCore/QString>
28
29#include "kldap_export.h"
30
31#include "ldapconnection.h"
32#include "ldapcontrol.h"
33#include "ldapobject.h"
34#include "ldapoperation.h"
35#include "ldapserver.h"
36#include "ldapurl.h"
37
38namespace KLDAP {
39
40/**
41 * @brief
42 * This class starts a search operation on a LDAP server and returns the
43 * search values via a Qt signal.
44 */
45class KLDAP_EXPORT LdapSearch : public QObject
46{
47 Q_OBJECT
48
49 public:
50 /**
51 * Constructs an LdapSearch object
52 */
53 LdapSearch();
54
55 /**
56 * Constructs an LdapConnection object with the given connection. If this
57 * form of constructor used, then always this connection will be used
58 * regardless of the LDAP Url or LdapServer object passed to search().
59 * @param connection the connection used to construct LdapConnection object
60 */
61 explicit LdapSearch( LdapConnection &connection );
62
63 virtual ~LdapSearch();
64
65 /**
66 * Sets the connection for this object to use for searches from now
67 * onwards, regardless of the LDAP Url or LdapServer object passed to
68 * search().
69 */
70 void setConnection( LdapConnection &connection );
71
72 /**
73 * Sets the client controls which will sent with each operation.
74 */
75 void setClientControls( const LdapControls &ctrls );
76
77 /**
78 * Sets the server controls which will sent with each operation.
79 */
80 void setServerControls( const LdapControls &ctrls );
81
82 /**
83 * Starts a search operation on the LDAP server @param server,
84 * returning the attributes specified with @param attributes.
85 * @param count means how many entries to list. If it's >0, then result()
86 * will be emitted when the number of entries is reached, but with
87 * isFinished() set to false.
88 */
89 bool search( const LdapServer &server,
90 const QStringList &attributes = QStringList(), int count = 0 );
91
92 /**
93 * Starts a search operation on the given LDAP URL.
94 */
95 bool search( const LdapUrl &url, int count = 0 );
96
97 /**
98 * Starts a search operation if the LdapConnection object already set
99 * in the constructor.
100 */
101 bool search( const LdapDN &base,
102 LdapUrl::Scope scope = LdapUrl::Sub,
103 const QString &filter = QString(),
104 const QStringList &attributes = QStringList(),
105 int pagesize = 0, int count = 0 );
106
107 /**
108 * Continues the search (if you set count to non-zero in search(), and isFinished() is false)
109 */
110 void continueSearch();
111 /**
112 * Returns true if the search is finished else returns false.
113 */
114 bool isFinished();
115 /**
116 * Tries to abandon the search.
117 */
118 void abandon();
119
120 /**
121 * Returns the error code of the search operation (0 if no error).
122 */
123 int error() const;
124
125 /**
126 * Returns the error description of the search operation.
127 */
128 QString errorString() const;
129
130 Q_SIGNALS:
131 /**
132 * Emitted for each result object.
133 */
134 void data( KLDAP::LdapSearch *search, const KLDAP::LdapObject &obj );
135
136 /**
137 * Emitted when the searching finished.
138 */
139 void result( KLDAP::LdapSearch *search );
140
141 private:
142 class Private;
143 Private *const d;
144
145 Q_PRIVATE_SLOT( d, void result() )
146
147 Q_DISABLE_COPY( LdapSearch )
148};
149
150}
151
152#endif
153