diff --git a/Mainpage.dox b/Mainpage.dox index 0b78290..ece1a87 100644 --- a/Mainpage.dox +++ b/Mainpage.dox @@ -1,40 +1,40 @@ /** @mainpage LibKGAPI \section purpose Purpose LibKGAPI is a library that implements various Google APIs so that 3rd party applications can easily integrate with Google services. \section desc Description -

Suppoerted Services

-LibKGAPI currently supports following Google APIs: +

Supported Services

+LibKGAPI currently supports the following Google APIs: Deprecated APIs:

Examples

For examples of how to use LibKGAPI in KDE applications, please refer to example programs in the examples folder. To compile examples, pass -DBUILD_EXAMPLES=TRUE to CMake. @authors Daniel Vrátil \ Jan Grulich \ @maintainers Daniel Vrátil \ @licenses @gplv2 // DOXYGEN_PROJECTNAME=LibKGAPI diff --git a/src/blogger/commentapprovejob.h b/src/blogger/commentapprovejob.h index ce10393..bc8e67f 100644 --- a/src/blogger/commentapprovejob.h +++ b/src/blogger/commentapprovejob.h @@ -1,66 +1,66 @@ /* * Copyright (C) 2014 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef KGAPI2_BLOGGER_COMMENTAPPROVEJOB_H #define KGAPI2_BLOGGER_COMMENTAPPROVEJOB_H #include "modifyjob.h" #include "kgapiblogger_export.h" namespace KGAPI2 { namespace Blogger { class KGAPIBLOGGER_EXPORT CommentApproveJob : public KGAPI2::ModifyJob { Q_OBJECT public: enum ApprovalAction { Approve, MarkAsSpam }; explicit CommentApproveJob(const QString &blogId, const QString &postId, const QString &commentId, ApprovalAction action, const AccountPtr &account, QObject *parent = nullptr); explicit CommentApproveJob(const CommentPtr &comment, ApprovalAction action, const AccountPtr &account, QObject *parent = nullptr); ~CommentApproveJob() override; protected: void start() override; ObjectsList handleReplyWithItems(const QNetworkReply *reply, const QByteArray &rawData) override; private: class Private; Private * const d; friend class Private; }; } // namespace Blogger -} // namespace KGPAI2 +} // namespace KGAPI2 #endif // KGAPI2_BLOGGER_COMMENTAPPROVEJOB_H diff --git a/src/calendar/event.h b/src/calendar/event.h index 2200298..b36131a 100644 --- a/src/calendar/event.h +++ b/src/calendar/event.h @@ -1,99 +1,99 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_EVENT_H #define LIBKGAPI2_EVENT_H #include "object.h" #include "types.h" #include "kgapicalendar_export.h" #include namespace KGAPI2 { /** * @brief Represents a single event from Google Calendar * * @author Daniel Vrátil * @since 0.1 */ class KGAPICALENDAR_EXPORT Event: public KGAPI2::Object, public KCalCore::Event { public: /** * @brief Constructor */ Event(); /** * @brief Copy constructor */ Event(const Event& other); /** * @brief Copy constructor */ explicit Event(const KCalCore::Event &event); /** * @brief Destructor */ ~Event(); bool operator==(const Event &other) const; /** * @brief Marks the event as deleted * * @param deleted */ void setDeleted(bool deleted); /** * @brief Returns whether the event was removed */ bool deleted() const; /** * @brief Sets whether the event should use calendar's default reminders. * * @param useDefault */ void setUseDefaultReminders(bool useDefault); /** * @brief Returns whether the event should use calendar's default reminders. */ bool useDefaultReminders() const; private: class Private; Private * const d; }; -} // namepsace KGAPI +} // namespace KGAPI #endif // LIBKGAPI2_EVENT_H diff --git a/src/core/account.h b/src/core/account.h index 46c709a..cf795ad 100644 --- a/src/core/account.h +++ b/src/core/account.h @@ -1,227 +1,227 @@ /* Copyright (C) 2012 - 2018 Daniel Vrátil This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) version 3, or any later version accepted by the membership of KDE e.V. (or its successor approved by the membership of KDE e.V.), which shall act as a proxy defined in Section 6 of version 3 of the license. This library 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. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see . */ #ifndef LIBKGAPI2_ACCOUNT_H #define LIBKGAPI2_ACCOUNT_H #include #include #include #include #include "kgapicore_export.h" #include "types.h" namespace KGAPI2 { /** * @headerfile Account * @brief A Google account * * This class represents a single Google account. The account is uniquely - * identified by Account::accountName (which is actually user's GMail address). + * identified by Account::accountName (which is actually the user's GMail address). * * The class stores an access token, refresh token (to retrieve a new access token * when the old one expires) and list of scopes (APIs that current access token * can be used to access). * * Unlike in previous versions, account management is not handled by LibKGAPI * anymore and it's up to programmer to store the account in a persistent storage. * * To obtain a new account, use AuthJob. * * @author Daniel Vrátil * @since 0.1 */ class KGAPICORE_EXPORT Account { public: /** * @brief Constructs an invalid account. */ Account(); /** * @brief Constructs a new valid account * * @param account Google account name (usually user.name@gmail.com) * @param accessToken Access token to \p scopes for \p account * @param refreshToken Refresh token * @param scopes List of scopes */ explicit Account(const QString &account, const QString &accessToken = QString(), const QString &refreshToken = QString(), const QList< QUrl > &scopes = QList< QUrl >()); /** * @brief Copy constructor */ Account(const Account &other); /** * @brief Destructor */ virtual ~Account(); /** * @returns Returns unique account identifier */ QString accountName() const; /** * Sets account name. * * @param accountName */ void setAccountName(const QString &accountName); /** * @return Returns access token. */ QString accessToken() const; /** * Sets a new access token. * * @param accessToken */ void setAccessToken(const QString &accessToken); /** * @return Returns refresh token. */ QString refreshToken() const; /** * Sets a new refresh token for the access token. * * @param refreshToken */ void setRefreshToken(const QString &refreshToken); /** * @return Returns list of scopes the account is authenticated against. */ QList< QUrl > scopes() const; /** * \brief Sets new scopes. * * @note Note that changing scopes requires makes current tokens invalid. * This means that when this Account is used next time, AuthJob will be * automatically started and user will be prompted with a dialog to grant * access to all scopes. * * @param scopes */ void setScopes(const QList< QUrl > &scopes); /** * Adds a single scope to account scopes. * * @param scope * @see Account::setScopes(const QList) */ void addScope(const QUrl &scope); /** * Removes scope from the list. * * @param scope * @see Account::setScopes(const QList) */ void removeScope(const QUrl &scope); /** * @since 2.0.82 * Returns expire date time token */ QDateTime expireDateTime() const; /** * @since 2.0.82 * set expire date time */ void setExpireDateTime(const QDateTime &expire); /** * Returns scope URL for AccountInfo service. */ static QUrl accountInfoScopeUrl(); /** * Returns scope URL to retrieve AccountInfo with email. */ static QUrl accountInfoEmailScopeUrl(); /** * Returns scope URL for Google Calendar service. */ static QUrl calendarScopeUrl(); /** * Returns scope URL for Google Tasks service. */ static QUrl tasksScopeUrl(); /** * Returns scope URL for Google Contacts service. */ static QUrl contactsScopeUrl(); /** * Returns scope URL for Google Latitude service. */ static QUrl latitudeScopeUrl(); /** * Returns scope URL for Google Blogger service. */ static QUrl bloggerScopeUrl(); private: class Private; Private * const d; /** * @internal * Whether scopes were changed or not. * * AuthJob reads this attribute when Account is passed to it to * determine whether completely new process of authentication is needed, * or whether just refreshing tokens is enough. * * When m_scopesChanged is \p true and AuthJob successffulyperforms full * re-authentication it sets this attribute to \p false and next time it * will just refresh existing tokens until the scopes are changed again. */ bool m_scopesChanged; //krazy:exclude=dpointer friend class AuthJob; }; } // namespace KGAPI2 Q_DECLARE_METATYPE(KGAPI2::AccountPtr) #endif // LIBKGAPI2_ACCOUNT_H diff --git a/src/core/createjob.h b/src/core/createjob.h index f2387cc..9cf6d4e 100644 --- a/src/core/createjob.h +++ b/src/core/createjob.h @@ -1,129 +1,129 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_CREATEJOB_H #define LIBKGAPI2_CREATEJOB_H #include "job.h" #include "kgapicore_export.h" namespace KGAPI2 { /** * @headerfile CreateJob - * @brief Abstract superclass for all jobs that create a new objects on the + * @brief Abstract superclass for all jobs that create new objects on the * server. * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT CreateJob: public KGAPI2::Job { Q_OBJECT public: /** * @brief Constructor for jobs that don't require authentication * * @param parent */ explicit CreateJob(QObject* parent = nullptr); /** * @brief Constructor for jobs that require authentication * - * @param account Account to use to authenticate the requests send by this job + * @param account Account to use to authenticate the requests sent by this job * @param parent */ explicit CreateJob(const KGAPI2::AccountPtr &account, QObject* parent = nullptr); /** * @brief Destructor */ ~CreateJob() override; /** * @return Returns newly created items */ virtual ObjectsList items() const; protected: /** * @brief KGAPI::Job::dispatchRequest() * * @param accessManager * @param request * @param data * @param contentType */ void dispatchRequest(QNetworkAccessManager* accessManager, const QNetworkRequest& request, const QByteArray& data, const QString& contentType) override; /** * @brief KGAPI2::Job::handleReply implementation * * \param rawData * \param contentType */ void handleReply(const QNetworkReply *reply, const QByteArray& rawData) override; /** * @brief KGAPI2::Job::aboutToStart() implementation */ void aboutToStart() override; /** * @brief A reply handler that returns items parsed from \@ rawData * - * This method can be reimplemented in a FetchJob subclasses. It is called + * This method can be reimplemented in FetchJob subclasses. It is called * automatically when a reply is received and the returned items are stored * in FetchJob and accessible via FetchJob::items when the job has finished. * * If you need more control over handling reply and items, you can reimplement * FetchJob::handleReply. Note that reimplementing FetchJob::handleReply * usually requires reimplementing FetchJob::items as well and storing the * parsed items in your implementation. * - * @param reply A QNetworkReply received from Google server + * @param reply A QNetworkReply received from Google's server * @param rawData Content of body of the @p reply. Don't use * QNetworkReply::readAll(), because the content has already been read * by Job implementation and thus it would return empty data. * * @return Items parsed from @p rawData */ virtual ObjectsList handleReplyWithItems(const QNetworkReply *reply, const QByteArray &rawData); private: class Private; Private * const d; friend class Private; }; } // namespace KGAPI2 #endif // LIBKGAPI2_CREATEJOB_H diff --git a/src/core/deletejob.h b/src/core/deletejob.h index 63b4ec5..91889b0 100644 --- a/src/core/deletejob.h +++ b/src/core/deletejob.h @@ -1,103 +1,103 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_DELETEJOB_H #define LIBKGAPI2_DELETEJOB_H #include "job.h" #include "kgapicore_export.h" namespace KGAPI2 { /** * @headerfile DeleteJob * @brief Abstract superclass for all jobs that delete resources from Google * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT DeleteJob : public KGAPI2::Job { Q_OBJECT public: /** * Constructor for jobs that don't require authentication * * @param parent */ explicit DeleteJob(QObject* parent = nullptr); /** * @brief Constructor for jobs that require authentication * - * @param account Account to use to authenticate the requests send by this job + * @param account Account to use to authenticate the requests sent by this job * @param parent */ explicit DeleteJob(const KGAPI2::AccountPtr &account, QObject* parent = nullptr); /** * @brief Destructor */ ~DeleteJob() override; protected: /** * @brief KGAPI::Job::dispatchRequest immplementation * * @param accessManager * @param request * @param data * @param contentType */ void dispatchRequest(QNetworkAccessManager* accessManager, const QNetworkRequest& request, const QByteArray& data, const QString& contentType) override; /** * KGAPI2::Job::handleReply implementation * * Ths implementation will automatically call start() again in order to * process another item in queue. Programmer should call emitFinished() * from start() if there are no further items to delete. * * If you need more control over deleting or handling the reply, you can * reimplement this method in your subclass. * * @param rawData * @param contentType */ void handleReply(const QNetworkReply *reply, const QByteArray& rawData) override; private: class Private; Private const * d; friend class Private; }; } // namespace KGAPI2 #endif // LIBKGAPI2_DELETEJOB_H diff --git a/src/core/fetchjob.h b/src/core/fetchjob.h index ae0bc40..9183c7c 100644 --- a/src/core/fetchjob.h +++ b/src/core/fetchjob.h @@ -1,131 +1,131 @@ /* - * This file is part of LiKGAPI library + * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_FETCHJOB_H #define LIBKGAPI2_FETCHJOB_H #include "job.h" #include "kgapicore_export.h" namespace KGAPI2 { /** * @headerfile FetchJob * @brief Abstract superclass for all jobs that fetch resources from Google * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT FetchJob : public KGAPI2::Job { Q_OBJECT public: /** * @brief Constructor for jobs that don't require authentication * * @param parent */ explicit FetchJob(QObject* parent = nullptr); /** * @brief Constructor for jobs that require authentication * - * @param account Account to use to authenticate the requests send by this job + * @param account Account to use to authenticate the requests sent by this job * @param parent */ explicit FetchJob(const KGAPI2::AccountPtr &account, QObject* parent = nullptr); /** * @brief Destructor */ ~FetchJob() override; /** * @brief Returns all items fetched by this job. * * Returns all items fetch by this job. This method can be called only * from handler of Job::finished signal. Calling this method on a running * job will print a warning and return an empty list. * * @return All items fetched by this job. */ virtual ObjectsList items() const; protected: /** * @brief KGAPI::Job::dispatchRequest implementation * * @param accessManager * @param request * @param data * @param contentType */ void dispatchRequest(QNetworkAccessManager* accessManager, const QNetworkRequest& request, const QByteArray& data, const QString& contentType) override; /** * @brief KGAPI::Job::handleReply implementation * * @param rawData * @param contentType */ void handleReply(const QNetworkReply *reply, const QByteArray& rawData) override; /** * @brief KGAPI::Job::aboutToStart implementation */ void aboutToStart() override; /** * @brief A reply handler that returns items parsed from \@ rawData * * This method can be reimplemented in a FetchJob subclasses. It is called * automatically when a reply is received and the returned items are stored * in FetchJob and accessible via FetchJob::items when the job has finished. * * If you need more control over handling reply and items, you can reimplement * FetchJob::handleReply. Note that reimplementing FetchJob::handleReply * usually requires reimplementing FetchJob::items as well and storing the * parsed items in your implementation. * * @param reply A QNetworkReply received from Google server * @param rawData Content of body of the @p reply. Don't use * QNetworkReply::readAll(), because the content has already been read * by Job implementation and thus it would return empty data. * * @return Items parsed from @p rawData */ virtual ObjectsList handleReplyWithItems(const QNetworkReply *reply, const QByteArray &rawData); private: class Private; Private * const d; friend class Private; }; } // namespace KGAPI2 #endif // LIBKGAPI2_FETCHJOB_H diff --git a/src/core/job.h b/src/core/job.h index 5a29e7b..0a68689 100644 --- a/src/core/job.h +++ b/src/core/job.h @@ -1,334 +1,334 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_JOB_H #define LIBKGAPI2_JOB_H #include "types.h" #include "kgapicore_export.h" #include class QNetworkAccessManager; class QNetworkReply; class QNetworkRequest; namespace KGAPI2 { /** * @headerfile Job * @brief Abstract base class for all jobs in LibKGAPI * * Usual workflow of Job subclasses is to reimplement Job::start, * Job::dispatchRequest and Job::handleReply, then enqueue a QNetworkRequest using * Job::enqueueRequest. The request will automatically be scheduled in a queue * and dispatched by calling Job::dispatchRequest implementation. When a reply * is received, the Job will automatically perform error handling and if there * is no error, the reply is passed to implementation of Job::handleReply. * * Job is automatically when program enters an event loop. * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT Job : public QObject { Q_OBJECT /** * @brief Maximum interval between requests. * * Some Google APIs have a quota on maximum amount of requests per account * per second. When this quota is exceeded, the Job will automatically increase * the interval between dispatching requests, wait for a while and then try - * again. If however the interval is incresed over @p maxTimeout, the job - * will fail and finish immediatelly. By default @p maxTimeout is @p -1, which + * again. If however the interval is increased over @p maxTimeout, the job + * will fail and finish immediately. By default @p maxTimeout is @p -1, which * allows the interval to be increased indefinitely. * * @see Job::maxTimeout, Job::setMaxTimeout */ Q_PROPERTY(int maxTimeout READ maxTimeout WRITE setMaxTimeout) /** * @brief Whether the job is running * * This property indicates whether the job is running or not. The value is * set to @p true when the job is started (see Job::start) and back to * @p false right before Job::finished is emitted. * * @see Job::isRunning, Job::finished */ Q_PROPERTY(bool isRunning READ isRunning NOTIFY finished) public: /** * @brief Constructor for jobs that don't require authentication * * @param parent */ explicit Job(QObject* parent = nullptr); /** * @brief Constructor for jobs that require authentication * * @param account Account to use to authenticate the requests send by this job * @param parent * @see Job::Account, Job::setAccount */ explicit Job(const AccountPtr &account, QObject* parent = nullptr); /** * @brief Destructor */ ~Job() override; /** * @brief Error code * * This method can only be called after the job has emitted Job::finished * signal. Calling this method on a running job will always return * KGAPI2::NoError. * * @return Returns code of ocurred error or KGAPI2::NoError when no error * has ocurred. */ KGAPI2::Error error() const; /** * @brief Error string * * This method can only be called after the job has emitted Job::finished * signal. Calling this method on a running job will alaways return an empty * string. * * @return Returns localized description of error or an empty string if no * error has ocurred. */ QString errorString() const; /** * @brief Set maximum quota timeout * * Sets maximum interval for which the job should wait before trying to submit * a request that has previously failed due to exceeded quota. * * Default timeout is 1 seconds, then after every failed request the timeout - * is increesed exponentially until reaching @p maxTimeout. + * is increased exponentially until reaching @p maxTimeout. * * @param maxTimeout Maximum timeout (in seconds), or @p -1 for no timeout */ void setMaxTimeout(int maxTimeout); /** * @brief Maximum quota limit. * * @return Returns maximum timeout in seconds or -1 if there is no timeout set. * @see Job::setMaxTimeout */ int maxTimeout() const; /** * @brief Whether job is running * * A job is considered running from the moment it's started until * until Job::finished is emitted. Some methods should not be * called when a job is running. * * @return Returns whether this job is currently running. * @sa start() */ bool isRunning() const; /** * @brief Set account to be used to authenticate requests * * By default, no account is set and all request are sent without any * authentication. * * @param account Account to use */ void setAccount(const AccountPtr &account); /** * @brief Returns account used to authenticate requests * * For jobs that don't require authentication, this method returns a null * pointer. * * @return Am Account or a null pointer when no account was set. */ AccountPtr account() const; /** * @brief Restarts this job * * When a job finishes, it's possible to run it again, without having * to create a new job. * * The job will throw away all results retrieved in previous run and retrieve * everything again. * * @see Job::aboutToStart */ void restart(); Q_SIGNALS: /** * @brief Emitted when @p job has finished * * The signal is emitted every time, no matter whether the job is successful * or an error has ocurred. * - * Sublcasses should never ever emit this signal directly. + * Subclasses should never ever emit this signal directly. * Use Job::emitFinished instead. * * @param job The job that has finished * @sa emitFinished() */ void finished(KGAPI2::Job *job); /** * @brief Emitted when a job progress changes. * * Note that some jobs might not provide progress information, thus this * signal will never be emitted. * * @param job The job that the information relates to * @param processed Amount of already processed items * @param total Total amount of items to process */ void progress(KGAPI2::Job *job, int processed, int total); protected: /** * @brief Set job error to @p error * * @param error Error code to set * @see Job::error */ void setError(KGAPI2::Error error); /** * @brief Set job error description to @p errorString * * @param errorString Error description to set * @see Job::errorString */ void setErrorString(const QString &errorString); /** * @brief Emits Job::finished() signal * * Subclasses should always use this method instead of directly emitting * Job::finished(). */ virtual void emitFinished(); /** * @brief This method is invoked right before finished() is emitted * - * Sublcasses can reimplement this method to do final clean up before + * Subclasses can reimplement this method to do a final cleanup before * the Job::finished() signal is emitted. * * @note Note that after Job::finished() the job is not running anymore and * therefore the job should not modify any data accessible by user. */ virtual void aboutToFinish(); /** * @brief Emit progress() signal * * Subclasses should always use this method instead of directly emitting * Job::progress(). * * @param processed Amount of already processed items * @param total Total amount of itms to process */ virtual void emitProgress(int processed, int total); /** * @brief This method is invoked right before Job::start() is called. * - * Sublcasses should reset their internal state and call parent implementation. + * Subclasses should reset their internal state and call parent implementation. */ virtual void aboutToStart(); /** * @brief This method is invoked when job is started. * * Job is automatically started when application enters event loop. */ virtual void start() = 0; /** * @brief Dispatches @p request via @p accessManager * * Because different types of request require different HTTP method to be * used, subclasses must reimplement this method and use respective HTTP * method to send the @p request via @p accessManager. * * @param accessManager QNetworkAccessManager used to dispatch the request * @param request Request to dispatch - * @param data Data to send in body of the request + * @param data Data to sent in the body of the request * @param contentType Content-Type of @p data */ virtual void dispatchRequest(QNetworkAccessManager *accessManager, const QNetworkRequest &request, const QByteArray &data, const QString &contentType) = 0; /** * @brief Called when a reply is received. * * Sublcasses must reimplement this method to handle reply content. * * @param reply A reply received from server * @param rawData Raw content of the reply. Don't use QNetworkReply::readAll, * because this method has already been called by Job and thus it would * return nothing. */ virtual void handleReply(const QNetworkReply *reply, const QByteArray &rawData) = 0; /** * @brief Enqueues @p request in dispatcher queue * * Subclasses should call this method to enqueue the @p request in main job * queue. The request is automatically dispatched, and reply is handled. * * @param request Request to enqueue * @param data Data to be send in body of the request * @param contentType Content type of @p data */ virtual void enqueueRequest(const QNetworkRequest &request, const QByteArray &data = QByteArray(), const QString &contentType = QString()); private: class Private; Private * const d; friend class Private; friend class AuthJob; }; } // namespace KGAPI2 #endif // LIBKGAPI2_JOB_H diff --git a/src/core/modifyjob.cpp b/src/core/modifyjob.cpp index 9e776d0..65315a0 100644 --- a/src/core/modifyjob.cpp +++ b/src/core/modifyjob.cpp @@ -1,110 +1,110 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #include "modifyjob.h" #include "../debug.h" #include "object.h" #include #include #include using namespace KGAPI2; class Q_DECL_HIDDEN ModifyJob::Private { public: ObjectsList items; QBuffer buffer; }; ModifyJob::ModifyJob(QObject* parent): Job(parent), d(new Private) { } ModifyJob::ModifyJob(const AccountPtr& account, QObject* parent): Job(account, parent), d(new Private) { } ModifyJob::~ModifyJob() { delete d; } ObjectsList ModifyJob::items() const { return d->items; } void ModifyJob::dispatchRequest(QNetworkAccessManager* accessManager, const QNetworkRequest& request, const QByteArray& data, const QString& contentType) { QNetworkRequest r = request; if (!r.hasRawHeader("Content-Type")) { r.setHeader(QNetworkRequest::ContentTypeHeader, contentType); } if (!r.hasRawHeader("If-Match")) { r.setRawHeader("If-Match", "*"); } - // Note: there is a problem with PUT when using KIO::AccessManager - it does - // not transfer the body correctly. + // Note: there is a problem with PUT when using KIO::AccessManager - it + // doesn't transfer the body correctly. // Using sendCustomRequest() works just fine. //accessManager->put(r, data); if (data.size() > 0) { r.setHeader(QNetworkRequest::ContentLengthHeader, data.size()); d->buffer.close(); d->buffer.setData(data); d->buffer.open(QIODevice::ReadOnly); accessManager->sendCustomRequest(r, "PUT", &d->buffer); } else { accessManager->sendCustomRequest(r, "PUT"); } } void ModifyJob::handleReply( const QNetworkReply *reply, const QByteArray &rawData ) { d->buffer.close(); d->items << handleReplyWithItems(reply, rawData); } void ModifyJob::aboutToStart() { d->items.clear(); Job::aboutToStart(); } ObjectsList ModifyJob::handleReplyWithItems(const QNetworkReply* reply, const QByteArray& rawData) { Q_UNUSED(reply) Q_UNUSED(rawData) return ObjectsList(); } diff --git a/src/core/modifyjob.h b/src/core/modifyjob.h index bdda439..53bf6c7 100644 --- a/src/core/modifyjob.h +++ b/src/core/modifyjob.h @@ -1,126 +1,126 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_MODIFYJOB_H #define LIBKGAPI2_MODIFYJOB_H #include "job.h" #include "kgapicore_export.h" namespace KGAPI2 { /** * @headerfile FetchJob * @brief Abstract superclass for all jobs that somehow modify resources on Google * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT ModifyJob : public KGAPI2::Job { Q_OBJECT public: /** * @brief Constructor for jobs that don't require authentication * * @param parent */ explicit ModifyJob(QObject* parent = nullptr); /** * @brief Constructor for jobs that require authentication * - * @param account Account to use to authenticate the requests send by this job + * @param account Account to use to authenticate the requests sent by this job * @param parent */ explicit ModifyJob(const KGAPI2::AccountPtr& account, QObject* parent = nullptr); /** * Destructor */ ~ModifyJob() override; /** * @return Returns modified items. */ ObjectsList items() const; protected: /** * @brief A reply handler that returns items parsed from \@ rawData * * This method can be reimplemented in a FetchJob subclasses. It is called * automatically when a reply is received and the returned items are stored * in FetchJob and accessible via FetchJob::items when the job has finished. * * If you need more control over handling reply and items, you can reimplement * FetchJob::handleReply. Note that reimplementing FetchJob::handleReply * usually requires reimplementing FetchJob::items as well and storing the * parsed items in your implementation. * - * @param reply A QNetworkReply received from Google server + * @param reply A QNetworkReply received from Google's servers * @param rawData Content of body of the @p reply. Don't use * QNetworkReply::readAll(), because the content has already been read * by Job implementation and thus it would return empty data. * * @return Items parsed from @p rawData */ virtual ObjectsList handleReplyWithItems(const QNetworkReply *reply, const QByteArray& rawData); /** * KGAPI2::Job::dispatchRequest implementation * * @param accessManager * @param request * @param data * @param contentType */ void dispatchRequest(QNetworkAccessManager* accessManager, const QNetworkRequest& request, const QByteArray& data, const QString& contentType) override; /** * KGAPI2::Job::handleReply implementation * * @param reply * @param rawData */ void handleReply(const QNetworkReply *reply, const QByteArray& rawData) override; /** * KGAPI2::Job::aboutToStart() implementation */ void aboutToStart() override; private: class Private; Private * const d; friend class Private; }; } // namespace KGAPI2 #endif // LIBKGAPI2_MODIFYJOB_H diff --git a/src/core/object.h b/src/core/object.h index b2e584c..4ac3d22 100644 --- a/src/core/object.h +++ b/src/core/object.h @@ -1,91 +1,91 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_OBJECT_H #define LIBKGAPI2_OBJECT_H #include #include #include "types.h" #include "kgapicore_export.h" namespace KGAPI2 { /** * @brief Base class for all objects * * There are many container classes to represent data fetched from Google servers, * like KGAPI2::Contact, KGAPI2::Event, etc. All these container classes must - * be subclasses of KGAPI2::Object. + * be subclasses of the KGAPI2::Object. * * @author Daniel Vrátil * @since 2.0 */ class KGAPICORE_EXPORT Object { public: /** * @brief Constructor */ Object(); /** * @brief Copy constructor */ Object(const Object &other); /** * @brief Destructor */ virtual ~Object(); bool operator==(const Object &other) const; /** - * @brief Sets etag of this object. + * @brief Set the etag of this object. * - * Etag represents a revision of an object When object is changed on the - * remote side is given a new etag. + * Etag represents a revision of an object. When the object is changed on the + * remote side it is given a new etag. * * @param etag */ void setEtag(const QString &etag); /** * @brief Returns etag of this object. * * @return Etag string */ QString etag() const; private: class Private; Private * const d; friend class Private; }; } // namespace KGAPI2 #endif // LIBKGAPI2_OBJECT_H diff --git a/src/core/types.h b/src/core/types.h index 299fb83..a05694c 100644 --- a/src/core/types.h +++ b/src/core/types.h @@ -1,219 +1,219 @@ /* * This file is part of LibKGAPI library * * Copyright (C) 2013 Daniel Vrátil * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) version 3, or any * later version accepted by the membership of KDE e.V. (or its * successor approved by the membership of KDE e.V.), which shall * act as a proxy defined in Section 6 of version 3 of the license. * * This library 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. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library. If not, see . */ #ifndef LIBKGAPI2_TYPES_H #define LIBKGAPI2_TYPES_H #include "kgapicore_export.h" #include #include #include namespace KGAPI2 { /** * @brief Structure to store additional information about a feed. */ class KGAPICORE_EXPORT FeedData { public: explicit FeedData(): startIndex(0), itemsPerPage(0), totalResults(0) { } int startIndex; /**< Index of first item on current feed page. */ int itemsPerPage; /**< Number of items per feed page. This will be same for all pages (except for the last one which can be shorter). */ int totalResults; /**< Number of all items. */ QUrl nextPageUrl; /**< Link to next page of feed.*/ QUrl requestUrl; /**< Original URL of the request. This value is filled by AccessManager when passing the structure to a service */ }; class Object; typedef QSharedPointer ObjectPtr; typedef QList ObjectsList; class Account; typedef QSharedPointer AccountPtr; typedef QList AccountsList; class AccountInfo; typedef QSharedPointer AccountInfoPtr; typedef QList AccountInfosList; class Contact; typedef QSharedPointer ContactPtr; typedef QList ContactsList; class ContactsGroup; typedef QSharedPointer ContactsGroupPtr; typedef QList ContactsGroupsList; class Calendar; typedef QSharedPointer CalendarPtr; typedef QList CalendarsList; namespace Drive { class About; typedef QSharedPointer AboutPtr; typedef QList AboutsList; class App; typedef QSharedPointer AppPtr; typedef QList AppsList; class Change; typedef QSharedPointer ChangePtr; typedef QList ChangesList; class ChildReference; typedef QSharedPointer ChildReferencePtr; typedef QList ChildReferencesList; class File; typedef QSharedPointer FilePtr; typedef QList FilesList; class ParentReference; typedef QSharedPointer ParentReferencePtr; typedef QList ParentReferencesList; class Permission; typedef QSharedPointer PermissionPtr; typedef QList PermissionsList; class Revision; typedef QSharedPointer RevisionPtr; typedef QList RevisionsList; class User; typedef QSharedPointer UserPtr; typedef QList UsersList; } class Event; typedef QSharedPointer EventPtr; typedef QList EventsList; class Location; typedef QSharedPointer LocationPtr; typedef QList LocationsList; class Reminder; typedef QSharedPointer ReminderPtr; typedef QList RemindersList; class Task; typedef QSharedPointer TaskPtr; typedef QList TasksList; class TaskList; typedef QSharedPointer TaskListPtr; typedef QList TaskListsList; namespace Blogger { class Blog; typedef QSharedPointer BlogPtr; typedef QList BlogsList; class Comment; typedef QSharedPointer CommentPtr; typedef QList CommentsList; class Page; typedef QSharedPointer PagePtr; typedef QList PagesList; class Post; typedef QSharedPointer PostPtr; typedef QList PostsList; } template ObjectsList operator<<(ObjectsList &objectsList, const QList< QSharedPointer > &list) { for (const QSharedPointer &item : list) { objectsList << item; } return objectsList; } /** * @brief Job error codes */ enum Error { /* Internal LibKGAPI errors */ NoError = 0, ///< LibKGAPI error - no error. UnknownError = 1, ///< LibKGAPI error - a general unidentified error. AuthError = 2, ///< LibKGAPI error - authentication process failed. UnknownAccount = 3, ///< LibKGAPI error - application requested unknown account. UnknownService = 4, ///< LibKGAPI error - application requested unknown service. InvalidResponse = 5, ///< LibKGAPI error - Google returned invalid response. BackendNotReady = 6, ///< @deprecated LibKGAPI error - backend is not ready (for example KWallet is not opened). InvalidAccount = 7, ///< LibKGAPI error - the KGAPI2::Account object is invalid. - NetworkError = 8, ///< LibKGAPI error - standard network request returned other code then 200. - AuthCancelled = 9, ///< LibKGAPI error - when authentication dialog is canceled + NetworkError = 8, ///< LibKGAPI error - standard network request returned a different code than 200. + AuthCancelled = 9, ///< LibKGAPI error - when the authentication dialog is canceled. /* Following error codes identify Google errors */ OK = 200, ///< Request successfully executed. Created = 201, ///< Create request successfully executed. NoContent = 204, ///< Tasks API returns 204 when task is successfully removed. TemporarilyMoved = 302, ///< The object is located on a different URL provided in reply. NotModified = 304, ///< Request was successful, but no data were updated. BadRequest = 400, ///< Invalid (malformed) request. Unauthorized = 401, ///< Invalid or expired token. See KGAPI2::Account::refreshTokens(). - Forbidden = 403, ///< The requested data are not accessible to this account - NotFound = 404, ///< Requested object was not found on the remote side + Forbidden = 403, ///< The requested data is not accessible to this account. + NotFound = 404, ///< Requested object was not found on the remote side. Conflict = 409, ///< Object on the remote site differs from the submitted one. @see KGAPI2::Object::setEtag. - Gone = 410, ///< The requested does not exist anymore on the remote site - InternalError = 500, ///< An unexpected error on the Google service occurred - QuotaExceeded = 503 ///< User quota has been exceeded, the request should be send again later. + Gone = 410, ///< The requested data does not exist anymore on the remote site. + InternalError = 500, ///< An unexpected error occurred on the Google service. + QuotaExceeded = 503 ///< User quota has been exceeded, the request should be sent again later. }; /** * @since 2.0 */ enum ContentType { UnknownContentType = -1, JSON, XML }; } // namespace KGAPI2 #endif // LIBKGAPI2_TYPES_H