1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
4 * Sylpheed -- a GTK+ based, lightweight, and fast e-mail client
5 * Copyright (C) 1999-2003 Hiroyuki Yamamoto
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 2 of the License, or
10 * (at your option) any later version.
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.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
28 typedef struct _Folder Folder;
29 typedef struct _FolderClass FolderClass;
31 typedef struct _FolderItem FolderItem;
32 typedef struct _FolderUpdateData FolderUpdateData;
33 typedef struct _FolderItemUpdateData FolderItemUpdateData;
34 typedef struct _PersistPrefs PersistPrefs;
36 #define FOLDER(obj) ((Folder *)obj)
37 #define FOLDER_CLASS(obj) (FOLDER(obj)->klass)
38 #define FOLDER_TYPE(obj) (FOLDER(obj)->klass->type)
40 #define FOLDER_IS_LOCAL(obj) (FOLDER_TYPE(obj) == F_MH || \
41 FOLDER_TYPE(obj) == F_MBOX || \
42 FOLDER_TYPE(obj) == F_MAILDIR)
44 #define FOLDER_ITEM(obj) ((FolderItem *)obj)
46 #define FOLDER_UPDATE_HOOKLIST "folder_update"
47 #define FOLDER_ITEM_UPDATE_HOOKLIST "folder_item_update"
67 } SpecialFolderItemType;
95 F_MOVE_FAILED_DEST_IS_PARENT = -1,
96 F_MOVE_FAILED_DEST_IS_CHILD = -2,
97 F_MOVE_FAILED_DEST_OUTSIDE_MAILBOX = -3,
99 } FolderItemMoveResult;
103 FOLDER_ADD_FOLDER = 1 << 0,
104 FOLDER_REMOVE_FOLDER = 1 << 1,
105 FOLDER_TREE_CHANGED = 1 << 2,
106 FOLDER_ADD_FOLDERITEM = 1 << 3,
107 FOLDER_REMOVE_FOLDERITEM = 1 << 4
112 F_ITEM_UPDATE_MSGCNT = 1 << 0,
113 F_ITEM_UPDATE_CONTENT = 1 << 1,
114 F_ITEM_UPDATE_ADDMSG = 1 << 2,
115 F_ITEM_UPDATE_REMOVEMSG = 1 << 3,
116 F_ITEM_UPDATE_NAME = 1 << 4
117 } FolderItemUpdateFlags;
119 typedef void (*FolderUIFunc) (Folder *folder,
122 typedef void (*FolderDestroyNotify) (Folder *folder,
125 typedef void (*FolderItemFunc) (FolderItem *item,
129 #include "folder_item_prefs.h"
132 #include "msgcache.h"
134 #include "prefs_account.h"
141 PrefsAccount *account;
150 FolderUIFunc ui_func;
151 gpointer ui_func_data;
163 * A numeric identifier for the FolderClass. Will be removed in the future
167 * A string identifier for the FolderClass. Currently used in folderlist.xml.
168 * Should be lowercase.
172 * A string for the User Interface that identifies the FolderClass to the
173 * user. Can be upper and lowercase unlike the idstr.
177 /* virtual functions */
179 /* Folder funtions */
181 * Create a new \c Folder of this \c FolderClass.
183 * \param name The name of the new Folder
184 * \param path The path of the new Folder
185 * \return The new \c Folder, or \c NULL when creating the \c Folder
188 Folder *(*new_folder) (const gchar *name,
191 * Destroy a \c Folder of this \c FolderClass, frees all resources
192 * allocated by the Folder
194 * \param folder The \c Folder that should be destroyed.
196 void (*destroy_folder) (Folder *folder);
198 * Set the Folder's internal attributes from an \c XMLTag. Also sets the
199 * parameters of the root-FolderItem of the \c Folder. If \c NULL
200 * the default function of the basic \ยข FolderClass is used, so it
201 * must not be \c NULL if one of the parent \c FolderClasses has a \c set_xml
202 * function. In that case the parent \c FolderClass' \c set_xml function
203 * can be used or it has to be called with the \c folder and \c tag by
204 * the implementation.
206 * \param folder The \c Folder which's attributes should be updated
207 * \param tag The \c XMLTag containing the \c XMLAttrs for the attributes
209 void (*set_xml) (Folder *folder,
212 * Get an \c XMLTag for the attributes of the \c Folder and the root-FolderItem
213 * of the \c Folder. If \c NULL the default implementation for the basic
214 * FolderClass will be used, so it must not be \c NULL if one of the
215 * parent \c FolderClasses has it's own implementation for \c get_xml.
216 * In that case the parent FolderClass' \c get_xml function can be
217 * used or the \c XMLTag has to be fetched from the parent's \c get_xml
218 * function and then the \c FolderClass specific attributes can be
221 * \param Folder The \c Folder which's attributes should be set in the
222 * \c XMLTag's \c XMLAttrs
223 * \return XMLTag An \c XMLTag with \c XMLAttrs containing the \c Folder's
226 XMLTag *(*get_xml) (Folder *folder);
228 * Rebuild the folder tree from the folder's data
229 * \todo New implementations of MH and IMAP are actually syncronizing
230 * the tree with the folder by reusing the old \c FolderItems.
231 * Claws still destroys the old tree before calling this function.
233 * \param folder The folder which's tree should be rebuild
234 * \return 0 on success, a negative number otherwise
236 gint (*scan_tree) (Folder *folder);
238 gint (*create_tree) (Folder *folder);
240 /* FolderItem functions */
242 * Create a new \c FolderItem structure for the \c FolderClass.
243 * \c FolderClasses can have their own \c FolderItem structure with
246 * \param folder The \c Folder for that a \c FolderItem should be
248 * \return The new \c FolderItem or NULL in case of an error
250 FolderItem *(*item_new) (Folder *folder);
252 * Destroy a \c FolderItem from this \c FolderClass. The \c FolderClass
253 * has to free all private resources used by the \c FolderItem.
255 * \param folder The \c Folder of the \c FolderItem
256 * \param item The \c FolderItem that should be destroyed
258 void (*item_destroy) (Folder *folder,
261 * Set the \c FolderItem's internal attributes from an \c XMLTag. If
262 * \c NULL the default function of the basic \c FolderClass is used, so it
263 * must not be \c NULL if one of the parent \c FolderClasses has a \c item_set_xml
264 * function. In that case the parent \c FolderClass' \c item_set_xml function
265 * can be used or it has to be called with the \c folder, \c item and \c tag by
266 * the implementation.
268 * \param folder The \c Folder of the \c FolderItem
269 * \param item The \c FolderItems which's attributes should be set
270 * \param tag The \c XMLTag with \c XMLAttrs for the \c FolderItem's
273 void (*item_set_xml) (Folder *folder,
277 * Get an \c XMLTag for the attributes of the \c FolderItem If \c NULL
278 * the default implementation for the basic \c FolderClass will be used,
279 * so it must not be \c NULL if one of the parent \c FolderClasses has
280 * it's own implementation for \c item_get_xml. In that case the parent
281 * FolderClass' \c item_get_xml function can be used or the \c XMLTag
282 * has to be fetched from the parent's \c item_get_xml function and
283 * then the \c FolderClass specific attributes can be added to it.
285 * \param folder The \c Folder of the \c FolderItem
286 * \parem item The \c FolderItem which's attributes should be set in
287 * the \c XMLTag's \c XMLAttrs
288 * \return An \c XMLTag with \c XMLAttrs containing the \c FolderItem's
291 XMLTag *(*item_get_xml) (Folder *folder,
294 * Get a local path for the \c FolderItem where Sylpheed can save
295 * it's cache data. For local directory based folders this can be the
296 * real path. For other folders it can be the local cache directory.
298 * \param folder The \c Folder of the \c FolderItem
299 * \param item The \c FolderItem for that a path should be returned
300 * \return A path for the \c FolderItem
302 gchar *(*item_get_path) (Folder *folder,
305 * Create a new \c FolderItem. The function must use folder_item_append
306 * to add the new \c FolderItem to the folder tree
308 * \param folder The \c Folder in which a new \c FolderItem should be
310 * \param parent \c The parent \c FolderItem for the new \c FolderItem
311 * \parem name The name for the new \c FolderItem
312 * \return The new \c FolderItem
314 FolderItem *(*create_folder) (Folder *folder,
318 * Rename a \c FolderItem
320 * \param folder The \c Folder of the \c FolderItem that should be
322 * \param item The \c FolderItem that should be renamed
323 * \param name The new name of the \c FolderItem
324 * \return 0 on success, a negative number otherwise
326 gint (*rename_folder) (Folder *folder,
330 * Remove a \c FolderItem from the \c Folder
332 * \param folder The \c Folder that contains the \c FolderItem
333 * \param item The \c FolderItem that should be removed
334 * \return 0 on sucess, a negative number otherwise
336 gint (*remove_folder) (Folder *folder,
339 * Close a \c FolderItem. Called when the user deselects a
342 * \attention In Sylpheed-Main operations can only be done on the
343 * \c FolderItem that is opened in the SummaryView. This
344 * \c FolderItem will be closed when you select a new
345 * \c FolderItem in the FolderView. In Claws operations can
346 * be done any time on any folder and you should not expect
347 * that all \c FolderItems get closed after operations
349 * \param folder The \c Folder that contains the \c FolderItem
350 * \param item The \c FolderItem that should be closed
351 * \return 0 on success, a negative number otherwise
353 gint (*close) (Folder *folder,
356 * Get the list of message numbers for the messages in the \c FolderItem
358 * \param folder The \c Folder that contains the \c FolderItem
359 * \param item The \c FolderItem for which the message numbers should
361 * \param list Pointer to a GSList where message numbers have to be
362 * added. Because of the implementation of the GSList that
363 * changes the pointer of the GSList itself when the first
364 * item is added this is a pointer to a pointer to a
365 * GSList structure. Use *item = g_slist_...(*item, ...)
366 * operations to modify the list.
367 * \param old_uids_valid In some \c Folders the old UIDs can be invalid.
368 * Set this pointer to a gboolean to TRUE if the
369 * old UIDs are still valid, otherwise set it to
370 * FALSE and the folder system will discard it's
371 * cache data of the previously know UIDs
372 * \return The number of message numbers add to the list on success,
373 * a negative number otherwise.
375 gint (*get_num_list) (Folder *folder,
378 gboolean *old_uids_valid);
380 * Tell the folder system if a \c FolderItem should be scanned
381 * (cache data syncronized with the folder content) when it is required
382 * because the \c FolderItem's content changed. If NULL the folder
383 * system will not do automatic scanning of \c FolderItems
385 * \param folder The \c Folder that contains the \c FolderItem
386 * \param item The \c FolderItem which's content should be checked
387 * \return TRUE if the \c FolderItem should be scanned, FALSE otherwise
389 gboolean (*scan_required) (Folder *folder,
392 /* Message functions */
394 * Get a MsgInfo for a message in a \c FolderItem
396 * \param folder The \c Folder containing the message
397 * \param item The \c FolderItem containing the message
398 * \param num The message number of the message
399 * \return A pointer to a \c MsgInfo decribing the message or \c
400 * NULL in case of an error
402 MsgInfo *(*get_msginfo) (Folder *folder,
406 * Get \c MsgInfos for a list of message numbers
408 * \param folder The \c Folder containing the message
409 * \param item The \c FolderItem containing the message
410 * \param msgnum_list A list of message numbers for which the
411 * \c MsgInfos should be fetched
412 * \return A list of \c MsgInfos for the messages in the \c msgnum_list
413 * that really exist. Messages that are not found can simply
416 MsgInfoList *(*get_msginfos) (Folder *folder,
418 MsgNumberList *msgnum_list);
420 * Get the filename for a message. This can either be the real message
421 * file for local folders or a temporary file for remote folders.
423 * \param folder The \c Folder containing the message
424 * \param item The \c FolderItem containing the message
425 * \param num The message number of the message
426 * \return A string with the filename of the message file. The returned
427 * string has to be freed with \c g_free(). If message is not
428 * available return NULL.
430 gchar *(*fetch_msg) (Folder *folder,
433 gchar *(*fetch_msg_full) (Folder *folder,
439 * Add a single message file to a folder with the given flags (if
440 * flag handling is supported by the folder)
442 * \param folder The target \c Folder for the message
443 * \param dest the target \c FolderItem for the message
444 * \param file The file that contains the message
445 * \param flags The flags the new message should have in the folder
446 * \return 0 on success, a negative number otherwise
448 gint (*add_msg) (Folder *folder,
453 * Add multiple messages to a \c FolderItem. If NULL the folder
454 * system will add messages with \c add_msg one by one
456 * \param folder The target \c Folder for the messages
457 * \param dest the target \c FolderItem for the messages
458 * \param file_list A list of \c MsgFileInfos which contain the
459 * filenames and flags for the new messages
460 * \param relation Insert tuples of (MsgFileInfo, new message number) to
461 * provide feedback for the folder system which new
462 * message number a \c MsgFileInfo got in dest. Insert
463 * 0 if the new message number is unknown.
465 gint (*add_msgs) (Folder *folder,
468 GRelation *relation);
470 * Copy a message to a FolderItem
472 * \param folder The \c Folder of the destination FolderItem
473 * \param dest The destination \c FolderItem for the message
474 * \param msginfo The message that should be copied
475 * \return The message number the copied message got, 0 if it is
476 * unknown because message numbers are assigned by an external
477 * system and not available after copying or a negative number
478 * if an error occuried
480 gint (*copy_msg) (Folder *folder,
484 * Copy multiple messages to a \c FolderItem. If \c NULL the folder
485 * system will use \c copy_msg to copy messages one by one.
487 * \param folder The \c Folder of the destination FolderItem
488 * \param dest The destination \c FolderItem for the message
489 * \param msglist A list of \c MsgInfos which should be copied to dest
490 * \param relation Insert tuples of (MsgInfo, new message number) to
491 * provide feedback for the folder system which new
492 * message number a \c MsgInfo got in dest. Insert
493 * 0 if the new message number is unknown.
494 * \return 0 on success, a negative number otherwise
496 gint (*copy_msgs) (Folder *folder,
498 MsgInfoList *msglist,
499 GRelation *relation);
501 * Remove a message from a \c FolderItem.
503 * \param folder The \c Folder of the message
504 * \param item The \c FolderItem containing the message
505 * \param num The message number of the message
506 * \return 0 on success, a negative number otherwise
508 gint (*remove_msg) (Folder *folder,
511 gint (*remove_msgs) (Folder *folder,
513 MsgInfoList *msglist,
514 GRelation *relation);
516 * Remove all messages in a \ c FolderItem
518 * \param folder The \c Folder of the \c FolderItem
519 * \param item The \FolderItem which's messages should be deleted
520 * \return 0 on succes, a negative number otherwise
522 gint (*remove_all_msg) (Folder *folder,
525 * Check if a message has been modified by someone else
527 * \param folder The \c Folder of the message
528 * \param item The \c FolderItem containing the message
529 * \param msginfo The \c MsgInfo for the message that should be checked
530 * \return \c TRUE if the message was modified, \c FALSE otherwise
532 gboolean (*is_msg_changed) (Folder *folder,
536 * Update a message's flags in the folder data. If NULL only the
537 * internal flag management will be used. The function has to set
538 * \c msginfo->flags.perm_flags. It does not have to set the flags
539 * that it got as \c newflags. If a flag can not be set in this
540 * \c FolderClass the function can refuse to set it. Flags that are not
541 * supported by the \c FolderClass should not be refused. They will be
542 * managed by the internal cache in this case.
544 * \param folder The \c Folder of the message
545 * \param item The \c FolderItem of the message
546 * \param msginfo The \c MsgInfo for the message which's flags should be
548 * \param newflags The flags the message should get
550 void (*change_flags) (Folder *folder,
553 MsgPermFlags newflags);
555 * Get the flags for a list of messages. Flags that are not supported
556 * by the folder should be preserved. They can be copied from
557 * \c msginfo->flags.perm_flags
559 * \param folder The \c Folder of the messages
560 * \param item The \c FolderItem of the messages
561 * \param msglist The list of \c MsgInfos for which the flags should
563 * \param msgflags A \c GRelation for tuples of (MsgInfo, new permanent
564 * flags for MsgInfo). Add tuples for the messages in msglist
565 * \return 0 on success, a negative number otherwise
567 gint (*get_flags) (Folder *folder,
569 MsgInfoList *msglist,
570 GRelation *msgflags);
572 void (*set_batch) (Folder *folder,
575 void (*synchronise) (FolderItem *item);
580 SpecialFolderItemType stype;
582 gchar *name; /* UTF-8 */
583 gchar *path; /* UTF-8 */
590 gint unreadmarked_msgs;
598 guint no_sub : 1; /* no child allowed? */
599 guint no_select : 1; /* not selectable? */
600 guint collapsed : 1; /* collapsed item */
601 guint thread_collapsed : 1; /* collapsed item */
602 guint threaded : 1; /* threaded folder view */
603 guint hide_read_msgs : 1; /* hide read messages */
604 guint ret_rcpt : 1; /* return receipt */
605 guint search_match : 1;
608 guint opened : 1; /* opened by summary view */
609 FolderItemUpdateFlags update_flags; /* folderview for this folder should be updated */
611 FolderSortKey sort_key;
612 FolderSortType sort_type;
618 PrefsAccount *account;
626 FolderItemPrefs * prefs;
628 /* for faster search of special parents */
629 SpecialFolderItemType parent_stype;
630 gboolean processing_pending;
635 FolderSortKey sort_key;
636 FolderSortType sort_type;
638 guint thread_collapsed : 1;
640 guint hide_read_msgs : 1; /* CLAWS */
641 guint ret_rcpt : 1; /* CLAWS */
644 struct _FolderUpdateData
647 FolderUpdateFlags update_flags;
651 struct _FolderItemUpdateData
654 FolderItemUpdateFlags update_flags;
658 void folder_system_init (void);
659 void folder_register_class (FolderClass *klass);
660 void folder_unregister_class (FolderClass *klass);
661 Folder *folder_new (FolderClass *type,
664 void folder_init (Folder *folder,
667 void folder_destroy (Folder *folder);
669 void folder_set_xml (Folder *folder,
671 XMLTag *folder_get_xml (Folder *folder);
673 FolderItem *folder_item_new (Folder *folder,
676 void folder_item_append (FolderItem *parent,
678 void folder_item_remove (FolderItem *item);
679 void folder_item_remove_children (FolderItem *item);
680 void folder_item_destroy (FolderItem *item);
681 FolderItem *folder_item_parent (FolderItem *item);
683 void folder_item_set_xml (Folder *folder,
686 XMLTag *folder_item_get_xml (Folder *folder,
689 void folder_set_ui_func (Folder *folder,
692 void folder_set_name (Folder *folder,
694 void folder_set_sort (Folder *folder,
696 void folder_tree_destroy (Folder *folder);
698 void folder_add (Folder *folder);
699 void folder_remove (Folder *folder);
701 GList *folder_get_list (void);
702 gint folder_read_list (void);
703 void folder_write_list (void);
704 void folder_scan_tree (Folder *folder, gboolean rebuild);
705 FolderItem *folder_create_folder(FolderItem *parent, const gchar *name);
706 gint folder_item_rename (FolderItem *item, gchar *newname);
707 void folder_update_op_count (void);
708 void folder_func_to_all_folders (FolderItemFunc function,
710 void folder_count_total_msgs(guint *new_msgs, guint *unread_msgs,
711 guint *unreadmarked_msgs, guint *marked_msgs,
713 gchar *folder_get_status (GPtrArray *folders,
716 Folder *folder_find_from_path (const gchar *path);
717 Folder *folder_find_from_name (const gchar *name,
719 FolderItem *folder_find_item_from_path (const gchar *path);
720 FolderClass *folder_get_class_from_string (const gchar *str);
721 FolderItem *folder_find_child_item_by_name (FolderItem *item,
723 gchar *folder_get_identifier (Folder *folder);
724 gchar *folder_item_get_identifier (FolderItem *item);
725 FolderItem *folder_find_item_from_identifier (const gchar *identifier);
726 gchar *folder_item_get_name (FolderItem *item);
728 Folder *folder_get_default_folder (void);
729 FolderItem *folder_get_default_inbox (void);
730 FolderItem *folder_get_default_outbox (void);
731 FolderItem *folder_get_default_draft (void);
732 FolderItem *folder_get_default_queue (void);
733 FolderItem *folder_get_default_trash (void);
734 FolderItem *folder_get_default_processing (void);
735 void folder_set_missing_folders (void);
736 void folder_unref_account_all (PrefsAccount *account);
738 /* return value is locale encoded file name */
739 gchar *folder_item_get_path (FolderItem *item);
741 gint folder_item_open (FolderItem *item);
742 gint folder_item_close (FolderItem *item);
743 gint folder_item_scan (FolderItem *item);
744 gint folder_item_syncronize_flags (FolderItem *item);
745 void folder_item_scan_foreach (GHashTable *table);
746 MsgInfo *folder_item_get_msginfo (FolderItem *item,
748 MsgInfo *folder_item_get_msginfo_by_msgid(FolderItem *item,
750 GSList *folder_item_get_msg_list (FolderItem *item);
751 /* return value is locale charset */
752 gchar *folder_item_fetch_msg (FolderItem *item,
754 gchar *folder_item_fetch_msg_full (FolderItem *item,
756 gboolean get_headers,
758 gint folder_item_fetch_all_msg (FolderItem *item);
759 gint folder_item_add_msg (FolderItem *dest,
762 gboolean remove_source);
763 gint folder_item_add_msgs (FolderItem *dest,
765 gboolean remove_source);
766 gint folder_item_move_to (FolderItem *src,
768 FolderItem **new_item);
769 gint folder_item_move_msg (FolderItem *dest,
771 gint folder_item_move_msgs (FolderItem *dest,
773 gint folder_item_copy_msg (FolderItem *dest,
775 gint folder_item_copy_msgs (FolderItem *dest,
777 gint folder_item_remove_msg (FolderItem *item,
779 gint folder_item_remove_msgs (FolderItem *item,
781 gint folder_item_remove_all_msg (FolderItem *item);
782 void folder_item_change_msg_flags (FolderItem *item,
784 MsgPermFlags newflags);
785 gboolean folder_item_is_msg_changed (FolderItem *item,
787 /* return value is locale chaset */
788 gchar *folder_item_get_cache_file (FolderItem *item);
789 gchar *folder_item_get_mark_file (FolderItem *item);
790 gchar * folder_item_get_identifier (FolderItem * item);
792 GHashTable *folder_persist_prefs_new (Folder *folder);
793 void folder_persist_prefs_free (GHashTable *pptable);
794 const PersistPrefs *folder_get_persist_prefs
795 (GHashTable *pptable, const char *name);
797 void folder_item_restore_persist_prefs (FolderItem *item, GHashTable *pptable);
798 void folder_clean_cache_memory (void);
799 void folder_clean_cache_memory_force (void);
800 void folder_item_write_cache (FolderItem *item);
801 void folder_item_set_default_flags (FolderItem *dest, MsgFlags *flags);
803 void folder_item_apply_processing (FolderItem *item);
805 void folder_item_update (FolderItem *item,
806 FolderItemUpdateFlags update_flags);
807 void folder_item_update_recursive (FolderItem *item,
808 FolderItemUpdateFlags update_flags);
809 void folder_item_update_freeze (void);
810 void folder_item_update_thaw (void);
811 void folder_item_set_batch (FolderItem *item, gboolean batch);
812 gboolean folder_has_parent_of_type (FolderItem *item, SpecialFolderItemType type);
813 void folder_synchronise (Folder *folder);
814 gboolean folder_want_synchronise (Folder *folder);
815 void folder_item_process_open (FolderItem *item,
816 void (*before_proc_func)(gpointer data),
817 void (*after_proc_func)(gpointer data),
819 #endif /* __FOLDER_H__ */