1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271
|
/******************************************************************************
* Copyright (C) 2011-2015 Frank Osterfeld <frank.osterfeld@gmail.com> *
* *
* This program is distributed in the hope that it will be useful, but *
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY *
* or FITNESS FOR A PARTICULAR PURPOSE. For licensing and distribution *
* details, check the accompanying file 'COPYING'. *
*****************************************************************************/
#ifndef KEYCHAIN_H
#define KEYCHAIN_H
#if !defined(QTKEYCHAIN_NO_EXPORT)
#include "qkeychain_export.h"
#else
#define QKEYCHAIN_EXPORT
#endif
#include <QtCore/QObject>
#include <QtCore/QString>
class QSettings;
#define QTKEYCHAIN_VERSION 0x000100
namespace QKeychain {
/**
* Error codes
*/
enum Error {
NoError=0, /**< No error occurred, operation was successful */
EntryNotFound, /**< For the given key no data was found */
CouldNotDeleteEntry, /**< Could not delete existing secret data */
AccessDeniedByUser, /**< User denied access to keychain */
AccessDenied, /**< Access denied for other reasons */
NoBackendAvailable, /**< No platform-specific keychain service available */
NotImplemented, /**< Not implemented on platform */
OtherError /**< Something else went wrong (errorString() might provide details) */
};
class JobExecutor;
class JobPrivate;
/**
* @brief Abstract base class for all QKeychain jobs.
*/
class QKEYCHAIN_EXPORT Job : public QObject {
Q_OBJECT
public:
~Job();
/**
* @return The QSettings instance used as plaintext storage if insecureFallback() is true.
* @see setSettings()
* @see insecureFallback()
*/
QSettings* settings() const;
/**
* @return Set the QSettings instance that will be used as plaintext storage if insecureFallback() is true.
* @see settings()
* @see insecureFallback()
*/
void setSettings( QSettings* settings );
/**
* Call this method to start the job.
* Typically you want to connect some slot to the finished() signal first:
*
* \code
* SomeClass::startJob()
* {
* connect(job, &Job::finished, this, &SomeClass::slotJobFinished);
* job->start();
* }
*
* SomeClass::slotJobFinished(Job *job)
* {
* if (job->error()) {
* // handle error
* } else {
* // do job-specific stuff
* }
* }
* \endcode
*
* @see finished()
*/
void start();
QString service() const;
/**
* @note Call this method only after finished() has been emitted.
* @return The error code of the job (0 if no error).
*/
Error error() const;
/**
* @return An error message that might provide details if error() returns OtherError.
*/
QString errorString() const;
/**
* @return Whether this job autodeletes itself once finished() has been emitted. Default is true.
* @see setAutoDelete()
*/
bool autoDelete() const;
/**
* Set whether this job should autodelete itself once finished() has been emitted.
* @see autoDelete()
*/
void setAutoDelete( bool autoDelete );
/**
* @return Whether this job will use plaintext storage on unsupported platforms. Default is false.
* @see setInsecureFallback()
*/
bool insecureFallback() const;
/**
* Set whether this job should use plaintext storage on unsupported platforms.
* @see insecureFallback()
*/
void setInsecureFallback( bool insecureFallback );
/**
* @return The string used as key by this job.
* @see setKey()
*/
QString key() const;
/**
* Set the @p key that this job will use to read or write data from/to the keychain.
* The key can be an empty string.
* @see key()
*/
void setKey( const QString& key );
void emitFinished();
void emitFinishedWithError(Error, const QString& errorString);
Q_SIGNALS:
/**
* Emitted when this job is finished.
* You can connect to this signal to be notified about the job's completion.
* @see start()
*/
void finished( QKeychain::Job* );
protected:
explicit Job( JobPrivate *q, QObject* parent=0 );
Q_INVOKABLE void doStart();
private:
void setError( Error error );
void setErrorString( const QString& errorString );
void scheduledStart();
protected:
JobPrivate* const d;
friend class JobExecutor;
friend class JobPrivate;
friend class ReadPasswordJobPrivate;
friend class WritePasswordJobPrivate;
friend class DeletePasswordJobPrivate;
};
class ReadPasswordJobPrivate;
/**
* @brief Job for reading secrets from the keychain.
* You can use a ReadPasswordJob to read passwords or binary data from the keychain.
* This job requires a "service" string, which is basically a namespace of keys within the keychain.
* This means that you can read all the pairs <key, secret> stored in the same service string.
*/
class QKEYCHAIN_EXPORT ReadPasswordJob : public Job {
Q_OBJECT
public:
/**
* Create a new ReadPasswordJob.
* @param service The service string used by this job (can be empty).
* @param parent The parent of this job.
*/
explicit ReadPasswordJob( const QString& service, QObject* parent=0 );
~ReadPasswordJob();
/**
* @return The binary data stored as value of this job's key().
* @see Job::key()
*/
QByteArray binaryData() const;
/**
* @return The string stored as value of this job's key().
* @see Job::key()
* @warning Returns meaningless data if the data was stored as binary data.
* @see WritePasswordJob::setTextData()
*/
QString textData() const;
private:
friend class QKeychain::ReadPasswordJobPrivate;
};
class WritePasswordJobPrivate;
/**
* @brief Job for writing secrets to the keychain.
* You can use a WritePasswordJob to store passwords or binary data in the keychain.
* This job requires a "service" string, which is basically a namespace of keys within the keychain.
* This means that you can store different pairs <key, secret> under the same service string.
*/
class QKEYCHAIN_EXPORT WritePasswordJob : public Job {
Q_OBJECT
public:
/**
* Create a new WritePasswordJob.
* @param service The service string used by this job (can be empty).
* @param parent The parent of this job.
*/
explicit WritePasswordJob( const QString& service, QObject* parent=0 );
~WritePasswordJob();
/**
* Set the @p data that the job will store in the keychain as binary data.
* @warning setBinaryData() and setTextData() are mutually exclusive.
*/
void setBinaryData( const QByteArray& data );
/**
* Set the @p data that the job will store in the keychain as string.
* Typically @p data is a password.
* @warning setBinaryData() and setTextData() are mutually exclusive.
*/
void setTextData( const QString& data );
private:
friend class QKeychain::WritePasswordJobPrivate;
};
class DeletePasswordJobPrivate;
/**
* @brief Job for deleting secrets from the keychain.
* You can use a DeletePasswordJob to delete passwords or binary data from the keychain.
* This job requires a "service" string, which is basically a namespace of keys within the keychain.
* This means that you can delete all the pairs <key, secret> stored in the same service string.
*/
class QKEYCHAIN_EXPORT DeletePasswordJob : public Job {
Q_OBJECT
public:
/**
* Create a new DeletePasswordJob.
* @param service The service string used by this job (can be empty).
* @param parent The parent of this job.
*/
explicit DeletePasswordJob( const QString& service, QObject* parent=0 );
~DeletePasswordJob();
private:
friend class QKeychain::DeletePasswordJobPrivate;
};
} // namespace QtKeychain
#endif
|