← Back to branch summary

~ubuntu-branches/ubuntu/breezy/evolution-data-server/breezy

« back to all changes in this revision

Viewing changes to camel/camel-folder.c

  • Committer: Bazaar Package Importer
  • Author(s): Daniel Holbach
  • Date: 2005-10-10 11:30:56 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20051010113056-rb4vj4kbs8yxft85
Tags: 1.4.1-0ubuntu3
* debian/patches/camel-imap-store.c.patch:
  - Ubuntu 17465: apply patch from
  http://bugzilla.gnome.org/attachment.cgi?id=53234&action=view
  (additional NULL pointer check)

Show diffs side-by-side

added added

removed removed

Lines of Context:
camel/camel-folder.c
8
8
 * Copyright 1999-2003 Ximian, Inc. (www.ximian.com)
9
9
 *
10
10
 * This program is free software; you can redistribute it and/or
11
 
 * modify it under the terms of version 2 of the GNU General Public
 
11
 * modify it under the terms of version 2 of the GNU Lesser General Public
12
12
 * License as published by the Free Software Foundation.
13
13
 *
14
14
 * This program is distributed in the hope that it will be useful,
15
15
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16
16
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17
 
 * GNU General Public License for more details.
 
17
 * GNU Lesser General Public License for more details.
18
18
 *
19
 
 * You should have received a copy of the GNU General Public License
 
19
 * You should have received a copy of the GNU Lesser General Public License
20
20
 * along with this program; if not, write to the Free Software
21
21
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
22
22
 * USA
221
221
 
222
222
/**
223
223
 * camel_folder_construct:
224
 
 * @folder: folder object to construct
225
 
 * @parent_store: parent store object of the folder
 
224
 * @folder: a #CamelFolder object to construct
 
225
 * @parent_store: parent #CamelStore object of the folder
226
226
 * @full_name: full name of the folder
227
227
 * @name: short name of the folder
228
228
 *
253
253
                     camel_type_to_name (CAMEL_OBJECT_GET_TYPE (folder))));
254
254
}
255
255
 
 
256
 
256
257
/**
257
258
 * camel_folder_sync:
258
 
 * @folder: The folder object
 
259
 * @folder: a #CamelFolder object
259
260
 * @expunge: whether or not to expunge deleted messages
260
 
 * @ex: exception object
 
261
 * @ex: a #CamelException
261
262
 *
262
 
 * Sync changes made to a folder to its backing store, possibly expunging
263
 
 * deleted messages as well.
 
263
 * Sync changes made to a folder to its backing store, possibly
 
264
 * expunging deleted messages as well.
264
265
 **/
265
266
void
266
267
camel_folder_sync (CamelFolder *folder, gboolean expunge, CamelException *ex)
282
283
        /* No op */
283
284
}
284
285
 
 
286
 
285
287
/**
286
288
 * camel_folder_refresh_info:
287
 
 * @folder: The folder object
288
 
 * @ex: exception object
 
289
 * @folder: a #CamelFolder object
 
290
 * @ex: a #CamelException
289
291
 *
290
292
 * Updates a folder's summary to be in sync with its backing store.
291
293
 **/
294
296
{
295
297
        g_return_if_fail (CAMEL_IS_FOLDER (folder));
296
298
 
297
 
        CAMEL_FOLDER_LOCK(folder, lock);
298
 
 
299
299
        CF_CLASS (folder)->refresh_info (folder, ex);
300
 
 
301
 
        CAMEL_FOLDER_UNLOCK(folder, lock);
302
300
}
303
301
 
304
302
static int
447
445
        return folder->name;
448
446
}
449
447
 
 
448
 
450
449
/**
451
450
 * camel_folder_get_name:
452
 
 * @folder: a folder
 
451
 * @folder: a #CamelFolder object
453
452
 *
454
453
 * Get the (short) name of the folder. The fully qualified name
455
 
 * can be obtained with the get_full_name method.
 
454
 * can be obtained with the #camel_folder_get_full_name method.
456
455
 *
457
 
 * Return value: name of the folder
 
456
 * Returns the short name of the folder
458
457
 **/
459
458
const char *
460
 
camel_folder_get_name (CamelFolder * folder)
 
459
camel_folder_get_name (CamelFolder *folder)
461
460
{
462
461
        g_return_val_if_fail (CAMEL_IS_FOLDER (folder), NULL);
463
462
 
471
470
        return folder->full_name;
472
471
}
473
472
 
 
473
 
474
474
/**
475
475
 * camel_folder_get_full_name:
476
 
 * @folder: a folder
477
 
 *
478
 
 * Get the (full) name of the folder.
479
 
 *
480
 
 * Return value: full name of the folder
 
476
 * @folder: a #CamelFolder object
 
477
 *
 
478
 * Get the full name of the folder.
 
479
 *
 
480
 * Returns the full name of the folder
481
481
 **/
482
482
const char *
483
483
camel_folder_get_full_name (CamelFolder *folder)
494
494
        return folder->parent_store;
495
495
}
496
496
 
 
497
 
497
498
/**
498
499
 * camel_folder_get_parent_store:
499
 
 * @folder: folder to get the parent of
 
500
 * @folder: a #CamelFolder object
500
501
 *
501
 
 * Return value: the parent store of the folder.
 
502
 * Returns the parent #CamelStore of the folder
502
503
 **/
