calendarsupport/attachmenthandler.h

   1 /*
   2   Copyright (c) 2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>
   3
   4   This library is free software; you can redistribute it and/or
   5   modify it under the terms of the GNU Library General Public
   6   License as published by the Free Software Foundation; either
   7   version 2 of the License, or (at your option) any later version.
   8
   9   This library is distributed in the hope that it will be useful,
  10   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12   Library General Public License for more details.
  13
  14   You should have received a copy of the GNU Library General Public License
  15   along with this library; see the file COPYING.LIB.  If not, write to
  16   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17   Boston, MA 02110-1301, USA.
  18 */
  19 /**
  20   @file
  21   This file is part of the API for handling calendar data and provides
  22   static functions for dealing with calendar incidence attachments.
  23
  24   @author Allen Winter \<winter@kde.org\>
  25 */
  26 #ifndef CALENDARSUPPORT_ATTACHMENTHANDLER_H
  27 #define CALENDARSUPPORT_ATTACHMENTHANDLER_H
  28
  29 #include <KCalCore/Attachment>
  30 #include <KCalCore/Incidence>
  31 #include <KCalCore/ScheduleMessage>
  32
  33 #include <QObject>
  34
  35 class KJob;
  36
  37 class QString;
  38 class QWidget;
  39
  40 namespace CalendarSupport {
  41
  42 /**
  43   @brief
  44   Provides methods to handle incidence attachments.
  45
  46   Includes functions to view and save attachments.
  47 */
  48 class AttachmentHandler : public QObject
  49 {
  50   Q_OBJECT
  51   public:
  52
  53   /**
  54    * Constructs an AttachmentHandler.
  55    * @param parent is the parent widget for the dialogs used by this class.
  56    */
  57     explicit AttachmentHandler( QWidget *parent );
  58    ~AttachmentHandler();
  59
  60   /**
  61    * Finds the attachment in the user's calendar, by @p attachmentName and @p incidence.
  62    *
  63    * @param attachmentName is the name of the attachment
  64    * @param incidence is a pointer to a valid Incidence object containing the attachment.
  65    * @return a pointer to the Attachment object located; 0 if no such attachment could be found.
  66    */
  67   KCalCore::Attachment::Ptr find( const QString &attachmentName,
  68                                   const KCalCore::Incidence::Ptr &incidence );
  69
  70   /**
  71    * Finds the attachment in the user's calendar, by @p attachmentName and a scheduler message;
  72    * in other words, this function is intended to retrieve attachments from calendar invitations.
  73    *
  74    * @param attachmentName is the name of the attachment
  75    * @param message is a pointer to a valid ScheduleMessage object containing the attachment.
  76    * @return a pointer to the Attachment object located; 0 if no such attachment could be found.
  77    */
  78   KCalCore::Attachment::Ptr find( const QString &attachmentName,
  79                                   const KCalCore::ScheduleMessage::Ptr &message );
  80
  81   /**
  82    * Launches a viewer on the specified attachment.
  83    *
  84    * @param attachment is a pointer to a valid Attachment object.
  85    * @return true if the viewer program successfully launched; false otherwise.
  86    */
  87   bool view( const KCalCore::Attachment::Ptr &attachment );
  88
  89   /**
  90    * Launches a viewer on the specified attachment.
  91    *
  92    * @param attachmentName is the name of the attachment
  93    * @param incidence is a pointer to a valid Incidence object containing the attachment.
  94    * @return true if the attachment could be found and the viewer program successfully launched;
  95    * false otherwise.
  96    */
  97   bool view( const QString &attachmentName,
  98              const KCalCore::Incidence::Ptr &incidence );
  99
 100   /**
 101     Launches a viewer on the specified attachment.
 102
 103     @param attachmentName is the name of the attachment
 104     @param uid is a QString containing a UID of the incidence containing the attachment.
 105
 106     This function is async and will return immediately. Listen to signal viewFinished()
 107     if you're interested on the success of this operation.
 108
 109   */
 110   void view( const QString &attachmentName, const QString &uid );
 111
 112   /**
 113     Launches a viewer on the specified attachment.
 114
 115     @param attachmentName is the name of the attachment
 116     @param message is a pointer to a valid ScheduleMessage object containing the attachment.
 117
 118     @return true if the attachment could be found and the viewer program successfully launched;
 119     false otherwise.
 120   */
 121   bool view( const QString &attachmentName,
 122              const KCalCore::ScheduleMessage::Ptr &message );
 123
 124   /**
 125     Saves the specified attachment to a file of the user's choice.
 126
 127     @param attachment is a pointer to a valid Attachment object.
 128
 129     @return true if the save operation was successful; false otherwise.
 130   */
 131   bool saveAs( const KCalCore::Attachment::Ptr &attachment );
 132
 133   /**
 134     Saves the specified attachment to a file of the user's choice.
 135
 136     @param attachmentName is the name of the attachment
 137     @param incidence is a pointer to a valid Incidence object containing the attachment.
 138
 139     @return true if the attachment could be found and the save operation was successful;
 140     false otherwise.
 141   */
 142   bool saveAs( const QString &attachmentName,
 143                const KCalCore::Incidence::Ptr &incidence );
 144
 145   /**
 146     Saves the specified attachment to a file of the user's choice.
 147
 148     @param attachmentName is the name of the attachment
 149     @param uid is a QString containing a UID of the incidence containing the attachment.
 150
 151     This function is async, it will return immediately. Listen to signal saveAsFinished()
 152     if you're interested on the success of this operation.
 153   */
 154   void saveAs( const QString &attachmentName, const QString &uid );
 155
 156   /**
 157     Saves the specified attachment to a file of the user's choice.
 158
 159     @param attachmentName is the name of the attachment
 160     @param message is a pointer to a valid ScheduleMessage object containing the attachment.
 161
 162     @return true if the attachment could be found and the save operation was successful;
 163     false otherwise.
 164   */
 165   bool saveAs( const QString &attachmentName,
 166                const KCalCore::ScheduleMessage::Ptr &message );
 167
 168   Q_SIGNALS:
 169     void viewFinished( const QString &uid, const QString &attachmentName, bool success );
 170     void saveAsFinished( const QString &uid, const QString &attachmentName, bool success );
 171
 172   private Q_SLOTS:
 173     void slotFinishView( KJob *job );
 174     void slotFinishSaveAs( KJob *job );
 175
 176   private:
 177     //@cond PRIVATE
 178     class Private;
 179     Private *const d;
 180     //@endcond
 181
 182 }; // class AttachmentHandler
 183
 184 } // namespace CalendarSupport
 185
 186 #endif