src/folder.h

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
   2
   3 /*
   4  * Sylpheed -- a GTK+ based, lightweight, and fast e-mail client
   5  * Copyright (C) 1999-2012 Hiroyuki Yamamoto and the Claws Mail team
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  19  *
  20  */
  21
  22 #ifndef __FOLDER_H__
  23 #define __FOLDER_H__
  24
  25 #include <glib.h>
  26 #include <time.h>
  27
  28 typedef struct _Folder          Folder;
  29 typedef struct _FolderClass     FolderClass;
  30
  31 typedef struct _FolderItem      FolderItem;
  32 typedef struct _FolderUpdateData        FolderUpdateData;
  33 typedef struct _FolderItemUpdateData    FolderItemUpdateData;
  34 typedef struct _PersistPrefs            PersistPrefs;
  35
  36 #define FOLDER(obj)             ((Folder *)obj)
  37 #define FOLDER_CLASS(obj)       (FOLDER(obj)->klass)
  38 #define FOLDER_TYPE(obj)        (FOLDER(obj)->klass->type)
  39
  40 #define FOLDER_IS_LOCAL(obj)    (FOLDER_TYPE(obj) == F_MH      || \
  41                                  FOLDER_TYPE(obj) == F_MBOX    || \
  42                                  FOLDER_TYPE(obj) == F_MAILDIR)
  43
  44 #define FOLDER_ITEM(obj)        ((FolderItem *)obj)
  45
  46 #define FOLDER_UPDATE_HOOKLIST "folder_update"
  47 #define FOLDER_ITEM_UPDATE_HOOKLIST "folder_item_update"
  48
  49 typedef enum
  50 {
  51         F_MH,
  52         F_MBOX,
  53         F_MAILDIR,
  54         F_IMAP,
  55         F_NEWS,
  56         F_UNKNOWN
  57 } FolderType;
  58
  59 typedef enum
  60 {
  61         F_NORMAL,
  62         F_INBOX,
  63         F_OUTBOX,
  64         F_DRAFT,
  65         F_QUEUE,
  66         F_TRASH
  67 } SpecialFolderItemType;
  68
  69 typedef enum
  70 {
  71         SORT_BY_NONE,
  72         SORT_BY_NUMBER,
  73         SORT_BY_SIZE,
  74         SORT_BY_DATE,
  75         SORT_BY_FROM,
  76         SORT_BY_SUBJECT,
  77         SORT_BY_SCORE,
  78         SORT_BY_LABEL,
  79         SORT_BY_MARK,
  80         SORT_BY_STATUS,
  81         SORT_BY_MIME,
  82         SORT_BY_TO,
  83         SORT_BY_LOCKED,
  84         SORT_BY_TAGS,
  85         SORT_BY_THREAD_DATE
  86 } FolderSortKey;
  87
  88 typedef enum
  89 {
  90         SORT_ASCENDING,
  91         SORT_DESCENDING
  92 } FolderSortType;
  93
  94 typedef enum
  95 {
  96         F_MOVE_OK = 0,
  97         F_MOVE_FAILED_DEST_IS_PARENT = -1,
  98         F_MOVE_FAILED_DEST_IS_CHILD = -2,
  99         F_MOVE_FAILED_DEST_OUTSIDE_MAILBOX = -3,
 100         F_MOVE_FAILED = -4
 101 } FolderItemMoveResult;
 102
 103 typedef enum
 104 {
 105         FOLDER_ADD_FOLDER               = 1 << 0,
 106         FOLDER_REMOVE_FOLDER            = 1 << 1,
 107         FOLDER_TREE_CHANGED             = 1 << 2,
 108         FOLDER_ADD_FOLDERITEM           = 1 << 3,
 109         FOLDER_REMOVE_FOLDERITEM        = 1 << 4,
 110         FOLDER_RENAME_FOLDERITEM        = 1 << 5,
 111         FOLDER_MOVE_FOLDERITEM          = 1 << 6
 112 } FolderUpdateFlags;
 113
 114 typedef enum
 115 {
 116         F_ITEM_UPDATE_MSGCNT = 1 << 0,
 117         F_ITEM_UPDATE_CONTENT = 1 << 1,
 118         F_ITEM_UPDATE_ADDMSG = 1 << 2,
 119         F_ITEM_UPDATE_REMOVEMSG = 1 << 3,
 120         F_ITEM_UPDATE_NAME = 1 << 4
 121 } FolderItemUpdateFlags;
 122
 123 typedef void (*FolderUIFunc)            (Folder         *folder,
 124                                          FolderItem     *item,
 125                                          gpointer        data);
 126 typedef void (*FolderDestroyNotify)     (Folder         *folder,
 127                                          FolderItem     *item,
 128                                          gpointer        data);
 129 typedef void (*FolderItemFunc)  (FolderItem     *item,
 130                                          gpointer        data);
 131
 132
 133 #include "proctypes.h"
 134 #include "xml.h"
 135 #include "prefs_account.h"
 136 #include "matchertypes.h"
 137
 138 struct _MsgCache;
 139
 140 struct _Folder
 141 {
 142         FolderClass *klass;
 143
 144         gchar *name;
 145         PrefsAccount *account;
 146         guint sort;
 147
 148         FolderItem *inbox;
 149         FolderItem *outbox;
 150         FolderItem *draft;
 151         FolderItem *queue;
 152         FolderItem *trash;
 153
 154         FolderUIFunc ui_func;
 155         gpointer     ui_func_data;
 156
 157         GNode *node;
 158
 159         gpointer data;
 160
 161         GHashTable *newsart;
 162 };
 163
 164 /**
 165  * Callback used to convey progress information of a specific search.
 166  *
 167  * \param data User-provided data
 168  * \param on_server Whether or not the current progress information originated from the
 169  *                  server
 170  * \param at Number of the last message processed
 171  * \param matched Number of messages with definitive matches found so far
 172  * \param total Number of messages to be processed
 173  *
 174  * \note
 175  * Even if the mailserver does not support progress reports, an instance of this type
 176  * should be invoked when serverside search starts and ends, with \c at set to \c 0 and
 177  * \c total, respectively.
 178  */
 179 typedef gboolean (*SearchProgressNotify)(gpointer data, gboolean on_server, guint at, guint matched, guint total);
 180
 181 struct _FolderClass
 182 {
 183         /**
 184          * A numeric identifier for the FolderClass. Will be removed in the future
 185          */
 186         FolderType  type;
 187         /**
 188          * A string identifier for the FolderClass. Currently used in folderlist.xml.
 189          * Should be lowercase.
 190          */
 191         gchar      *idstr;
 192         /**
 193          * A string for the User Interface that identifies the FolderClass to the
 194          * user. Can be upper and lowercase unlike the idstr.
 195          */
 196         gchar      *uistr;
 197         /**
 198         * A boolean to indicate whether or not the FolderClass supports search on the
 199         * server. If \c TRUE, setting \c on_server in \c search_msgs offloads search to
 200         * the server.
 201         */
 202         gboolean    supports_server_search;
 203
 204         /**
 205          * Klass-specific prefs pages
 206          */
 207
 208         GSList *prefs_pages;
 209
 210         /* virtual functions */
 211
 212         /* Folder funtions */
 213         /**
 214          * Create a new \c Folder of this \c FolderClass.
 215          *
 216          * \param name The name of the new Folder
 217          * \param path The path of the new Folder
 218          * \return The new \c Folder, or \c NULL when creating the \c Folder
 219          *         failed
 220          */
 221         Folder          *(*new_folder)          (const gchar    *name,
 222                                                  const gchar    *path);
 223         /**
 224          * Destroy a \c Folder of this \c FolderClass, frees all resources
 225          * allocated by the Folder
 226          *
 227          * \param folder The \c Folder that should be destroyed.
 228          */
 229         void            (*destroy_folder)       (Folder         *folder);
 230         /**
 231          * Set the Folder's internal attributes from an \c XMLTag. Also sets the
 232          * parameters of the root-FolderItem of the \c Folder. If \c NULL
 233          * the default function of the basic \¢ FolderClass is used, so it
 234          * must not be \c NULL if one of the parent \c FolderClasses has a \c set_xml
 235          * function. In that case the parent \c FolderClass' \c set_xml function
 236          * can be used or it has to be called with the \c folder and \c tag by
 237          * the implementation.
 238          *
 239          * \param folder The \c Folder which's attributes should be updated
 240          * \param tag The \c XMLTag containing the \c XMLAttrs for the attributes
 241          */
 242         void             (*set_xml)             (Folder         *folder,
 243                                                  XMLTag         *tag);
 244         /**
 245          * Get an \c XMLTag for the attributes of the \c Folder and the root-FolderItem
 246          * of the \c Folder. If \c NULL the default implementation for the basic
 247          * FolderClass will be used, so it must not be \c NULL if one of the
 248          * parent \c FolderClasses has it's own implementation for \c get_xml.
 249          * In that case the parent FolderClass' \c get_xml function can be
 250          * used or the \c XMLTag has to be fetched from the parent's \c get_xml
 251          * function and then the \c FolderClass specific attributes can be
 252          * added to it.
 253          *
 254          * \param Folder The \c Folder which's attributes should be set in the
 255          *               \c XMLTag's \c XMLAttrs
 256          * \return XMLTag An \c XMLTag with \c XMLAttrs containing the \c Folder's
 257          *                attributes.
 258          */
 259         XMLTag          *(*get_xml)             (Folder         *folder);
 260         /**
 261          * Rebuild the folder tree from the folder's data
 262          * \todo New implementations of MH and IMAP are actually syncronizing
 263          *       the tree with the folder by reusing the old \c FolderItems.
 264          *       Claws still destroys the old tree before calling this function.
 265          *
 266          * \param folder The folder which's tree should be rebuild
 267          * \return 0 on success, a negative number otherwise
 268          */
 269         gint            (*scan_tree)            (Folder         *folder);
 270
 271         gint            (*create_tree)          (Folder         *folder);
 272
 273         /* FolderItem functions */
 274         /**
 275          * Create a new \c FolderItem structure for the \c FolderClass.
 276          * \c FolderClasses can have their own \c FolderItem structure with
 277          * extra attributes.
 278          *
 279          * \param folder The \c Folder for that a \c FolderItem should be
 280          *               created
 281          * \return The new \c FolderItem or NULL in case of an error
 282          */
 283         FolderItem      *(*item_new)            (Folder         *folder);
 284         /**
 285          * Destroy a \c FolderItem from this \c FolderClass. The \c FolderClass
 286          * has to free all private resources used by the \c FolderItem.
 287          *
 288          * \param folder The \c Folder of the \c FolderItem
 289          * \param item The \c FolderItem that should be destroyed
 290          */
 291         void             (*item_destroy)        (Folder         *folder,
 292                                                  FolderItem     *item);
 293         /**
 294          * Set the \c FolderItem's internal attributes from an \c XMLTag. If
 295          * \c NULL the default function of the basic \c FolderClass is used, so it
 296          * must not be \c NULL if one of the parent \c FolderClasses has a \c item_set_xml
 297          * function. In that case the parent \c FolderClass' \c item_set_xml function
 298          * can be used or it has to be called with the \c folder, \c item and \c tag by
 299          * the implementation.
 300          *
 301          * \param folder The \c Folder of the \c FolderItem
 302          * \param item The \c FolderItems which's attributes should be set
 303          * \param tag The \c XMLTag with \c XMLAttrs for the \c FolderItem's
 304          *            attributes
 305          */
 306         void             (*item_set_xml)        (Folder         *folder,
 307                                                  FolderItem     *item,
 308                                                  XMLTag         *tag);
 309         /**
 310          * Get an \c XMLTag for the attributes of the \c FolderItem If \c NULL
 311          * the default implementation for the basic \c FolderClass will be used,
 312          * so it must not be \c NULL if one of the parent \c FolderClasses has
 313          * it's own implementation for \c item_get_xml. In that case the parent
 314          * FolderClass' \c item_get_xml function can be used or the \c XMLTag
 315          * has to be fetched from the parent's \c item_get_xml function and
 316          * then the \c FolderClass specific attributes can be added to it.
 317          *
 318          * \param folder The \c Folder of the \c FolderItem
 319          * \parem item The \c FolderItem which's attributes should be set in
 320          *             the \c XMLTag's \c XMLAttrs
 321          * \return An \c XMLTag with \c XMLAttrs containing the \c FolderItem's
 322          *         attributes.
 323          */
 324         XMLTag          *(*item_get_xml)        (Folder         *folder,
 325                                                  FolderItem     *item);
 326         /**
 327          * Get a local path for the \c FolderItem where Sylpheed can save
 328          * it's cache data. For local directory based folders this can be the
 329          * real path. For other folders it can be the local cache directory.
 330          *
 331          * \param folder The \c Folder of the \c FolderItem
 332          * \param item The \c FolderItem for that a path should be returned
 333          * \return A path for the \c FolderItem
 334          */
 335         gchar           *(*item_get_path)       (Folder         *folder,
 336                                                  FolderItem     *item);
 337         /**
 338          * Create a new \c FolderItem. The function must use folder_item_append
 339          * to add the new \c FolderItem to the folder tree
 340          *
 341          * \param folder The \c Folder in which a new \c FolderItem should be
 342          *               created
 343          * \param parent \c The parent \c FolderItem for the new \c FolderItem
 344          * \parem name The name for the new \c FolderItem
 345          * \return The new \c FolderItem
 346          */
 347         FolderItem      *(*create_folder)       (Folder         *folder,
 348                                                  FolderItem     *parent,
 349                                                  const gchar    *name);
 350         /**
 351          * Rename a \c FolderItem
 352          *
 353          * \param folder The \c Folder of the \c FolderItem that should be
 354          *               renamed
 355          * \param item The \c FolderItem that should be renamed
 356          * \param name The new name of the \c FolderItem
 357          * \return 0 on success, a negative number otherwise
 358          */
 359         gint             (*rename_folder)       (Folder         *folder,
 360                                                  FolderItem     *item,
 361                                                  const gchar    *name);
 362         /**
 363          * Remove a \c FolderItem from the \c Folder
 364          *
 365          * \param folder The \c Folder that contains the \c FolderItem
 366          * \param item The \c FolderItem that should be removed
 367          * \return 0 on sucess, a negative number otherwise
 368          */
 369         gint             (*remove_folder)       (Folder         *folder,
 370                                                  FolderItem     *item);
 371         /**
 372          * Close a \c FolderItem. Called when the user deselects a
 373          * \c FolderItem.
 374          *
 375          * \attention In Sylpheed-Main operations can only be done on the
 376          *            \c FolderItem that is opened in the SummaryView. This
 377          *            \c FolderItem will be closed when you select a new
 378          *            \c FolderItem in the FolderView. In Claws operations can
 379          *            be done any time on any folder and you should not expect
 380          *            that all \c FolderItems get closed after operations
 381          *
 382          * \param folder The \c Folder that contains the \c FolderItem
 383          * \param item The \c FolderItem that should be closed
 384          * \return 0 on success, a negative number otherwise
 385          */
 386         gint             (*close)               (Folder         *folder,
 387                                                  FolderItem     *item);
 388         /**
 389          * Get the list of message numbers for the messages in the \c FolderItem
 390          *
 391          * \param folder The \c Folder that contains the \c FolderItem
 392          * \param item The \c FolderItem for which the message numbers should
 393          *             be fetched
 394          * \param list Pointer to a GSList where message numbers have to be
 395          *             added. Because of the implementation of the GSList that
 396          *             changes the pointer of the GSList itself when the first
 397          *             item is added this is a pointer to a pointer to a
 398          *             GSList structure. Use *item = g_slist_...(*item, ...)
 399          *             operations to modify the list.
 400          * \param old_uids_valid In some \c Folders the old UIDs can be invalid.
 401          *                       Set this pointer to a gboolean to TRUE if the
 402          *                       old UIDs are still valid, otherwise set it to
 403          *                       FALSE and the folder system will discard it's
 404          *                       cache data of the previously know UIDs
 405          * \return The number of message numbers add to the list on success,
 406          *         a negative number otherwise.
 407          */
 408         gint             (*get_num_list)        (Folder         *folder,
 409                                                  FolderItem     *item,
 410                                                  GSList        **list,
 411                                                  gboolean       *old_uids_valid);
 412         /**
 413          * Tell the folder system if a \c FolderItem should be scanned
 414          * (cache data syncronized with the folder content) when it is required
 415          * because the \c FolderItem's content changed. If NULL the folder
 416          * system will not do automatic scanning of \c FolderItems
 417          *
 418          * \param folder The \c Folder that contains the \c FolderItem
 419          * \param item The \c FolderItem which's content should be checked
 420          * \return TRUE if the \c FolderItem should be scanned, FALSE otherwise
 421          */
 422         gboolean        (*scan_required)        (Folder         *folder,
 423                                                  FolderItem     *item);
 424
 425         /**
 426          * Updates the known mtime of a folder
 427          */
 428         void            (*set_mtime)            (Folder         *folder,
 429                                                  FolderItem     *item);
 430
 431         /* Message functions */
 432         /**
 433          * Get a MsgInfo for a message in a \c FolderItem
 434          *
 435          * \param folder The \c Folder containing the message
 436          * \param item The \c FolderItem containing the message
 437          * \param num The message number of the message
 438          * \return A pointer to a \c MsgInfo decribing the message or \c
 439          *         NULL in case of an error
 440          */
 441         MsgInfo         *(*get_msginfo)         (Folder         *folder,
 442                                                  FolderItem     *item,
 443                                                  gint            num);
 444         /**
 445          * Get \c MsgInfos for a list of message numbers
 446          *
 447          * \param folder The \c Folder containing the message
 448          * \param item The \c FolderItem containing the message
 449          * \param msgnum_list A list of message numbers for which the
 450          *                    \c MsgInfos should be fetched
 451          * \return A list of \c MsgInfos for the messages in the \c msgnum_list
 452          *         that really exist. Messages that are not found can simply
 453          *         be left out.
 454          */
 455         MsgInfoList     *(*get_msginfos)        (Folder         *folder,
 456                                                  FolderItem     *item,
 457                                                  MsgNumberList  *msgnum_list);
 458         /**
 459          * Get the filename for a message. This can either be the real message
 460          * file for local folders or a temporary file for remote folders.
 461          *
 462          * \param folder The \c Folder containing the message
 463          * \param item The \c FolderItem containing the message
 464          * \param num The message number of the message
 465          * \return A string with the filename of the message file. The returned
 466          *         string has to be freed with \c g_free(). If message is not
 467          *         available return NULL.
 468          */
 469         gchar           *(*fetch_msg)           (Folder         *folder,
 470                                                  FolderItem     *item,
 471                                                  gint            num);
 472         gchar           *(*fetch_msg_full)      (Folder         *folder,
 473                                                  FolderItem     *item,
 474                                                  gint            num,
 475                                                  gboolean        headers,
 476                                                  gboolean        body);
 477         /**
 478          * Add a single message file to a folder with the given flags (if
 479          * flag handling is supported by the folder)
 480          *
 481          * \param folder The target \c Folder for the message
 482          * \param dest the target \c FolderItem for the message
 483          * \param file The file that contains the message
 484          * \param flags The flags the new message should have in the folder
 485          * \return 0 on success, a negative number otherwise
 486          */
 487         gint            (*add_msg)              (Folder         *folder,
 488                                                  FolderItem     *dest,
 489                                                  const gchar    *file,
 490                                                  MsgFlags       *flags);
 491         /**
 492          * Add multiple messages to a \c FolderItem. If NULL the folder
 493          * system will add messages with \c add_msg one by one
 494          *
 495          * \param folder The target \c Folder for the messages
 496          * \param dest the target \c FolderItem for the messages
 497          * \param file_list A list of \c MsgFileInfos which contain the
 498          *                  filenames and flags for the new messages
 499          * \param relation Insert tuples of (MsgFileInfo, new message number) to
 500          *                 provide feedback for the folder system which new
 501          *                 message number a \c MsgFileInfo got in dest. Insert
 502          *                 0 if the new message number is unknown.
 503          */
 504         gint            (*add_msgs)             (Folder         *folder,
 505                                                  FolderItem     *dest,
 506                                                  GSList         *file_list,
 507                                                  GHashTable     *relation);
 508         /**
 509          * Copy a message to a FolderItem
 510          *
 511          * \param folder The \c Folder of the destination FolderItem
 512          * \param dest The destination \c FolderItem for the message
 513          * \param msginfo The message that should be copied
 514          * \return The message number the copied message got, 0 if it is
 515          *         unknown because message numbers are assigned by an external
 516          *         system and not available after copying or a negative number
 517          *         if an error occuried
 518          */
 519         gint            (*copy_msg)             (Folder         *folder,
 520                                                  FolderItem     *dest,
 521                                                  MsgInfo        *msginfo);
 522         /**
 523          * Copy multiple messages to a \c FolderItem. If \c NULL the folder
 524          * system will use \c copy_msg to copy messages one by one.
 525          *
 526          * \param folder The \c Folder of the destination FolderItem
 527          * \param dest The destination \c FolderItem for the message
 528          * \param msglist A list of \c MsgInfos which should be copied to dest
 529          * \param relation Insert tuples of (MsgInfo, new message number) to
 530          *                 provide feedback for the folder system which new
 531          *                 message number a \c MsgInfo got in dest. Insert
 532          *                 0 if the new message number is unknown.
 533          * \return 0 on success, a negative number otherwise
 534          */
 535         gint            (*copy_msgs)            (Folder         *folder,
 536                                                  FolderItem     *dest,
 537                                                  MsgInfoList    *msglist,
 538                                                  GHashTable     *relation);
 539
 540         /**
 541          * Search the given FolderItem for messages matching \c predicate.
 542          * The search may be offloaded to the server if the \c folder
 543          * supports server side search, as indicated by \c supports_server_search.
 544          *
 545          * \param folder The \c Folder of the container FolderItem
 546          * \param container The \c FolderItem containing the messages to be searched
 547          * \param msgs The \c MsgNumberList results will be saved to.
 548          *             If <tt>*msgs != NULL</tt>, the search will be restricted to
 549          *             messages whose numbers are contained therein.
 550          *             If \c on_server is considered \c FALSE, messages are guaranteed to
 551          *             be processed in the order they are listed in \c msgs.
 552          *             On error, \c msgs will not be changed.
 553          * \param on_server Whether or not the search should be offloaded to the server.
 554          *                  If \c on_server is not \c NULL and points to a \c TRUE value,
 555          *                  search will be done on the server. If \c predicate contains
 556          *                  one or more atoms the server does not support, the value
 557          *                  pointed to by \c on_server will be set to \c FALSE upon return.
 558          *                  In this case, \c msgs must still contain a valid superset of
 559          *                  messages actually matched by \c predicate, or this method must
 560          *                  return an error.
 561          *                  \c on_server may only point to a \c TRUE value if
 562          *                  \c supports_server_search is also \c TRUE.
 563          *                  \c NULL and pointer to \c FALSE are considered equivalent and
 564          *                  will start a client-only search.
 565          * \param predicate The \c MatcherList to use in the search
 566          * \param progress_cb Called for every message searched.
 567          *                    When search is offloaded to the server, this function
 568          *                    may or may not be called, depending on the implementation.
 569          *                    The second argument of this function will be the number of
 570          *                    messages already processed.
 571          *                    Return \c FALSE from this function to end the search.
 572          *                    May be \c NULL, no calls will be made in this case.
 573          * \param progress_data First argument value for \c progress_cb
 574          * \return Number of messages that matched \c predicate on success, a negative
 575          *         number otherwise.
 576          *
 577          * \note
 578          * When search is stopped by returning \c FALSE from \c progress_cb, \c msgs will
 579          * contain all messages found until the point of cancellation. The number of
 580          * messages found will be returned as indicated above.
 581          */
 582         gint            (*search_msgs)          (Folder                 *folder,
 583                                                  FolderItem             *container,
 584                                                  MsgNumberList          **msgs,
 585                                                  gboolean               *on_server,
 586                                                  MatcherList            *predicate,
 587                                                  SearchProgressNotify   progress_cb,
 588                                                  gpointer               progress_data);
 589
 590
 591         /**
 592          * Remove a message from a \c FolderItem.
 593          *
 594          * \param folder The \c Folder of the message
 595          * \param item The \c FolderItem containing the message
 596          * \param num The message number of the message
 597          * \return 0 on success, a negative number otherwise
 598          */
 599         gint            (*remove_msg)           (Folder         *folder,
 600                                                  FolderItem     *item,
 601                                                  gint            num);
 602         gint            (*remove_msgs)          (Folder         *folder,
 603                                                  FolderItem     *item,
 604                                                  MsgInfoList    *msglist,
 605                                                  GHashTable     *relation);
 606         gint            (*expunge)              (Folder         *folder,
 607                                                  FolderItem     *item);
 608         /**
 609          * Remove all messages in a \ c FolderItem
 610          *
 611          * \param folder The \c Folder of the \c FolderItem
 612          * \param item The \FolderItem which's messages should be deleted
 613          * \return 0 on succes, a negative number otherwise
 614          */
 615         gint            (*remove_all_msg)       (Folder         *folder,
 616                                                  FolderItem     *item);
 617         /**
 618          * Check if a message has been modified by someone else
 619          *
 620          * \param folder The \c Folder of the message
 621          * \param item The \c FolderItem containing the message
 622          * \param msginfo The \c MsgInfo for the message that should be checked
 623          * \return \c TRUE if the message was modified, \c FALSE otherwise
 624          */
 625         gboolean        (*is_msg_changed)       (Folder         *folder,
 626                                                  FolderItem     *item,
 627                                                  MsgInfo        *msginfo);
 628         /**
 629          * Update a message's flags in the folder data. If NULL only the
 630          * internal flag management will be used. The function has to set
 631          * \c msginfo->flags.perm_flags. It does not have to set the flags
 632          * that it got as \c newflags. If a flag can not be set in this
 633          * \c FolderClass the function can refuse to set it. Flags that are not
 634          * supported by the \c FolderClass should not be refused. They will be
 635          * managed by the internal cache in this case.
 636          *
 637          * \param folder The \c Folder of the message
 638          * \param item The \c FolderItem of the message
 639          * \param msginfo The \c MsgInfo for the message which's flags should be
 640          *                updated
 641          * \param newflags The flags the message should get
 642          */
 643         void            (*change_flags)         (Folder         *folder,
 644                                                  FolderItem     *item,
 645                                                  MsgInfo        *msginfo,
 646                                                  MsgPermFlags    newflags);
 647         /**
 648          * Get the flags for a list of messages. Flags that are not supported
 649          * by the folder should be preserved. They can be copied from
 650          * \c msginfo->flags.perm_flags
 651          *
 652          * \param folder The \c Folder of the messages
 653          * \param item The \c FolderItem of the messages
 654          * \param msglist The list of \c MsgInfos for which the flags should
 655          *                   be returned
 656          * \param msgflags A \c GRelation for tuples of (MsgInfo, new permanent
 657          *        flags for MsgInfo). Add tuples for the messages in msglist
 658          * \return 0 on success, a negative number otherwise
 659          */
 660         gint            (*get_flags)            (Folder         *folder,
 661                                                  FolderItem     *item,
 662                                                  MsgInfoList    *msglist,
 663                                                  GHashTable     *msgflags);
 664
 665         /* Sets batch mode for a FolderItem. It means that numerous flags updates
 666          * could follow, and the FolderClass implementation can cache them in order
 667          * to process them later when set_false will be called again with the
 668          * batch parameter set to FALSE.
 669          */
 670         void            (*set_batch)            (Folder         *folder,
 671                                                  FolderItem     *item,
 672                                                  gboolean        batch);
 673         /* Called when switching offline or asking for synchronisation. the imple
 674          * mentation should do what's necessary to be able to read mails present
 675          * in the FolderItem at this time with no network connectivity.
 676          * Days: max number of days of mail to fetch.
 677          */
 678         void            (*synchronise)          (FolderItem     *item,
 679                                                  gint            days);
 680
 681         /* Passed from claws-mail --subscribe scheme://uri. Implementations
 682          * should check if they handle this type of URI, and return TRUE in this
 683          * case after having subscribed it.
 684          */
 685         gboolean        (*subscribe)            (Folder         *folder,
 686                                                  const gchar    *uri);
 687
 688         /* Gets the preferred sort key and type for a folderclass. */
 689         void            (*get_sort_type)        (Folder         *folder,
 690                                                  FolderSortKey  *sort_key,
 691                                                  FolderSortType *sort_type);
 692
 693         /* Copies internal FolderItem data from one folderItem to another. Used
 694          * when moving folders (this move is in reality a folder creation, content
 695          * move, folder delettion).
 696          */
 697         void            (*copy_private_data)    (Folder         *folder,
 698                                                  FolderItem     *src,
 699                                                  FolderItem     *dest);
 700
 701         void            (*remove_cached_msg)    (Folder         *folder,
 702                                                  FolderItem     *item,
 703                                                  MsgInfo        *msginfo);
 704         void            (*commit_tags)          (FolderItem     *item,
 705                                                  MsgInfo        *msginfo,
 706                                                  GSList         *tags_set,
 707                                                  GSList         *tags_unset);
 708         void            (*item_opened)          (FolderItem     *item);
 709         void            (*item_closed)          (FolderItem     *item);
 710 };
 711
 712 enum {
 713         ITEM_NOT_SCANNING,
 714         ITEM_SCANNING_WITH_FLAGS,
 715         ITEM_SCANNING
 716 };
 717
 718 struct _FolderItemPrefs;
 719
 720 struct _FolderItem
 721 {
 722         SpecialFolderItemType stype;
 723
 724         gchar *name; /* UTF-8 */
 725         gchar *path; /* UTF-8 */
 726
 727         time_t mtime;
 728
 729         gint new_msgs;
 730         gint unread_msgs;
 731         gint total_msgs;
 732         gint unreadmarked_msgs;
 733         gint marked_msgs;
 734         gint replied_msgs;
 735         gint forwarded_msgs;
 736         gint locked_msgs;
 737         gint ignored_msgs;
 738         gint watched_msgs;
 739
 740         gint order;
 741
 742         gint last_num;
 743
 744         struct _MsgCache *cache;
 745         gboolean cache_dirty;
 746         gboolean mark_dirty;
 747         gboolean tags_dirty;
 748
 749         /* special flags */
 750         guint no_sub         : 1; /* no child allowed?    */
 751         guint no_select      : 1; /* not selectable?      */
 752         guint collapsed      : 1; /* collapsed item       */
 753         guint thread_collapsed      : 1; /* collapsed item       */
 754         guint threaded       : 1; /* threaded folder view */
 755         guint hide_read_msgs : 1; /* hide read messages   */
 756         guint ret_rcpt       : 1; /* return receipt       */
 757         guint search_match   : 1;
 758         guint hide_del_msgs : 1; /* hide deleted messages   */
 759         guint hide_read_threads : 1; /* hide threads with only read messages   */
 760
 761         gint op_count;
 762         guint opened         : 1; /* opened by summary view */
 763         FolderItemUpdateFlags update_flags; /* folderview for this folder should be updated */
 764
 765         FolderSortKey sort_key;
 766         FolderSortType sort_type;
 767
 768         GNode *node;
 769
 770         Folder *folder;
 771
 772         PrefsAccount *account;
 773
 774         gboolean apply_sub;
 775
 776         GSList *mark_queue;
 777
 778         gpointer data;
 779
 780         struct _FolderItemPrefs * prefs;
 781
 782         /* for faster search of special parents */
 783         SpecialFolderItemType parent_stype;
 784         gboolean processing_pending;
 785         gint scanning;
 786         guint last_seen;
 787 };
 788
 789 struct _PersistPrefs
 790 {
 791         FolderSortKey   sort_key;
 792         FolderSortType  sort_type;
 793         guint           collapsed       : 1;
 794         guint           thread_collapsed        : 1;
 795         guint           threaded        : 1;
 796         guint           hide_read_msgs  : 1; /* CLAWS */
 797         guint           ret_rcpt        : 1; /* CLAWS */
 798         guint           hide_del_msgs   : 1; /* CLAWS */
 799         guint           hide_read_threads       : 1;
 800 };
 801
 802 struct _FolderUpdateData
 803 {
 804         Folder                  *folder;
 805         FolderUpdateFlags        update_flags;
 806         FolderItem              *item;
 807         FolderItem              *item2;
 808 };
 809
 810 struct _FolderItemUpdateData
 811 {
 812         FolderItem              *item;
 813         FolderItemUpdateFlags    update_flags;
 814         MsgInfo                 *msg;
 815 };
 816
 817 void        folder_system_init          (void);
 818 void        folder_register_class       (FolderClass    *klass);
 819 void        folder_unregister_class     (FolderClass    *klass);
 820 Folder     *folder_new                  (FolderClass    *type,
 821                                          const gchar    *name,
 822                                          const gchar    *path);
 823 void        folder_init                 (Folder         *folder,
 824                                          const gchar    *name);
 825
 826 void        folder_destroy              (Folder         *folder);
 827
 828 void        folder_set_xml              (Folder          *folder,
 829                                          XMLTag          *tag);
 830 XMLTag     *folder_get_xml              (Folder          *folder);
 831
 832 FolderItem *folder_item_new             (Folder         *folder,
 833                                          const gchar    *name,
 834                                          const gchar    *path);
 835 void        folder_item_append          (FolderItem     *parent,
 836                                          FolderItem     *item);
 837 void        folder_item_remove          (FolderItem     *item);
 838 void        folder_item_remove_children (FolderItem     *item);
 839 void        folder_item_destroy         (FolderItem     *item);
 840 FolderItem *folder_item_parent          (FolderItem     *item);
 841
 842 void        folder_item_set_xml         (Folder          *folder,
 843                                          FolderItem      *item,
 844                                          XMLTag          *tag);
 845 XMLTag     *folder_item_get_xml         (Folder          *folder,
 846                                          FolderItem      *item);
 847
 848 void        folder_set_ui_func  (Folder         *folder,
 849                                  FolderUIFunc    func,
 850                                  gpointer        data);
 851 void        folder_set_name     (Folder         *folder,
 852                                  const gchar    *name);
 853 void        folder_set_sort     (Folder         *folder,
 854                                  guint           sort);
 855 void        folder_tree_destroy (Folder         *folder);
 856
 857 void   folder_add               (Folder         *folder);
 858 void   folder_remove            (Folder         *folder);
 859
 860 GList *folder_get_list          (void);
 861 gint   folder_read_list         (void);
 862 void   folder_write_list        (void);
 863 void   folder_scan_tree         (Folder *folder, gboolean rebuild);
 864 FolderItem *folder_create_folder(FolderItem     *parent, const gchar *name);
 865 gint   folder_item_rename       (FolderItem *item, gchar *newname);
 866 void   folder_update_op_count           (void);
 867 void   folder_func_to_all_folders       (FolderItemFunc function,
 868                                          gpointer data);
 869 void folder_count_total_msgs(guint *new_msgs, guint *unread_msgs,
 870                              guint *unreadmarked_msgs, guint *marked_msgs,
 871                              guint *total_msgs, guint *replied_msgs,
 872                              guint *forwarded_msgs, guint *locked_msgs,
 873                              guint *ignored_msgs, guint *watched_msgs);
 874 gchar *folder_get_status        (GPtrArray      *folders,
 875                                  gboolean        full);
 876
 877 Folder     *folder_find_from_identifier         (const gchar *identifier);
 878 Folder     *folder_find_from_path               (const gchar    *path);
 879 Folder     *folder_find_from_name               (const gchar    *name,
 880                                                  FolderClass    *klass);
 881 FolderItem *folder_find_item_from_path          (const gchar    *path);
 882 FolderItem *folder_find_item_from_real_path     (const gchar    *path);
 883 FolderClass *folder_get_class_from_string       (const gchar    *str);
 884 FolderItem *folder_find_child_item_by_name      (FolderItem     *item,
 885                                                  const gchar    *name);
 886 /* return value is locale charset */
 887 gchar      *folder_get_identifier               (Folder *folder);
 888 /* return value is locale charset */
 889 gchar      *folder_item_get_identifier          (FolderItem     *item);
 890 FolderItem *folder_find_item_from_identifier    (const gchar    *identifier);
 891 FolderItem *folder_get_item_from_identifier     (const gchar    *identifier);
 892 gchar      *folder_item_get_name                (FolderItem     *item);
 893
 894 FolderItem *folder_get_default_inbox    (void);
 895 FolderItem *folder_get_default_inbox_for_class(FolderType type);
 896 FolderItem *folder_get_default_outbox   (void);
 897 FolderItem *folder_get_default_outbox_for_class(FolderType type);
 898 FolderItem *folder_get_default_draft    (void);
 899 FolderItem *folder_get_default_draft_for_class(FolderType type);
 900 FolderItem *folder_get_default_queue    (void);
 901 FolderItem *folder_get_default_queue_for_class(FolderType type);
 902 FolderItem *folder_get_default_trash    (void);
 903 FolderItem *folder_get_default_trash_for_class(FolderType type);
 904 FolderItem *folder_get_default_processing (int account_id);
 905 void folder_set_missing_folders         (void);
 906 void folder_unref_account_all           (PrefsAccount   *account);
 907
 908 /* return value is locale encoded file name */
 909 gchar *folder_item_get_path             (FolderItem     *item);
 910
 911 gint   folder_item_open                 (FolderItem     *item);
 912 gint   folder_item_close                (FolderItem     *item);
 913 gint   folder_item_scan                 (FolderItem     *item);
 914 gint   folder_item_scan_full            (FolderItem     *item,
 915                                          gboolean        filtering);
 916 MsgInfo *folder_item_get_msginfo        (FolderItem     *item,
 917                                          gint            num);
 918 MsgInfo *folder_item_get_msginfo_by_msgid(FolderItem    *item,
 919                                          const gchar    *msgid);
 920 GSList *folder_item_get_msg_list        (FolderItem     *item);
 921 MsgNumberList *folder_item_get_number_list(FolderItem *item);
 922
 923 /* return value is locale charset */
 924 gchar *folder_item_fetch_msg            (FolderItem     *item,
 925                                          gint            num);
 926 gchar *folder_item_fetch_msg_full       (FolderItem     *item,
 927                                          gint            num,
 928                                          gboolean        get_headers,
 929                                          gboolean        get_body);
 930 gint   folder_item_add_msg              (FolderItem     *dest,
 931                                          const gchar    *file,
 932                                          MsgFlags       *flags,
 933                                          gboolean        remove_source);
 934 gint   folder_item_add_msgs             (FolderItem     *dest,
 935                                          GSList         *file_list,
 936                                          gboolean        remove_source);
 937 gint   folder_item_move_to              (FolderItem     *src,
 938                                          FolderItem     *dest,
 939                                          FolderItem    **new_item,
 940                                          gboolean        copy);
 941 gint   folder_item_move_msg             (FolderItem     *dest,
 942                                          MsgInfo        *msginfo);
 943 gint   folder_item_move_msgs            (FolderItem     *dest,
 944                                          GSList         *msglist);
 945 gint   folder_item_copy_msg             (FolderItem     *dest,
 946                                          MsgInfo        *msginfo);
 947 gint   folder_item_copy_msgs            (FolderItem     *dest,
 948                                          GSList         *msglist);
 949 gint   folder_item_search_msgs          (Folder                 *folder,
 950                                          FolderItem             *container,
 951                                          MsgNumberList          **msgs,
 952                                          gboolean               *on_server,
 953                                          MatcherList            *predicate,
 954                                          SearchProgressNotify   progress_cb,
 955                                          gpointer               progress_data);
 956 gint   folder_item_remove_msg           (FolderItem     *item,
 957                                          gint            num);
 958 gint   folder_item_remove_msgs          (FolderItem     *item,
 959                                          GSList         *msglist);
 960 gint   folder_item_expunge              (FolderItem     *item);
 961 gint   folder_item_remove_all_msg       (FolderItem     *item);
 962 void    folder_item_change_msg_flags    (FolderItem     *item,
 963                                          MsgInfo        *msginfo,
 964                                          MsgPermFlags    newflags);
 965 gboolean folder_item_is_msg_changed     (FolderItem     *item,
 966                                          MsgInfo        *msginfo);
 967
 968 void folder_clean_cache_memory          (FolderItem *protected_item);
 969 void folder_clean_cache_memory_force    (void);
 970 void folder_item_write_cache            (FolderItem *item);
 971
 972 void folder_item_apply_processing       (FolderItem *item);
 973
 974 void folder_item_update                 (FolderItem *item,
 975                                          FolderItemUpdateFlags update_flags);
 976 void folder_item_update_recursive       (FolderItem *item,
 977                                          FolderItemUpdateFlags update_flags);
 978 void folder_item_update_freeze          (void);
 979 void folder_item_update_thaw            (void);
 980 void folder_item_set_batch              (FolderItem *item, gboolean batch);
 981 gboolean folder_has_parent_of_type      (FolderItem *item, SpecialFolderItemType type);
 982 gboolean folder_is_child_of             (FolderItem *item, FolderItem *possibleChild);
 983 void folder_synchronise                 (Folder *folder);
 984 gboolean folder_want_synchronise        (Folder *folder);
 985 gboolean folder_subscribe               (const gchar *uri);
 986 gboolean folder_have_mailbox            (void);
 987 gboolean folder_item_free_cache         (FolderItem *item, gboolean force);
 988 void folder_item_change_type            (FolderItem *item,
 989                                          SpecialFolderItemType newtype);
 990 gboolean folder_get_sort_type           (Folder         *folder,
 991                                          FolderSortKey  *sort_key,
 992                                          FolderSortType *sort_type);
 993 void folder_item_synchronise            (FolderItem *item);
 994 void folder_item_discard_cache          (FolderItem *item);
 995 void folder_item_commit_tags(FolderItem *item, MsgInfo *msginfo, GSList *tags_set, GSList *tags_unset);
 996
 997
 998
 999 gint folder_item_search_msgs_local      (Folder                 *folder,
1000                                          FolderItem             *container,
1001                                          MsgNumberList          **msgs,
1002                                          gboolean               *on_server,
1003                                          MatcherList            *predicate,
1004                                          SearchProgressNotify   progress_cb,
1005                                          gpointer               progress_data);
1006
1007 gchar *folder_get_list_path     (void);
1008 gboolean folder_local_name_ok(const gchar *name);
1009
1010 #endif /* __FOLDER_H__ */