503
504
CamelStore *
504
505
camel_folder_get_parent_store (CamelFolder *folder)
519
520
 
520
521
/**
521
522
 * camel_folder_expunge:
522
 
 * @folder: the folder
523
 
 * @ex: a CamelException
 
523
 * @folder: a #CamelFolder object
 
524
 * @ex: a #CamelException
524
525
 *
525
526
 * Delete messages which have been marked as "DELETED"
526
527
 **/
545
546
        return camel_folder_summary_count(folder->summary);
546
547
}
547
548
 
 
549
 
548
550
/**
549
551
 * camel_folder_get_message_count:
550
 
 * @folder: A CamelFolder object
 
552
 * @folder: a #CamelFolder object
551
553
 *
552
 
 * Return value: the number of messages in the folder, or -1 if unknown.
 
554
 * Returns the number of messages in the folder, or %-1 if unknown
553
555
 **/
554
556
int
555
557
camel_folder_get_message_count (CamelFolder *folder)
563
565
        return ret;
564
566
}
565
567
 
 
568
 
566
569
/**
567
 
 * camel_folder_unread_get_message_count:
568
 
 * @folder: A CamelFolder object
569
 
 *
570
 
 * DEPRECATED, use camel_object_get instead.
571
 
 *
572
 
 * Return value: the number of unread messages in the folder, or -1 if unknown.
 
570
 * camel_folder_get_unread_message_count:
 
571
 * @folder: a #CamelFolder object
 
572
 *
 
573
 * DEPRECATED: use #camel_object_get instead.
 
574
 *
 
575
 * Returns the number of unread messages in the folder, or %-1 if
 
576
 * unknown
573
577
 **/
574
578
int
575
579
camel_folder_get_unread_message_count (CamelFolder *folder)
583
587
        return count;
584
588
}
585
589
 
 
590
 
586
591
/**
587
 
 * camel_folder_deleted_get_message_count:
588
 
 * @folder: A CamelFolder object
 
592
 * camel_folder_get_deleted_message_count:
 
593
 * @folder: a #CamelFolder object
589
594
 *
590
 
 * Return value: the number of deleetd messages in the folder, or -1 if unknown.
 
595
 * Returns the number of deleted messages in the folder, or %-1 if
 
596
 * unknown
591
597
 **/
592
598
int
593
599
camel_folder_get_deleted_message_count (CamelFolder *folder)
617
623
 
618
624
}
619
625
 
 
626
 
620
627
/**
621
 
 * camel_folder_append_message: add a message to a folder
622
 
 * @folder: folder object to add the message to
623
 
 * @message: message object
624
 
 * @info: message info with additional flags/etc to set on
 
628
 * camel_folder_append_message:
 
629
 * @folder: a #CamelFolder object
 
630
 * @message: a #CamelMimeMessage object
 
631
 * @info: a #CamelMessageInfo with additional flags/etc to set on
625
632
 * new message, or %NULL
626
633
 * @appended_uid: if non-%NULL, the UID of the appended message will
627
634
 * be returned here, if it is known.
628
 
 * @ex: exception object
 
635
 * @ex: a #CamelException
629
636
 *
630
 
 * Add a message to a folder. Only the flag and tag data from @info
631
 
 * is used. If @info is %NULL, no flags or tags will be set.
 
637
 * Append @message to @folder. Only the flag and tag data from @info
 
638
 * are used. If @info is %NULL, no flags or tags will be set.
632
639
 **/
633
640
void
634
641
camel_folder_append_message (CamelFolder *folder, CamelMimeMessage *message,
651
658
        return folder->permanent_flags;
652
659
}
653
660
 
 
661
 
654
662
/**
655
663
 * camel_folder_get_permanent_flags:
656
 
 * @folder: a CamelFolder
 
664
 * @folder: a #CamelFolder object
657
665
 *
658
 
 * Return value: the set of CamelMessageFlags that can be permanently
659
 
 * stored on a message between sessions. If it includes %CAMEL_FLAG_USER,
660
 
 * then user-defined flags will be remembered.
 
666
 * Returns the set of #CamelMessageFlags that can be permanently
 
667
 * stored on a message between sessions. If it includes
 
668
 * #CAMEL_FLAG_USER, then user-defined flags will be remembered.
661
669
 **/
662
670
guint32
663
671
camel_folder_get_permanent_flags (CamelFolder *folder)
685
693
        return flags;
686
694
}
687
695
 
 
696
 
688
697
/**
689
698
 * camel_folder_get_message_flags:
690
 
 * @folder: a CamelFolder
 
699
 * @folder: a #CamelFolder object
691
700
 * @uid: the UID of a message in @folder
692
701
 *
693
 
 * Deprecated: Use camel_folder_get_message_info instead.
 
702
 * Deprecated: Use #camel_folder_get_message_info instead.
694
703
 *
695
 
 * Return value: the CamelMessageFlags that are set on the indicated
 
704
 * Returns the #CamelMessageFlags that are set on the indicated
696
705
 * message.
697
706
 **/
698
707
guint32
725
734
        return res;
726
735
}
727
736
 
 
737
 
