diff --git a/akonadi/preprocessorbase.cpp b/akonadi/preprocessorbase.cpp index 5264fe499..7403b181a 100644 --- a/akonadi/preprocessorbase.cpp +++ b/akonadi/preprocessorbase.cpp @@ -1,111 +1,109 @@ /****************************************************************************** * * File : preprocessorbase.cpp * Creation date : Sun 19 Jul 2009 22:39:13 * * Copyright (c) 2009 Szymon Stefanek * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published by * the Free Software Foundation; either version 2 of the License, or (at your * option) any later version. * * 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 Library General Public * License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; see the file COPYING.LIB. If not, write to the * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, * MA, 02110-1301, USA. * *****************************************************************************/ #include "preprocessorbase.h" #include "agentbase_p.h" - #include "preprocessoradaptor.h" -#include +#include namespace Akonadi { - class PreprocessorBasePrivate : public AgentBasePrivate { -public: - bool mInDelayedProcessing; - qlonglong mDelayedProcessingItemId; - -public: - PreprocessorBasePrivate( PreprocessorBase *parent ) - : AgentBasePrivate( parent ), - mInDelayedProcessing( false ), - mDelayedProcessingItemId( 0 ) - { - } - - Q_DECLARE_PUBLIC( PreprocessorBase ) + public: + PreprocessorBasePrivate( PreprocessorBase *parent ) + : AgentBasePrivate( parent ), + mInDelayedProcessing( false ), + mDelayedProcessingItemId( 0 ) + { + } + + Q_DECLARE_PUBLIC( PreprocessorBase ) + + void delayedInit() + { + if ( !QDBusConnection::sessionBus().registerService( QLatin1String( "org.freedesktop.Akonadi.Preprocessor." ) + mId ) ) + kFatal() << "Unable to register service at D-Bus: " << QDBusConnection::sessionBus().lastError().message(); + AgentBasePrivate::delayedInit(); + } + + bool mInDelayedProcessing; + qlonglong mDelayedProcessingItemId; +}; - void delayedInit() - { - if ( !QDBusConnection::sessionBus().registerService( QLatin1String( "org.freedesktop.Akonadi.Preprocessor." ) + mId ) ) - kFatal() << "Unable to register service at D-Bus: " << QDBusConnection::sessionBus().lastError().message(); - AgentBasePrivate::delayedInit(); - } - -}; // class PreprocessorBasePrivate +} +using namespace Akonadi; PreprocessorBase::PreprocessorBase( const QString &id ) : AgentBase( new PreprocessorBasePrivate( this ), id ) { new PreprocessorAdaptor( this ); } PreprocessorBase::~PreprocessorBase() { - } void PreprocessorBase::processingTerminated( ProcessingResult result ) { Q_D( PreprocessorBase ); Q_ASSERT_X( result != ProcessingDelayed, "PreprocessorBase::processingTerminated", "You should never pass ProcessingDelayed to this function" ); Q_ASSERT_X( d->mInDelayedProcessing, "PreprocessorBase::processingTerminated", "processingTerminated() called while not in delayed processing mode" ); d->mInDelayedProcessing = false; emit itemProcessed( d->mDelayedProcessingItemId ); } void PreprocessorBase::beginProcessItem( qlonglong id ) { Q_D( PreprocessorBase ); - qDebug() << "PreprocessorBase: about to process item " << id; + kDebug() << "PreprocessorBase: about to process item " << id; switch( processItem( Item( id ) ) ) { case ProcessingFailed: case ProcessingRefused: case ProcessingCompleted: - qDebug() << "PreprocessorBase: item processed, emitting signal (" << id << ")"; + kDebug() << "PreprocessorBase: item processed, emitting signal (" << id << ")"; emit itemProcessed( id ); - qDebug() << "PreprocessorBase: item processed, signal emitted (" << id << ")"; + kDebug() << "PreprocessorBase: item processed, signal emitted (" << id << ")"; break; case ProcessingDelayed: - qDebug() << "PreprocessorBase: item processing delayed (" << id << ")"; + kDebug() << "PreprocessorBase: item processing delayed (" << id << ")"; d->mInDelayedProcessing = true; d->mDelayedProcessingItemId = id; break; } } -} // namespace Akonadi +#include "preprocessorbase.moc" diff --git a/akonadi/preprocessorbase.h b/akonadi/preprocessorbase.h index dd2be6eb7..c6e225662 100644 --- a/akonadi/preprocessorbase.h +++ b/akonadi/preprocessorbase.h @@ -1,177 +1,173 @@ /****************************************************************************** * * File : preprocessorbase.h * Creation date : Sun 19 Jul 2009 22:39:13 * * Copyright (c) 2009 Szymon Stefanek * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published by * the Free Software Foundation; either version 2 of the License, or (at your * option) any later version. * * 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 Library General Public * License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; see the file COPYING.LIB. If not, write to the * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, * MA, 02110-1301, USA. * *****************************************************************************/ #ifndef _PREPROCESSORBASE_H_ #define _PREPROCESSORBASE_H_ #include "akonadi_export.h" #include #include #include class PreprocessorAdaptor; namespace Akonadi { class PreprocessorBasePrivate; /** - * @short The base class for all Akonadi preprocessors. + * @short The base class for all Akonadi preprocessors agents. * * This class should be used as a base class by all preprocessor agents * since it encapsulates large parts of the protocol between * preprocessor agent, agent manager and the Akonadi storage. * + * Preprocessor agents are special agents that are informed about newly + * added items before any other agents. This allows them to do filtering + * on the items or any other task that shall be done before the new item + * is visible in the Akonadi storage system. + * * The method all the preprocessors must implement is processItem(). + * + * @author Szymon Stefanek + * @since 4.4 */ class AKONADI_EXPORT PreprocessorBase : public AgentBase { friend class PreprocessorAdaptor; Q_OBJECT -public: - - /** - * Creates an instance of a PreprocessorBase. - * You don't need to call this explicitly if you - * use the AKONADI_PREPROCESSOR_MAIN macro below. - */ - PreprocessorBase( const QString &id ); + public: + /** + * Describes the possible return values of the processItem() method. + */ + enum ProcessingResult + { + /** + * Processing completed succesfully for this item. + * The Akonadi server will push in a new item when it's available. + */ + ProcessingCompleted, + + /** + * Processing was delayed to a later stage. + * This must be returned when implementing asynchronous preprocessing. + * + * If this value is returned, processingTerminated() has to be called + * when processing is done. + */ + ProcessingDelayed, + + /** + * Processing for this item failed (and the failure is unrecoverable). + * The Akonadi server will push in a new item when it's available, + * after possibly logging the failure. + */ + ProcessingFailed, + + /** + * Processing for this item was refused. This is very + * similar to ProcessingFailed above but additionally remarks + * that the item that the Akonadi server pushed in wasn't + * meant for this Preprocessor. + * The Akonadi server will push in a new item when it's available, + * after possibly logging the failure and maybe taking some additional action. + */ + ProcessingRefused + }; - /** - * Destroys the PreprocessorBase instance. - */ - virtual ~PreprocessorBase(); + /** + * This method has to be implement by every preprocessor subclass. + * + * Returns ProcessingCompleted on success, ProcessingDelayed + * if processing is implemented asynchronously and + * ProcessingRefused or ProcessingFailed if the processing + * didn't complete. + */ + virtual ProcessingResult processItem( const Item &item ) = 0; -public: + /** + * This method must be called if processing is implemented asynchronously. + * + * Valid values for @p result are ProcessingCompleted, + * PocessingRefused and ProcessingFailed. Passing any + * other value will lead to a runtime assertion. + */ + void processingTerminated( ProcessingResult result ); - /** - * The possible results of your processItem() function. - */ - enum ProcessingResult - { + Q_SIGNALS: /** - * Processing completed succesfully for this item. - * The Akonadi server will push in a new item when it's available. + * This signal is emitted to report item processing termination + * to the Akonadi server. + * + * @note This signal is only for internal use. */ - ProcessingCompleted, + void itemProcessed( qlonglong id ); + protected: /** - * Processing was delayed to a later stage. - * This is what you want to return when implementing - * asynchronous preprocessing. + * Creates a new preprocessor base agent. * - * If you return this value then you're responsible of calling - * processingTerminated() when you're done. + * @param id The instance id of the preprocessor base agent. */ - ProcessingDelayed, + PreprocessorBase( const QString &id ); /** - * Processing for this item failed (and the failure is unrecoverable). - * The Akonadi server will push in a new item when it's available, - * after possibly logging the failure. + * Destroys the preprocessor base agent. */ - ProcessingFailed, + virtual ~PreprocessorBase(); /** - * Processing for this item was refused. This is very - * similar to ProcessingFailed above but additionally remarks - * that the item that the Akonadi server pushed in wasn't - * meant for this Preprocessor. - * The Akonadi server will push in a new item when it's available, - * after possibly logging the failure and maybe taking some additional action. + * This dbus method is called by the Akonadi server + * in order to trigger the processing of an item. + * + * @note Do not call it manually! */ - ProcessingRefused - - }; - - /** - * This is the pure virtual you need to implement - * in your preprocessor. - * - * Return ProcessingCompleted on success, ProcessingDelayed - * if you're implementing asynchronous preprocessing and - * ProcessingRefused or ProcessingFailed if the processing - * didn't complete. - * - * If you return ProcessingDelayed then you also MUST - * call processingTerminated() when you're asynchronous - * elaboration completes. - */ - virtual ProcessingResult processItem( const Item &item ) = 0; - - /** - * You need to call this function if you are implementing an asynchronous - * preprocessor. In processItem() you trigger your async work - * and return ProcessingDelayed. The framework will then assume - * that you're busy until you call this function. - * - * Possible values for result are ProcessingCompleted, - * PocessingRefused and ProcessingFailed. Passing ProcessingDelayed - * is a programming error and will be punished by a Q_ASSERT(). - */ - void processingTerminated( ProcessingResult result ); - -private: - - // dbus Preprocessor interface: don't look :) - friend class ::PreprocessorAdaptor; - - /** - * Internal D-Bus handler. Called by the Akonadi server - * in order to trigger the processing of an item. Don't touch :) - */ - void beginProcessItem( qlonglong id ); - -Q_SIGNALS: - /** - * Internal D-Bus signal. Used to report item processing termination - * to the Akonadi server. Don't touch :) - */ - void itemProcessed( qlonglong id ); - -private: - - Q_DECLARE_PRIVATE( PreprocessorBase ) + void beginProcessItem( qlonglong itemId ); + + private: + // dbus Preprocessor interface + friend class ::PreprocessorAdaptor; + + Q_DECLARE_PRIVATE( PreprocessorBase ) }; // class PreprocessorBase } // namespace Akonadi #ifndef AKONADI_PREPROCESSOR_MAIN /** * Convenience Macro for the most common main() function for Akonadi preprocessors. */ #define AKONADI_PREPROCESSOR_MAIN( preProcessorClass ) \ int main( int argc, char **argv ) \ { \ return Akonadi::PreprocessorBase::init( argc, argv ); \ } #endif //!AKONADI_RESOURCE_MAIN - #endif //!_PREPROCESSORBASE_H_