camel/camel-folder.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*-
   2  *
   3  * camel-folder.h: Abstract class for an email folder
   4  *
   5  * Authors: Bertrand Guiheneuf <bertrand@helixcode.com>
   6  *          Michael Zucchi <notzed@ximian.com>
   7  *
   8  * Copyright 1999, 2000 Ximian, Inc. (www.ximian.com)
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of version 2 of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  22  * USA
  23  */
  24
  25 #ifndef CAMEL_FOLDER_H
  26 #define CAMEL_FOLDER_H 1
  27
  28 #include <glib.h>
  29 #include <camel/camel-object.h>
  30 #include <camel/camel-folder-summary.h>
  31
  32 #define CAMEL_FOLDER_TYPE     (camel_folder_get_type ())
  33 #define CAMEL_FOLDER(obj)     (CAMEL_CHECK_CAST((obj), CAMEL_FOLDER_TYPE, CamelFolder))
  34 #define CAMEL_FOLDER_CLASS(k) (CAMEL_CHECK_CLASS_CAST ((k), CAMEL_FOLDER_TYPE, CamelFolderClass))
  35 #define CAMEL_IS_FOLDER(o)    (CAMEL_CHECK_TYPE((o), CAMEL_FOLDER_TYPE))
  36
  37 G_BEGIN_DECLS
  38
  39 typedef struct _CamelFolderChangeInfo CamelFolderChangeInfo;
  40
  41 enum {
  42         CAMEL_FOLDER_ARG_FIRST = CAMEL_ARG_FIRST + 0x1000,
  43         CAMEL_FOLDER_ARG_NAME = CAMEL_FOLDER_ARG_FIRST,
  44         CAMEL_FOLDER_ARG_FULL_NAME,
  45         CAMEL_FOLDER_ARG_STORE,
  46         CAMEL_FOLDER_ARG_PERMANENTFLAGS,
  47         CAMEL_FOLDER_ARG_TOTAL,
  48         CAMEL_FOLDER_ARG_UNREAD, /* unread messages */
  49         CAMEL_FOLDER_ARG_DELETED, /* deleted messages */
  50         CAMEL_FOLDER_ARG_JUNKED, /* junked messages */
  51         CAMEL_FOLDER_ARG_VISIBLE, /* visible !(deleted or junked) */
  52         CAMEL_FOLDER_ARG_UID_ARRAY,
  53         CAMEL_FOLDER_ARG_INFO_ARRAY,
  54         CAMEL_FOLDER_ARG_PROPERTIES,
  55         CAMEL_FOLDER_ARG_LAST = CAMEL_ARG_FIRST + 0x2000,
  56 };
  57
  58 enum {
  59         CAMEL_FOLDER_NAME = CAMEL_FOLDER_ARG_NAME | CAMEL_ARG_STR,
  60         CAMEL_FOLDER_FULL_NAME = CAMEL_FOLDER_ARG_FULL_NAME | CAMEL_ARG_STR,
  61         CAMEL_FOLDER_STORE = CAMEL_FOLDER_ARG_STORE | CAMEL_ARG_OBJ,
  62         CAMEL_FOLDER_PERMANENTFLAGS = CAMEL_FOLDER_ARG_PERMANENTFLAGS | CAMEL_ARG_INT,
  63         CAMEL_FOLDER_TOTAL = CAMEL_FOLDER_ARG_TOTAL | CAMEL_ARG_INT,
  64         CAMEL_FOLDER_UNREAD = CAMEL_FOLDER_ARG_UNREAD | CAMEL_ARG_INT,
  65         CAMEL_FOLDER_DELETED = CAMEL_FOLDER_ARG_DELETED | CAMEL_ARG_INT,
  66         CAMEL_FOLDER_JUNKED = CAMEL_FOLDER_ARG_JUNKED | CAMEL_ARG_INT,
  67         CAMEL_FOLDER_VISIBLE = CAMEL_FOLDER_ARG_VISIBLE | CAMEL_ARG_INT,
  68
  69         CAMEL_FOLDER_UID_ARRAY = CAMEL_FOLDER_ARG_UID_ARRAY | CAMEL_ARG_PTR,
  70         CAMEL_FOLDER_INFO_ARRAY = CAMEL_FOLDER_ARG_INFO_ARRAY | CAMEL_ARG_PTR,
  71
  72         /* GSList of settable folder properties */
  73         CAMEL_FOLDER_PROPERTIES = CAMEL_FOLDER_ARG_PROPERTIES | CAMEL_ARG_PTR,
  74 };
  75
  76 struct _CamelFolderChangeInfo {
  77         GPtrArray *uid_added;
  78         GPtrArray *uid_removed;
  79         GPtrArray *uid_changed;
  80         GPtrArray *uid_recent;
  81
  82         struct _CamelFolderChangeInfoPrivate *priv;
  83 };
  84
  85 struct _CamelFolder {
  86         CamelObject parent_object;
  87
  88         struct _CamelFolderPrivate *priv;
  89
  90         /* get these via the :get() method, they might not be set otherwise */
  91         char *name;
  92         char *full_name;
  93         char *description;
  94
  95         CamelStore *parent_store;
  96         CamelFolderSummary *summary;
  97
  98         guint32 folder_flags;
  99         guint32 permanent_flags;
 100 };
 101
 102 #define CAMEL_FOLDER_HAS_SUMMARY_CAPABILITY (1<<0)
 103 #define CAMEL_FOLDER_HAS_SEARCH_CAPABILITY  (1<<1)
 104 #define CAMEL_FOLDER_FILTER_RECENT          (1<<2)
 105 #define CAMEL_FOLDER_HAS_BEEN_DELETED       (1<<3)
 106 #define CAMEL_FOLDER_IS_TRASH               (1<<4)
 107 #define CAMEL_FOLDER_IS_JUNK                (1<<5)
 108 #define CAMEL_FOLDER_FILTER_JUNK            (1<<6)
 109
 110 typedef struct {
 111         CamelObjectClass parent_class;
 112
 113         /* Virtual methods */
 114         void   (*refresh_info) (CamelFolder *folder, CamelException *ex);
 115
 116         void   (*sync) (CamelFolder *folder, gboolean expunge,
 117                         CamelException *ex);
 118
 119         const char *  (*get_name)  (CamelFolder *folder);
 120         const char *  (*get_full_name)   (CamelFolder *folder);
 121
 122         CamelStore *  (*get_parent_store) (CamelFolder *folder);
 123
 124         void (*expunge)  (CamelFolder *folder,
 125                           CamelException *ex);
 126
 127         int   (*get_message_count)   (CamelFolder *folder);
 128
 129         void (*append_message)  (CamelFolder *folder,
 130                                  CamelMimeMessage *message,
 131                                  const CamelMessageInfo *info,
 132                                  char **appended_uid,
 133                                  CamelException *ex);
 134
 135         guint32 (*get_permanent_flags) (CamelFolder *folder);
 136         guint32 (*get_message_flags)   (CamelFolder *folder,
 137                                         const char *uid);
 138         gboolean (*set_message_flags)   (CamelFolder *folder,
 139                                          const char *uid,
 140                                          guint32 flags, guint32 set);
 141
 142         gboolean (*get_message_user_flag) (CamelFolder *folder,
 143                                            const char *uid,
 144                                            const char *name);
 145         void     (*set_message_user_flag) (CamelFolder *folder,
 146                                            const char *uid,
 147                                            const char *name,
 148                                            gboolean value);
 149
 150         const char * (*get_message_user_tag) (CamelFolder *folder,
 151                                               const char *uid,
 152                                               const char *name);
 153         void     (*set_message_user_tag) (CamelFolder *folder,
 154                                           const char *uid,
 155                                           const char *name,
 156                                           const char *value);
 157
 158         CamelMimeMessage * (*get_message)  (CamelFolder *folder,
 159                                             const char *uid,
 160                                             CamelException *ex);
 161
 162         GPtrArray * (*get_uids)       (CamelFolder *folder);
 163         void (*free_uids)             (CamelFolder *folder,
 164                                        GPtrArray *array);
 165
 166         GPtrArray * (*get_summary)    (CamelFolder *folder);
 167         void (*free_summary)          (CamelFolder *folder,
 168                                        GPtrArray *summary);
 169
 170         gboolean (*has_search_capability) (CamelFolder *folder);
 171
 172         GPtrArray * (*search_by_expression) (CamelFolder *, const char *, CamelException *);
 173         GPtrArray * (*search_by_uids) (CamelFolder *, const char *, GPtrArray *uids, CamelException *);
 174
 175         void (*search_free) (CamelFolder *folder, GPtrArray *result);
 176
 177         CamelMessageInfo * (*get_message_info) (CamelFolder *, const char *uid);
 178         void (*ref_message_info) (CamelFolder *, CamelMessageInfo *);
 179         void (*free_message_info) (CamelFolder *, CamelMessageInfo *);
 180
 181         void (*transfer_messages_to) (CamelFolder *source,
 182                                       GPtrArray *uids,
 183                                       CamelFolder *destination,
 184                                       GPtrArray **transferred_uids,
 185                                       gboolean delete_originals,
 186                                       CamelException *ex);
 187
 188         void (*delete)           (CamelFolder *folder);
 189         void (*rename)           (CamelFolder *folder, const char *newname);
 190
 191         void     (*freeze)    (CamelFolder *folder);
 192         void     (*thaw)      (CamelFolder *folder);
 193         gboolean (*is_frozen) (CamelFolder *folder);
 194 } CamelFolderClass;
 195
 196 /* Standard Camel function */
 197 CamelType camel_folder_get_type (void);
 198
 199
 200 /* public methods */
 201 void               camel_folder_construct              (CamelFolder *folder,
 202                                                         CamelStore *parent_store,
 203                                                         const char *full_name,
 204                                                         const char *name);
 205
 206 void               camel_folder_refresh_info           (CamelFolder *folder,
 207                                                         CamelException *ex);
 208 void               camel_folder_sync                   (CamelFolder *folder,
 209                                                         gboolean expunge,
 210                                                         CamelException *ex);
 211
 212 CamelStore *       camel_folder_get_parent_store       (CamelFolder *folder);
 213
 214
 215 /* delete operations */
 216 void               camel_folder_expunge                (CamelFolder *folder,
 217                                                         CamelException *ex);
 218
 219
 220 /* folder name operations */
 221 const char *      camel_folder_get_name                (CamelFolder *folder);
 222 const char *      camel_folder_get_full_name           (CamelFolder *folder);
 223
 224
 225 /* various properties accessors */
 226 guint32            camel_folder_get_permanent_flags    (CamelFolder *folder);
 227
 228 #ifndef CAMEL_DISABLE_DEPRECATED
 229 guint32            camel_folder_get_message_flags      (CamelFolder *folder,
 230                                                         const char *uid);
 231
 232 gboolean           camel_folder_set_message_flags      (CamelFolder *folder,
 233                                                         const char *uid,
 234                                                         guint32 flags,
 235                                                         guint32 set);
 236
 237 gboolean           camel_folder_get_message_user_flag  (CamelFolder *folder,
 238                                                         const char *uid,
 239                                                         const char *name);
 240
 241 void               camel_folder_set_message_user_flag  (CamelFolder *folder,
 242                                                         const char *uid,
 243                                                         const char *name,
 244                                                         gboolean value);
 245
 246 const char *       camel_folder_get_message_user_tag  (CamelFolder *folder,
 247                                                        const char *uid,
 248                                                        const char *name);
 249
 250 void               camel_folder_set_message_user_tag  (CamelFolder *folder,
 251                                                        const char *uid,
 252                                                        const char *name,
 253                                                        const char *value);
 254 #endif
 255
 256
 257
 258 /* message manipulation */
 259 void               camel_folder_append_message         (CamelFolder *folder,
 260                                                         CamelMimeMessage *message,
 261                                                         const CamelMessageInfo *info,
 262                                                         char **appended_uid,
 263                                                         CamelException *ex);
 264
 265
 266 /* summary related operations */
 267 gboolean           camel_folder_has_summary_capability (CamelFolder *folder);
 268
 269
 270 int                camel_folder_get_message_count     (CamelFolder *folder);
 271
 272 #ifndef CAMEL_DISABLE_DEPRECATED
 273 int                camel_folder_get_unread_message_count (CamelFolder *folder);
 274 #endif
 275
 276 int                camel_folder_get_deleted_message_count (CamelFolder *folder);
 277
 278 GPtrArray *        camel_folder_get_summary           (CamelFolder *folder);
 279 void               camel_folder_free_summary          (CamelFolder *folder,
 280                                                        GPtrArray *array);
 281
 282 /* uid based access operations */
 283 CamelMimeMessage * camel_folder_get_message           (CamelFolder *folder,
 284                                                        const char *uid,
 285                                                        CamelException *ex);
 286 #define camel_folder_delete_message(folder, uid) \
 287         camel_folder_set_message_flags (folder, uid, CAMEL_MESSAGE_DELETED|CAMEL_MESSAGE_SEEN, CAMEL_MESSAGE_DELETED|CAMEL_MESSAGE_SEEN)
 288
 289 GPtrArray *        camel_folder_get_uids              (CamelFolder *folder);
 290 void               camel_folder_free_uids             (CamelFolder *folder,
 291                                                        GPtrArray *array);
 292
 293 /* search api */
 294 gboolean           camel_folder_has_search_capability (CamelFolder *folder);
 295 GPtrArray *        camel_folder_search_by_expression  (CamelFolder *folder, const char *expr, CamelException *ex);
 296 GPtrArray *        camel_folder_search_by_uids        (CamelFolder *folder, const char *expr, GPtrArray *uids, CamelException *ex);
 297 void               camel_folder_search_free           (CamelFolder *folder, GPtrArray *result);
 298
 299 /* summary info */
 300 CamelMessageInfo *camel_folder_get_message_info         (CamelFolder *folder, const char *uid);
 301 void              camel_folder_free_message_info        (CamelFolder *folder, CamelMessageInfo *info);
 302 #ifndef CAMEL_DISABLE_DEPRECATED
 303 void              camel_folder_ref_message_info         (CamelFolder *folder, CamelMessageInfo *info);
 304 #endif
 305
 306 void               camel_folder_transfer_messages_to   (CamelFolder *source,
 307                                                         GPtrArray *uids,
 308                                                         CamelFolder *dest,
 309                                                         GPtrArray **transferred_uids,
 310                                                         gboolean delete_originals,
 311                                                         CamelException *ex);
 312
 313 void               camel_folder_delete                 (CamelFolder *folder);
 314 void               camel_folder_rename                 (CamelFolder *folder, const char *new);
 315
 316 /* stop/restart getting events */
 317 void               camel_folder_freeze                (CamelFolder *folder);
 318 void               camel_folder_thaw                  (CamelFolder *folder);
 319 gboolean           camel_folder_is_frozen             (CamelFolder *folder);
 320
 321 /* For use by subclasses (for free_{uids,summary,subfolder_names}) */
 322 void camel_folder_free_nop     (CamelFolder *folder, GPtrArray *array);
 323 void camel_folder_free_shallow (CamelFolder *folder, GPtrArray *array);
 324 void camel_folder_free_deep    (CamelFolder *folder, GPtrArray *array);
 325
 326 /* update functions for change info */
 327 CamelFolderChangeInfo * camel_folder_change_info_new            (void);
 328 void                    camel_folder_change_info_clear          (CamelFolderChangeInfo *info);
 329 void                    camel_folder_change_info_free           (CamelFolderChangeInfo *info);
 330 gboolean                camel_folder_change_info_changed        (CamelFolderChangeInfo *info);
 331
 332 /* for building diff's automatically */
 333 void                    camel_folder_change_info_add_source     (CamelFolderChangeInfo *info, const char *uid);
 334 void                    camel_folder_change_info_add_source_list(CamelFolderChangeInfo *info, const GPtrArray *list);
 335 void                    camel_folder_change_info_add_update     (CamelFolderChangeInfo *info, const char *uid);
 336 void                    camel_folder_change_info_add_update_list(CamelFolderChangeInfo *info, const GPtrArray *list);
 337 void                    camel_folder_change_info_build_diff     (CamelFolderChangeInfo *info);
 338
 339 /* for manipulating diff's directly */
 340 void                    camel_folder_change_info_cat            (CamelFolderChangeInfo *info, CamelFolderChangeInfo *src);
 341 void                    camel_folder_change_info_add_uid        (CamelFolderChangeInfo *info, const char *uid);
 342 void                    camel_folder_change_info_remove_uid     (CamelFolderChangeInfo *info, const char *uid);
 343 void                    camel_folder_change_info_change_uid     (CamelFolderChangeInfo *info, const char *uid);
 344 void                    camel_folder_change_info_recent_uid     (CamelFolderChangeInfo *info, const char *uid);
 345
 346 G_END_DECLS
 347
 348 #endif /* CAMEL_FOLDER_H */