728
738
/**
729
739
 * camel_folder_set_message_flags:
730
 
 * @folder: a CamelFolder
 
740
 * @folder: a #CamelFolder object
731
741
 * @uid: the UID of a message in @folder
732
 
 * @flags: a set of CamelMessageFlag values to set
 
742
 * @flags: a set of #CamelMessageFlag values to set
733
743
 * @set: the mask of values in @flags to use.
734
744
 *
735
745
 * Sets those flags specified by @flags to the values specified by @set
736
746
 * on the indicated message. (This may or may not persist after the
737
 
 * folder or store is closed. See camel_folder_get_permanent_flags().)
 
747
 * folder or store is closed. See #camel_folder_get_permanent_flags)
738
748
 *
739
749
 * E.g. to set the deleted flag and clear the draft flag, use
740
 
 * set_message_flags(folder, uid, CAMEL_MESSAGE_DELETED|CAMEL_MESSAGE_DRAFT, CAMEL_MESSAGE_DELETED);
 
750
 * #camel_folder_set_message_flags(folder, uid, CAMEL_MESSAGE_DELETED|CAMEL_MESSAGE_DRAFT, CAMEL_MESSAGE_DELETED);
741
751
 *
742
 
 * DEPRECATED: Use camel_message_info_set_flags on the message info directly
 
752
 * DEPRECATED: Use #camel_message_info_set_flags on the message info directly
743
753
 * (when it works)
744
754
 *
745
 
 * Return Value: TRUE if the flags were changed, false otherwise.
 
755
 * Returns %TRUE if the flags were changed or %FALSE otherwise
746
756
 **/
747
757
gboolean
748
758
camel_folder_set_message_flags(CamelFolder *folder, const char *uid, guint32 flags, guint32 set)
775
785
        return ret;
776
786
}
777
787
 
 
788
 
778
789
/**
779
790
 * camel_folder_get_message_user_flag:
780
 
 * @folder: a CamelFolder
 
791
 * @folder: a #CamelFolder object
781
792
 * @uid: the UID of a message in @folder
782
793
 * @name: the name of a user flag
783
794
 *
784
 
 * DEPRECATED: Use camel_message_info_get_user_flag on the message info directly
 
795
 * DEPRECATED: Use #camel_message_info_get_user_flag on the message
 
796
 * info directly
785
797
 *
786
 
 * * Return value: whether or not the given user flag is set on the message.
 
798
 * Returns %TRUE if the given user flag is set on the message or
 
799
 * %FALSE otherwise
787
800
 **/
788
801
gboolean
789
802
camel_folder_get_message_user_flag (CamelFolder *folder, const char *uid,
813
826
        camel_message_info_free(info);
814
827
}
815
828
 
 
829
 
816
830
/**
817
831
 * camel_folder_set_message_user_flag:
818
 
 * @folder: a CamelFolder
 
832
 * @folder: a #CamelFolder object
819
833
 * @uid: the UID of a message in @folder
820
834
 * @name: the name of the user flag to set
821
835
 * @value: the value to set it to
822
836
 *
823
 
 * DEPRECATED: Use camel_message_info_set_user_flag on the message info directly (when it works)
 
837
 * DEPRECATED: Use #camel_message_info_set_user_flag on the
 
838
 * #CamelMessageInfo directly (when it works)
824
839
 *
825
840
 * Sets the user flag specified by @name to the value specified by @value
826
841
 * on the indicated message. (This may or may not persist after the
827
 
 * folder or store is closed. See camel_folder_get_permanent_flags().)
 
842
 * folder or store is closed. See #camel_folder_get_permanent_flags)
828
843
 **/
829
844
void
830
845
camel_folder_set_message_user_flag (CamelFolder *folder, const char *uid,
853
868
        return ret;
854
869
}
855
870
 
 
871
 
856
872
/**
857
873
 * camel_folder_get_message_user_tag:
858
 
 * @folder: a CamelFolder
 
874
 * @folder: a #CamelFolder object
859
875
 * @uid: the UID of a message in @folder
860
876
 * @name: the name of a user tag
861
877
 *
862
 
 * DEPRECATED: Use camel_message_info_get_user_tag on the messageinfo directly.
 
878
 * DEPRECATED: Use #camel_message_info_get_user_tag on the
 
879
 * #CamelMessageInfo directly.
863
880
 *
864
 
 * Return value: Returns the value of the user tag.
 
881
 * Returns the value of the user tag
865
882
 **/
866
883
const char *
867
884
camel_folder_get_message_user_tag (CamelFolder *folder, const char *uid,  const char *name)
891
908
        camel_message_info_free(info);
892
909
}
893
910
 
 
911
 
894
912
/**
895
913
 * camel_folder_set_message_user_tag:
896
 
 * @folder: a CamelFolder
 
914
 * @folder: a #CamelFolder object
897
915
 * @uid: the UID of a message in @folder
898
916
 * @name: the name of the user tag to set
899
917
 * @value: the value to set it to
900
918
 *
901
 
 * DEPRECATED: Use camel_message_info_set_user_tag on the messageinfo directly (when it works).
 
919
 * DEPRECATED: Use #camel_message_info_set_user_tag on the
 
920
 * #CamelMessageInfo directly (when it works).
902
921
 *
903
922
 * Sets the user tag specified by @name to the value specified by @value
904
923
 * on the indicated message. (This may or may not persist after the
905
 
 * folder or store is closed. See camel_folder_get_permanent_flags().)
 
924
 * folder or store is closed. See #camel_folder_get_permanent_flags)
906
925
 **/
