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