File indexing completed on 2024-06-16 04:50:00

0001 /*
0002     SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #pragma once
0008 
0009 #include "akonadiagentbase_export.h"
0010 // AkonadiCore
0011 #include "akonadi/item.h"
0012 
0013 #include <QString>
0014 
0015 #include <memory>
0016 
0017 namespace Akonadi
0018 {
0019 class TransportResourceBasePrivate;
0020 
0021 /**
0022   * @short Resource implementing mail transport capability.
0023   *
0024   * This class allows a resource to provide mail transport (i.e. sending
0025   * mail). A resource than can provide mail transport inherits from both
0026   * ResourceBase and TransportResourceBase, implements the virtual method
0027   * sendItem(), and calls itemSent() when finished sending.
0028   *
0029   * The resource must also have the "MailTransport" capability flag. For example
0030   * the desktop file may contain:
0031     \code
0032     X-Akonadi-Capabilities=Resource,MailTransport
0033     \endcode
0034   *
0035   * For an example of a transport-enabled resource, see
0036   * kdepim/runtime/resources/mailtransport_dummy
0037   *
0038   * @author Constantin Berzan <exit3219@gmail.com>
0039   * @since 4.4
0040  */
0041 class AKONADIAGENTBASE_EXPORT TransportResourceBase
0042 {
0043 public:
0044     /**
0045      * Creates a new transport resource base.
0046      */
0047     TransportResourceBase();
0048 
0049     /**
0050      * Destroys the transport resource base.
0051      */
0052     virtual ~TransportResourceBase();
0053 
0054     /**
0055      * Describes the result of the transport process.
0056      */
0057     enum TransportResult {
0058         TransportSucceeded, ///< The transport process succeeded.
0059         TransportFailed ///< The transport process failed.
0060     };
0061 
0062     /**
0063      * This method is called when the given @p item shall be send.
0064      * When the sending is done or an error occurred during
0065      * sending, call itemSent() with the appropriate result flag.
0066      *
0067      * @param item The message item to be send.
0068      * @see itemSent().
0069      */
0070     virtual void sendItem(const Akonadi::Item &item) = 0;
0071 
0072     /**
0073      * This method marks the sending of the passed @p item
0074      * as finished.
0075      *
0076      * @param item The item that was sent.
0077      * @param result The result that indicates whether the sending
0078      *               was successful or not.
0079      * @param message An optional text explanation of the result.
0080      * @see Transport.
0081      */
0082     void itemSent(const Akonadi::Item &item, TransportResult result, const QString &message = QString());
0083 
0084 private:
0085     /// @cond PRIVATE
0086     std::unique_ptr<TransportResourceBasePrivate> const d;
0087     /// @endcond
0088 };
0089 
0090 }