907
926
void
908
927
camel_folder_set_message_user_tag (CamelFolder *folder, const char *uid, const char *name, const char *value)
920
939
        return camel_folder_summary_uid(folder->summary, uid);
921
940
}
922
941
 
 
942
 
923
943
/**
924
944
 * camel_folder_get_message_info:
925
 
 * @folder: a CamelFolder
 
945
 * @folder: a #CamelFolder object
926
946
 * @uid: the uid of a message
927
947
 *
928
 
 * Retrieve the CamelMessageInfo for the specified @uid.  This return
929
 
 * must be freed using free_message_info().
 
948
 * Retrieve the #CamelMessageInfo for the specified @uid.  This return
 
949
 * must be freed using #camel_folder_free_message_info.
930
950
 *
931
 
 * Return value: the summary information for the indicated message, or NULL
932
 
 * if the uid does not exist.
 
951
 * Returns the summary information for the indicated message, or %NULL
 
952
 * if the uid does not exist
933
953
 **/
934
954
CamelMessageInfo *
935
955
camel_folder_get_message_info (CamelFolder *folder, const char *uid)
952
972
        camel_message_info_free(info);
953
973
}
954
974
 
 
975
 
955
976
/**
956
977
 * camel_folder_free_message_info:
957
 
 * @folder: 
958
 
 * @info: 
 
978
 * @folder: a #CamelFolder object
 
979
 * @info: a #CamelMessageInfo
959
980
 * 
960
 
 * Free (unref) a CamelMessageInfo, previously obtained with get_message_info().
 
981
 * Free (unref) a #CamelMessageInfo, previously obtained with
 
982
 * #camel_folder_get_message_info.
961
983
 **/
962
984
void
963
985
camel_folder_free_message_info(CamelFolder *folder, CamelMessageInfo *info)
976
998
        camel_message_info_ref(info);
977
999
}
978
1000
 
 
1001
 
979
1002
/**
980
1003
 * camel_folder_ref_message_info:
981
 
 * @folder: 
982
 
 * @info: 
 
1004
 * @folder: a #CamelFolder object
 
1005
 * @info: a #CamelMessageInfo
983
1006
 * 
984
 
 * DEPRECATED: Use camel_message_info_ref directly.
 
1007
 * DEPRECATED: Use #camel_message_info_ref directly.
985
1008
 *
986
 
 * Ref a CamelMessageInfo, previously obtained with get_message_info().
 
1009
 * Ref a #CamelMessageInfo, previously obtained with
 
1010
 * #camel_folder_get_message_info.
987
1011
 **/
988
1012
void
989
1013
camel_folder_ref_message_info(CamelFolder *folder, CamelMessageInfo *info)
994
1018
        CF_CLASS (folder)->ref_message_info(folder, info);
995
1019
}
996
1020
 
 
1021
 
997
1022
/* TODO: is this function required anyway? */
 
1023
/**
 
1024
 * camel_folder_has_summary_capability:
 
1025
 * @folder: a #CamelFolder object
 
1026
 *
 
1027
 * Get whether or not the folder has a summary.
 
1028
 *
 
1029
 * Returns %TRUE if a summary is available or %FALSE otherwise
 
1030
 **/
998
1031
gboolean
999
1032
camel_folder_has_summary_capability (CamelFolder *folder)
1000
1033
{
1007
1040
/* UIDs stuff */
1008
1041
 
1009
1042
static CamelMimeMessage *
1010
 
get_message (CamelFolder *folder, const gchar *uid, CamelException *ex)
 
1043
get_message (CamelFolder *folder, const char *uid, CamelException *ex)
1011
1044
{
1012
1045
        w(g_warning ("CamelFolder::get_message not implemented for `%s'",
1013
1046
                     camel_type_to_name (CAMEL_OBJECT_GET_TYPE (folder))));
1015
1048
        return NULL;
1016
1049
}
1017
1050
 
 
1051
 
1018
1052
/**
1019
1053
 * camel_folder_get_message:
1020
 
 * @folder: the folder object
 
1054
 * @folder: a #CamelFolder object
1021
1055
 * @uid: the UID
1022
 
 * @ex: a CamelException
1023
 
 *
1024
 
 * Get a message from its UID in the folder. Messages are cached
1025
 
 * within a folder, that is, asking twice for the same UID returns the
1026
 
 * same message object. (FIXME: is this true?)
1027
 
 *
1028
 
 * Return value: Message corresponding to the UID
 
1056
 * @ex: a #CamelException
 
1057
 *
 
1058
 * Get a message from its UID in the folder.
 
1059
 *
 
1060
 * Returns a #CamelMimeMessage corresponding to @uid
1029
1061
 **/
1030
1062
CamelMimeMessage *
1031
 
camel_folder_get_message (CamelFolder *folder, const gchar *uid, CamelException *ex)
 
1063
camel_folder_get_message (CamelFolder *folder, const char *uid, CamelException *ex)
1032
1064
{
1033
1065
        CamelMimeMessage *ret;
1034
1066
 
1075
1107
        return array;
1076
1108
}
1077
1109
 
 
1110
 
1078
1111
/**
1079
1112
 * camel_folder_get_uids:
1080
 
 * @folder: folder object
 
1113
 * @folder: a #CamelFolder object
1081
1114
 *
1082
1115
 * Get the list of UIDs available in a folder. This routine is useful
1083
1116
 * for finding what messages are available when the folder does not
1084
 
 * support summaries. The returned array shoudl not be modified, and
1085
 
 * must be freed by passing it to camel_folder_free_uids().
 
1117
 * support summaries. The returned array should not be modified, and
 
1118
 * must be freed by passing it to #camel_folder_free_uids.
1086
1119
 *
1087
 
 * Return value: GPtrArray of UIDs corresponding to the messages
1088
 
 * available in the folder.
 
1120
 * Returns a GPtrArray of UIDs corresponding to the messages available
 
1121
 * in the folder
1089
1122
 **/
1090
1123
GPtrArray *
1091
1124
camel_folder_get_uids (CamelFolder *folder)
1109
1142
        g_ptr_array_free(array, TRUE);
1110
1143
}
1111
1144
 
 
1145
 
