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_LDAPCONNECTION_H
22#define KLDAP_LDAPCONNECTION_H
23
24#include <QtCore/QString>
25
26#include "ldapurl.h"
27#include "ldapserver.h"
28#include "kldap_export.h"
29
30namespace KLDAP {
31
32/**
33 * @brief
34 * This class represents a connection to an LDAP server.
35 */
36class KLDAP_EXPORT LdapConnection
37{
38 public:
39
40 enum SASL_Fields {
41 SASL_Authname = 0x1,
42 SASL_Authzid = 0x2,
43 SASL_Realm = 0x4,
44 SASL_Password = 0x8
45 };
46
47 /** Constructs an LdapConnection object */
48 LdapConnection();
49 /** Constructs an LdapConnection with the parameters given in url */
50 explicit LdapConnection( const LdapUrl &url );
51 /** Constructs an LdapConnection with the parameters given in server */
52 explicit LdapConnection( const LdapServer &server );
53
54 virtual ~LdapConnection();
55
56 /**
57 * Sets the connection parameters via the specified url. After this,
58 * you need to call connect() to connect with the new parameters.
59 * @param url the URL containing the connection parameters
60 */
61 void setUrl( const LdapUrl &url );
62 /**
63 * Returns the connection parameters which was specified with an LDAP Url
64 * or a LdapServer structure.
65 */
66 const LdapServer &server() const;
67 /**
68 * Sets the connection parameters via the specified server structure. After
69 * this, you need to call connect() to connect with the new parameters.
70 * @param server the server object containing the connection parameters
71 */
72 void setServer( const LdapServer &server );
73
74 /**
75 * Sets up the connection parameters with creating a handle to the LDAP server.
76 * Also sets sizelimit and timelimit and starts TLS if it is requested.
77 * Returns 0 if successful, else returns an LDAP error code, and an error
78 * string which is available via connectionError().
79 */
80 int connect();
81 /**
82 * Returns a translated error string if connect() failed.
83 */
84 QString connectionError() const;
85 /**
86 * Closes the LDAP connection.
87 */
88 void close();
89
90 /** Sets the size limit for the connection.
91 * @param sizelimit the connection size limit to set
92 */
93 bool setSizeLimit( int sizelimit );
94 /** Returns the current size limit. */
95 int sizeLimit() const;
96
97 /** Sets the time limit for the connection.
98 * @param timelimit the connection time limit to set
99 */
100 bool setTimeLimit( int timelimit );
101 /** Returns the current time limit. */
102 int timeLimit() const;
103
104 /** Gets an option from the connection. The option value can be client
105 * library specific, so avoid this function if possible
106 * @param option the connection option to return
107 * @param value the value of option to get
108 */
109 int getOption( int option, void *value ) const;
110 /** Sets an option in the connection. The option value can be client
111 * library specific, so avoid this function if possible */
112 int setOption( int option, void *value );
113
114 /** Returns the LDAP error code from the last operation */
115 int ldapErrorCode() const;
116 /** Returns the LDAP error string from the last operation */
117 QString ldapErrorString() const;
118 /** Returns a translated error message from the specified LDAP error code */
119 static QString errorString( int code );
120
121 /** Returns the SASL error string from the last SASL operation */
122 QString saslErrorString() const;
123
124 /**
125 * Returns the opaqe client-library specific LDAP object.
126 * Avoid its usage if you can.
127 */
128 void *handle() const;
129
130 /**
131 * Returns the opaqe sasl-library specific SASL object.
132 * Avoid its usage if you can.
133 */
134 void *saslHandle() const;
135
136 private:
137 class LdapConnectionPrivate;
138 LdapConnectionPrivate *const d;
139
140 Q_DISABLE_COPY( LdapConnection )
141};
142
143}
144
145#endif
146