1112
1146
/**
1113
1147
 * camel_folder_free_uids:
1114
 
 * @folder: folder object
 
1148
 * @folder: a #CamelFolder object
1115
1149
 * @array: the array of uids to free
1116
1150
 *
1117
 
 * Frees the array of UIDs returned by camel_folder_get_uids().
 
1151
 * Frees the array of UIDs returned by #camel_folder_get_uids.
1118
1152
 **/
1119
1153
void
1120
1154
camel_folder_free_uids (CamelFolder *folder, GPtrArray *array)
1132
1166
        return camel_folder_summary_array(folder->summary);
1133
1167
}
1134
1168
 
 
1169
 
1135
1170
/**
1136
1171
 * camel_folder_get_summary:
1137
 
 * @folder: a folder object
 
1172
 * @folder: a #CamelFolder object
1138
1173
 *
1139
1174
 * This returns the summary information for the folder. This array
1140
1175
 * should not be modified, and must be freed with
1141
 
 * camel_folder_free_summary().
 
1176
 * #camel_folder_free_summary.
1142
1177
 *
1143
 
 * Return value: an array of CamelMessageInfo
 
1178
 * Returns an array of #CamelMessageInfo
1144
1179
 **/
1145
1180
GPtrArray *
1146
1181
camel_folder_get_summary (CamelFolder *folder)
1162
1197
        camel_folder_summary_array_free(folder->summary, summary);
1163
1198
}
1164
1199
 
 
1200
 
1165
1201
/**
1166
1202
 * camel_folder_free_summary:
1167
 
 * @folder: folder object
 
1203
 * @folder: a #CamelFolder object
1168
1204
 * @array: the summary array to free
1169
1205
 *
1170
 
 * Frees the summary array returned by camel_folder_get_summary().
 
1206
 * Frees the summary array returned by #camel_folder_get_summary.
1171
1207
 **/
1172
 
void camel_folder_free_summary(CamelFolder * folder, GPtrArray * array)
 
1208
void
 
1209
camel_folder_free_summary(CamelFolder *folder, GPtrArray *array)
1173
1210
{
1174
1211
        g_return_if_fail(CAMEL_IS_FOLDER(folder));
1175
1212
 
1176
1213
        CF_CLASS(folder)->free_summary(folder, array);
1177
1214
}
1178
1215
 
 
1216
 
1179
1217
/**
1180
1218
 * camel_folder_has_search_capability:
1181
 
 * @folder: Folder object
 
1219
 * @folder: a #CamelFolder object
1182
1220
 *
1183
1221
 * Checks if a folder supports searching.
1184
1222
 *
1185
 
 * Return value: %TRUE if the folder supports searching
 
1223
 * Returns %TRUE if the folder supports searching or %FALSE otherwise
1186
1224
 **/
1187
1225
gboolean
1188
1226
camel_folder_has_search_capability (CamelFolder *folder)
1206
1244
        return NULL;
1207
1245
}
1208
1246
 
 
1247
 
1209
1248
/**
1210
1249
 * camel_folder_search_by_expression:
1211
 
 * @folder: Folder object
1212
 
 * @expression: a search expression
1213
 
 * @ex: a CamelException
 
1250
 * @folder: a #CamelFolder object
 
1251
 * @expr: a search expression
 
1252
 * @ex: a #CamelException
1214
1253
 *
1215
1254
 * Searches the folder for messages matching the given search expression.
1216
1255
 *
1217
 
 * Return value: a list of uids of matching messages. The caller must
 
1256
 * Returns a #GPtrArray of uids of matching messages. The caller must
1218
1257
 * free the list and each of the elements when it is done.
1219
1258
 **/
1220
1259
GPtrArray *
1246
1285
        return NULL;
1247
1286
}
1248
1287
 
 
1288
 
1249
1289
/**
1250
1290
 * camel_folder_search_by_uids:
1251
 
 * @folder: 
1252
 
 * @expr: 
 
1291
 * @folder: a #CamelFolder object
 
1292
 * @expr: search expression
1253
1293
 * @uids: array of uid's to match against.
1254
 
 * @ex: 
1255
 
 * 
 
1294
 * @ex: a #CamelException
 
1295
 *
1256
1296
 * Search a subset of uid's for an expression match.
1257
 
 * 
1258
 
 * Return value: 
 
1297
 *
 
1298
 * Returns a #GPtrArray of uids of matching messages. The caller must
 
1299
 * free the list and each of the elements when it is done.
1259
1300
 **/
1260
1301
GPtrArray *
1261
1302
camel_folder_search_by_uids(CamelFolder *folder, const char *expr, GPtrArray *uids, CamelException *ex)
1282
1323
        g_ptr_array_free (result, TRUE);
1283
1324
}
1284
1325
 
 
1326
 
1285
1327
/**
1286
1328
 * camel_folder_search_free:
1287
 
 * @folder: 
1288
 
 * @result: 
 
1329
 * @folder: a #CamelFolder object
 
1330
 * @result: search results to free
1289
1331
 * 
1290
 
 * Free the result of a search.
 
1332
 * Free the result of a search as gotten by #camel_folder_search or
 
1333
 * #camel_folder_search_by_uids.
1291
1334
 **/
1292
1335
void 
1293
1336
camel_folder_search_free (CamelFolder *folder, GPtrArray *result)
1372
1415
        camel_exception_clear(&local);
1373
1416
}
1374
1417
 
 
1418
 
1375
1419
/**
1376
1420
 * camel_folder_transfer_messages_to:
1377
 
 * @source: source folder
 
1421
 * @source: the source #CamelFolder object
1378
1422
 * @uids: message UIDs in @source
1379
 
 * @dest: destination folder
 
1423
 * @dest: the destination #CamelFolder object
1380
1424
 * @transferred_uids: if non-%NULL, the UIDs of the resulting messages
1381
1425
 * in @dest will be stored here, if known.
1382
1426
 * @delete_originals: whether or not to delete the original messages
1383
 
 * @ex: a CamelException
 
1427
 * @ex: a #CamelException
1384
1428
 *
1385
1429
 * This copies or moves messages from one folder to another. If the
1386
1430
 * @source and @dest folders have the same parent_store, this may be
1387
 
 * more efficient than using camel_folder_append_message().
 
1431
 * more efficient than using #camel_folder_append_message.
1388
1432
 **/
1389
1433
void
1390
1434
camel_folder_transfer_messages_to (CamelFolder *source, GPtrArray *uids,
1419
1463
                camel_folder_summary_clear (folder->summary);
1420
1464
}
1421
1465
 
 
1466
 
1422
1467
/**
1423
1468
 * camel_folder_delete:
1424
 
 * @folder: folder
 
1469
 * @folder: a #CamelFolder object
1425
1470
 *
1426
1471
 * Marks a folder object as deleted and performs any required cleanup.
1427
1472
 **/
1450
1495
{
1451
1496
        char *tmp;
1452
1497
 
1453
 
        printf("CamelFolder:rename('%s')\n", new);
 
1498
        d(printf("CamelFolder:rename('%s')\n", new));
1454
1499
 
1455
1500
        g_free(folder->full_name);
1456
1501
        folder->full_name = g_strdup(new);
1459
1504
        folder->name = g_strdup(tmp?tmp+1:new);
1460
1505
}
1461
1506
 
 
1507
 
1462
1508
/**
1463
1509
 * camel_folder_rename:
1464
 
 * @folder: 
1465
 
 * @new: 
 
1510
 * @folder: a #CamelFolder object
 
1511
 * @new: new name for the folder
1466
1512
 * 
1467
1513
 * Mark an active folder object as renamed.
1468
1514
 *
1495
1541
        CAMEL_FOLDER_UNLOCK(folder, change_lock);
1496
1542
}
1497
1543
 
 
1544
 
1498
1545
/**
1499
1546
 * camel_folder_freeze:
1500
 
 * @folder: a folder
 
1547
 * @folder: a #CamelFolder
1501
1548
 *
1502
1549
 * Freezes the folder so that a series of operation can be performed
1503
 
 * without "folder_changed" signals being emitted.
1504
 
 * When the folder is later thawed with camel_folder_thaw(), the
1505
 
 * suppressed signals will be emitted.
 
1550
 * without "folder_changed" signals being emitted.  When the folder is
 
1551
 * later thawed with #camel_folder_thaw, the suppressed signals will
 
1552
 * be emitted.
1506
1553
 **/
1507
1554
void
1508
1555
camel_folder_freeze (CamelFolder * folder)
1541
1588
 
1542
1589
/**
1543
1590
 * camel_folder_thaw:
1544
 
 * @folder: a folder
 
1591
 * @folder: a #CamelFolder object
1545
1592
 *
1546
1593
 * Thaws the folder and emits any pending folder_changed
1547
1594
 * signals.
1561
1608
        return folder->priv->frozen != 0;
1562
1609
}
1563
1610
 
 
1611
 
1564
1612
/**
1565
1613
 * camel_folder_is_frozen:
1566
 
 * @folder: a folder
 
1614
 * @folder: a #CamelFolder object
1567
1615
 *
1568
 
 * Return value: whether or not the folder is frozen.
 
1616
 * Returns whether or not the folder is frozen
1569
1617
 **/
1570
1618
gboolean
1571
1619
camel_folder_is_frozen (CamelFolder *folder)
1733
1781
        }
1734
1782
        CAMEL_FOLDER_UNLOCK(folder, change_lock);
1735
1783
 
1736
 
        if (changed->uid_changed->len) {
 
1784
        if (session->junk_plugin && changed->uid_changed->len) {
1737
1785
                guint32 flags;
1738
1786
 
1739
1787
                for (i = 0; i < changed->uid_changed->len; i ++) {
1748
1796
                                                notjunk = g_ptr_array_new();
1749
1797
                                        g_ptr_array_add (notjunk, g_strdup (changed->uid_changed->pdata [i]));
1750
1798
                                }
1751
 
                                /* reset junk learn flag so that we don't process it again */
 
1799
                                /* reset junk learn flag so that we don't process it again*/ 
1752
1800
                                camel_folder_set_message_flags (folder, changed->uid_changed->pdata [i], CAMEL_MESSAGE_JUNK_LEARN, 0);
1753
1801
                        }
1754
1802
                }
1787
1835
        return TRUE;
1788
1836
}
1789
1837
 
 
1838
 
1790
1839
/**
1791
1840
 * camel_folder_free_nop:
1792
 
 * @folder: a folder
1793
 
 * @array: an array of uids or CamelMessageInfo
 
1841
 * @folder: a #CamelFolder object
 
1842
 * @array: an array of uids or #CamelMessageInfo
1794
1843
 *
1795
 
 * "Frees" the provided array by doing nothing. Used by CamelFolder
 
1844
 * "Frees" the provided array by doing nothing. Used by #CamelFolder
1796
1845
 * subclasses as an implementation for free_uids, or free_summary when
1797
1846
 * the returned array is "static" information and should not be freed.
1798
1847
 **/
1802
1851
        ;
1803
1852
}
1804
1853
 
 
1854
 
1805
1855
/**
1806
1856
 * camel_folder_free_shallow:
1807
 
 * @folder: a folder
1808
 
 * @array: an array of uids or CamelMessageInfo
 
1857
 * @folder: a #CamelFolder object
 
1858
 * @array: an array of uids or #CamelMessageInfo
1809
1859
 *
1810
 
 * Frees the provided array but not its contents. Used by CamelFolder
 
1860
 * Frees the provided array but not its contents. Used by #CamelFolder
1811
1861
 * subclasses as an implementation for free_uids or free_summary when
1812
1862
 * the returned array needs to be freed but its contents come from
1813
1863
 * "static" information.
1818
1868
        g_ptr_array_free (array, TRUE);
1819
1869
}
1820
1870
 
 
1871
 
1821
1872
/**
1822
1873
 * camel_folder_free_deep:
1823
 
 * @folder: a folder
 
1874
 * @folder: a #CamelFolder object
1824
1875
 * @array: an array of uids
1825
1876
 *
1826
 
 * Frees the provided array and its contents. Used by CamelFolder
 
1877
 * Frees the provided array and its contents. Used by #CamelFolder
1827
1878
 * subclasses as an implementation for free_uids when the provided
1828
1879
 * information was created explicitly by the corresponding get_ call.
1829
1880
 **/
1843
1894
        struct _EMemPool *uid_pool;     /* pool used to store copies of uid strings */
1844
1895
};
1845
1896
 
 
1897
 
1846
1898
/**
1847
1899
 * camel_folder_change_info_new:
1848
 
 * @void: 
1849
1900
 * 
1850
1901
 * Create a new folder change info structure.
1851
1902
 *
1852
1903
 * Change info structures are not MT-SAFE and must be
1853
1904
 * locked for exclusive access externally.
1854
 
 * 
1855
 
 * Return value: 
 
1905
 *
 
1906
 * Returns a new #CamelFolderChangeInfo
1856
1907
 **/
1857
1908
CamelFolderChangeInfo *
1858
1909
camel_folder_change_info_new(void)
1872
1923
        return info;
1873
1924
}
1874
1925
 
 
1926
 
1875
1927
/**
1876
1928
 * camel_folder_change_info_add_source:
1877
 
 * @info: 
1878
 
 * @uid: 
 
1929
 * @info: a #CamelFolderChangeInfo
 
1930
 * @uid: a uid
1879
1931
 * 
1880
1932
 * Add a source uid for generating a changeset.
1881
1933
 **/
1895
1947
                g_hash_table_insert(p->uid_source, e_mempool_strdup(p->uid_pool, uid), GINT_TO_POINTER (1));
1896
1948
}
1897
1949
 
 
1950
 
1898
1951
/**
1899
1952
 * camel_folder_change_info_add_source_list:
1900
 
 * @info: 
1901
 
 * @list: 
 
1953
 * @info: a #CamelFolderChangeInfo
 
1954
 * @list: a list of uids
1902
1955
 * 
1903
1956
 * Add a list of source uid's for generating a changeset.
1904
1957
 **/
1924
1977
        }
1925
1978
}
1926
1979
 
 
1980
 
1927
1981
/**
1928
1982
 * camel_folder_change_info_add_update:
1929
 
 * @info: 
1930
 
 * @uid: 
 
1983
 * @info: a #CamelFolderChangeInfo
 
1984
 * @uid: a uid
1931
1985
 * 
1932
1986
 * Add a uid from the updated list, used to generate a changeset diff.
1933
1987
 **/
1954
2008
        }
1955
2009
}
1956
2010
 
 
2011
 
1957
2012
/**
1958
2013
 * camel_folder_change_info_add_update_list:
1959
 
 * @info: 
1960
 
 * @list: 
 
2014
 * @info: a #CamelFolderChangeInfo
 
2015
 * @list: a list of uids
1961
2016
 * 
1962
2017
 * Add a list of uid's from the updated list.
1963
2018
 **/
1995
2050
        g_hash_table_insert(p->uid_stored, key, info->uid_removed);
1996
2051
}
1997
2052
 
 
2053
 
1998
2054
/**
1999
2055
 * camel_folder_change_info_build_diff:
2000
 
 * @info: 
 
2056
 * @info: a #CamelFolderChangeInfo
2001
2057
 * 
2002
 
 * Compare the source uid set to the updated uid set and generate the differences
2003
 
 * into the added and removed lists.
 
2058
 * Compare the source uid set to the updated uid set and generate the
 
2059
 * differences into the added and removed lists.
2004
2060
 **/
2005
2061
void
2006
2062
camel_folder_change_info_build_diff(CamelFolderChangeInfo *info)
2027
2083
                add(info, source->pdata[i]);
2028
2084
}
2029
2085
 
 
2086
 
2030
2087
/**
2031
2088
 * camel_folder_change_info_cat:
2032
 
 * @info: 
2033
 
 * @source: 
 
2089
 * @info: a #CamelFolderChangeInfo to append to
 
2090
 * @src: a #CamelFolderChangeInfo to append from
2034
2091
 * 
2035
 
 * Concatenate one change info onto antoher.  Can be used to copy
2036
 
 * them too.
 
2092
 * Concatenate one change info onto antoher.  Can be used to copy them
 
2093
 * too.
2037
2094
 **/
2038
2095
void
2039
2096
camel_folder_change_info_cat(CamelFolderChangeInfo *info, CamelFolderChangeInfo *source)
2049
2106
 
2050
2107
/**
2051
2108
 * camel_folder_change_info_add_uid:
2052
 
 * @info: 
2053
 
 * @uid: 
 
2109
 * @info: a #CamelFolderChangeInfo
 
2110
 * @uid: a uid
2054
2111
 * 
2055
2112
 * Add a new uid to the changeinfo.
2056
2113
 **/
2081
2138
        g_hash_table_insert(p->uid_stored, olduid, info->uid_added);
2082
2139
}
2083
2140
 
 
2141
 
2084
2142
/**
2085
2143
 * camel_folder_change_info_remove_uid:
2086
 
 * @info: 
2087
 
 * @uid: 
 
2144
 * @info: a #CamelFolderChangeInfo
 
2145
 * @uid: a uid
2088
2146
 * 
2089
2147
 * Add a uid to the removed uid list.
2090
2148
 **/
2114
2172
        g_hash_table_insert(p->uid_stored, olduid, info->uid_removed);
2115
2173
}
2116
2174
 
 
2175
 
2117
2176
/**
2118
2177
 * camel_folder_change_info_change_uid:
2119
 
 * @info: 
2120
 
 * @uid: 
 
2178
 * @info: a #CamelFolderChangeInfo
 
2179
 * @uid: a uid
2121
2180
 * 
2122
2181
 * Add a uid to the changed uid list.
2123
2182
 **/
2142
2201
        g_hash_table_insert(p->uid_stored, olduid, info->uid_changed);
2143
2202
}
2144
2203
 
 
2204
 
 
2205
/**
 
2206
 * camel_folder_change_info_recent_uid:
 
2207
 * @info: a #CamelFolderChangeInfo
 
2208
 * @uid: a uid
 
2209
 *
 
2210
 * Add a recent uid to the changedinfo.
 
2211
 **/
2145
2212
void
2146
2213
camel_folder_change_info_recent_uid(CamelFolderChangeInfo *info, const char *uid)
2147
2214
{
2162
2229
 
2163
2230
/**
2164
2231
 * camel_folder_change_info_changed:
2165
 
 * @info: 
2166
 
 * 
2167
 
 * Return true if the changeset contains any changes.
2168
 
 *
2169
 
 * Return Value:
 
2232
 * @info: a #CamelFolderChangeInfo
 
2233
 *
 
2234
 * Gets whether or not there have been any changes.
 
2235
 *
 
2236
 * Returns %TRUE if the changeset contains any changes or %FALSE
 
2237
 * otherwise
2170
2238
 **/
2171
2239
gboolean
2172
2240
camel_folder_change_info_changed(CamelFolderChangeInfo *info)
2176
2244
        return (info->uid_added->len || info->uid_removed->len || info->uid_changed->len || info->uid_recent->len);
2177
2245
}
2178
2246
 
 
2247
 
2179
2248
/**
2180
2249
 * camel_folder_change_info_clear:
2181
 
 * @info: 
 
2250
 * @info: a #CamelFolderChangeInfo
2182
2251
 * 
2183
 
 * Empty out the change info; called after changes have been processed.
 
2252
 * Empty out the change info; called after changes have been
 
2253
 * processed.
2184
2254
 **/
2185
2255
void
2186
2256
camel_folder_change_info_clear(CamelFolderChangeInfo *info)
2204
2274
        e_mempool_flush(p->uid_pool, TRUE);
2205
2275
}
2206
2276
 
 
2277
 
2207
2278
/**
2208
2279
 * camel_folder_change_info_free:
2209
 
 * @info: 
 
2280
 * @info: a #CamelFolderChangeInfo
2210
2281
 * 
2211
2282
 * Free memory associated with the folder change info lists.
2212
2283
 **/