![]() |
![]() |
![]() |
Camel Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <camel/camel.h> struct CamelIMAPXMailbox; CamelIMAPXMailbox * camel_imapx_mailbox_new (CamelIMAPXListResponse *response
,CamelIMAPXNamespace *namespace_
); CamelIMAPXMailbox * camel_imapx_mailbox_clone (CamelIMAPXMailbox *mailbox
,const gchar *new_mailbox_name
); gboolean camel_imapx_mailbox_exists (CamelIMAPXMailbox *mailbox
); gint camel_imapx_mailbox_compare (CamelIMAPXMailbox *mailbox_a
,CamelIMAPXMailbox *mailbox_b
); gboolean camel_imapx_mailbox_matches (CamelIMAPXMailbox *mailbox
,const gchar *pattern
); const gchar * camel_imapx_mailbox_get_name (CamelIMAPXMailbox *mailbox
); gchar camel_imapx_mailbox_get_separator (CamelIMAPXMailbox *mailbox
); CamelIMAPXNamespace * camel_imapx_mailbox_get_namespace (CamelIMAPXMailbox *mailbox
); guint32 camel_imapx_mailbox_get_messages (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_messages (CamelIMAPXMailbox *mailbox
,guint32 messages
); guint32 camel_imapx_mailbox_get_recent (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_recent (CamelIMAPXMailbox *mailbox
,guint32 recent
); guint32 camel_imapx_mailbox_get_unseen (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_unseen (CamelIMAPXMailbox *mailbox
,guint32 unseen
); guint32 camel_imapx_mailbox_get_uidnext (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_uidnext (CamelIMAPXMailbox *mailbox
,guint32 uidnext
); guint32 camel_imapx_mailbox_get_uidvalidity (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_uidvalidity (CamelIMAPXMailbox *mailbox
,guint32 uidvalidity
); guint64 camel_imapx_mailbox_get_highestmodseq (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_highestmodseq (CamelIMAPXMailbox *mailbox
,guint64 highestmodseq
); gchar ** camel_imapx_mailbox_dup_quota_roots (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_set_quota_roots (CamelIMAPXMailbox *mailbox
,const gchar **quota_roots
); GSequence * camel_imapx_mailbox_copy_message_map (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_take_message_map (CamelIMAPXMailbox *mailbox
,GSequence *message_map
); gboolean camel_imapx_mailbox_get_msn_for_uid (CamelIMAPXMailbox *mailbox
,guint32 uid
,guint32 *out_msn
); gboolean camel_imapx_mailbox_get_uid_for_msn (CamelIMAPXMailbox *mailbox
,guint32 msn
,guint32 *out_uid
); void camel_imapx_mailbox_deleted (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_subscribed (CamelIMAPXMailbox *mailbox
); void camel_imapx_mailbox_unsubscribed (CamelIMAPXMailbox *mailbox
); gboolean camel_imapx_mailbox_has_attribute (CamelIMAPXMailbox *mailbox
,const gchar *attribute
); void camel_imapx_mailbox_handle_list_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXListResponse *response
); void camel_imapx_mailbox_handle_lsub_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXListResponse *response
); void camel_imapx_mailbox_handle_status_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXStatusResponse *response
);
CamelIMAPXMailbox models the current state of an IMAP mailbox as accumulated from untagged IMAP server responses in the current session.
In particular, a CamelIMAPXMailbox should not be populated with locally cached information from the previous session. This is why instantiation requires a CamelIMAPXListResponse.
struct CamelIMAPXMailbox;
Contains only private data that should be read and manipulated using the functions below.
Since 3.12
CamelIMAPXMailbox * camel_imapx_mailbox_new (CamelIMAPXListResponse *response
,CamelIMAPXNamespace *namespace_
);
Creates a new CamelIMAPXMailbox from response
and namespace
.
The mailbox's name, path separator character, and attribute set are initialized from the CamelIMAPXListResponse.
|
a CamelIMAPXListResponse |
|
a CamelIMAPXNamespace |
Returns : |
a CamelIMAPXMailbox |
Since 3.12
CamelIMAPXMailbox * camel_imapx_mailbox_clone (CamelIMAPXMailbox *mailbox
,const gchar *new_mailbox_name
);
Creates an identical copy of mailbox
, except for the mailbox name.
The copied CamelIMAPXMailbox is given the name new_mailbox_name
.
The new_mailbox_name
must be in the same IMAP namespace as mailbox
.
This is primarily useful for handling mailbox renames. It is safer to create a new CamelIMAPXMailbox instance with the new name than to try and rename an existing CamelIMAPXMailbox, which could disrupt mailbox operations in progress as well as data structures that track mailboxes by name.
|
a CamelIMAPXMailbox |
|
new name for the cloned mailbox |
Returns : |
a copy of mailbox , named new_mailbox_name
|
Since 3.12
gboolean camel_imapx_mailbox_exists (CamelIMAPXMailbox *mailbox
);
Convenience function returns whether mailbox
exists; that is, whether it
lacks a CAMEL_IMAPX_LIST_ATTR_NONEXISTENT attribute.
Non-existent mailboxes should generally be disregarded.
|
a CamelIMAPXMailbox |
Returns : |
whether mailbox exists |
Since 3.12
gint camel_imapx_mailbox_compare (CamelIMAPXMailbox *mailbox_a
,CamelIMAPXMailbox *mailbox_b
);
Compares two CamelIMAPXMailbox instances by their mailbox names.
|
the first CamelIMAPXMailbox |
|
the second CamelIMAPXMailbox |
Returns : |
a negative value if mailbox_a compares before mailbox_b ,
zero if they compare equal, or a positive value if mailbox_a
compares after mailbox_b
|
Since 3.12
gboolean camel_imapx_mailbox_matches (CamelIMAPXMailbox *mailbox
,const gchar *pattern
);
Returns TRUE
if mailbox
's name matches pattern
. The pattern
may
contain wildcard characters '*' and '%', which are interpreted similar
to the IMAP LIST command.
|
a CamelIMAPXMailbox |
|
mailbox name with possible wildcards |
Returns : |
TRUE if mailbox 's name matches pattern , FALSE otherwise |
Since 3.12
const gchar * camel_imapx_mailbox_get_name (CamelIMAPXMailbox *mailbox
);
Returns the mailbox name for mailbox
.
|
a CamelIMAPXMailbox |
Returns : |
the mailbox name |
Since 3.12
gchar camel_imapx_mailbox_get_separator (CamelIMAPXMailbox *mailbox
);
Returns the path separator character for mailbox
.
|
a CamelIMAPXMailbox |
Returns : |
the mailbox path separator character |
Since 3.12
CamelIMAPXNamespace * camel_imapx_mailbox_get_namespace (CamelIMAPXMailbox *mailbox
);
Returns the CamelIMAPXNamespace representing the IMAP server namespace
to which mailbox
belongs.
|
a CamelIMAPXMailbox |
Returns : |
a CamelIMAPXNamespace |
Since 3.12
guint32 camel_imapx_mailbox_get_messages (CamelIMAPXMailbox *mailbox
);
Returns the last known number of messages in the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "MESSAGES" value |
Since 3.12
void camel_imapx_mailbox_set_messages (CamelIMAPXMailbox *mailbox
,guint32 messages
);
Updates the last known number of messages in the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "MESSAGES" value |
Since 3.12
guint32 camel_imapx_mailbox_get_recent (CamelIMAPXMailbox *mailbox
);
Returns the last known number of messages with the \Recent flag set.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "RECENT" value |
Since 3.12
void camel_imapx_mailbox_set_recent (CamelIMAPXMailbox *mailbox
,guint32 recent
);
Updates the last known number of messages with the \Recent flag set.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "RECENT" value |
Since 3.12
guint32 camel_imapx_mailbox_get_unseen (CamelIMAPXMailbox *mailbox
);
Returns the last known number of messages which do not have the \Seen flag set.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "UNSEEN" value |
Since 3.12
void camel_imapx_mailbox_set_unseen (CamelIMAPXMailbox *mailbox
,guint32 unseen
);
Updates the last known number of messages which do not have the \Seen flag set.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "UNSEEN" value |
Since 3.12
guint32 camel_imapx_mailbox_get_uidnext (CamelIMAPXMailbox *mailbox
);
Returns the last known next unique identifier value of the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "UIDNEXT" value |
Since 3.12
void camel_imapx_mailbox_set_uidnext (CamelIMAPXMailbox *mailbox
,guint32 uidnext
);
Updates the last known next unique identifier value of the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "UIDNEXT" value |
Since 3.12
guint32 camel_imapx_mailbox_get_uidvalidity (CamelIMAPXMailbox *mailbox
);
Returns the last known unique identifier validity value of the mailbox.
This valud should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "UIDVALIDITY" value |
Since 3.12
void camel_imapx_mailbox_set_uidvalidity (CamelIMAPXMailbox *mailbox
,guint32 uidvalidity
);
Updates the last known unique identifier validity value of the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "UIDVALIDITY" value |
Since 3.12
guint64 camel_imapx_mailbox_get_highestmodseq
(CamelIMAPXMailbox *mailbox
);
Returns the last known highest mod-sequence value of all messages in the mailbox, or zero if the server does not support the persistent storage of mod-sequences for the mailbox.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
Returns : |
the last known "HIGHESTMODSEQ" value |
Since 3.12
void camel_imapx_mailbox_set_highestmodseq (CamelIMAPXMailbox *mailbox
,guint64 highestmodseq
);
Updates the last known highest mod-sequence value of all messages in the mailbox. If the server does not support the persistent storage of mod-sequences for the mailbox then the value should remain zero.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "HIGHESTMODSEQ" value |
Since 3.12
gchar ** camel_imapx_mailbox_dup_quota_roots (CamelIMAPXMailbox *mailbox
);
Returns the last known list of quota roots for mailbox
as described
in RFC 2087,
or NULL
if no quota information for mailbox
is available.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
The returned newly-allocated, NULL
-terminated string array should
be freed with g_strfreev()
when finished with it.
|
a CamelIMAPXMailbox |
Returns : |
the last known "QUOTAROOT" value |
Since 3.12
void camel_imapx_mailbox_set_quota_roots (CamelIMAPXMailbox *mailbox
,const gchar **quota_roots
);
Updates the last known list of quota roots for mailbox
as described
in RFC 2087.
This value should reflect the present state of the IMAP server as reported through untagged server responses in the current session.
|
a CamelIMAPXMailbox |
|
a newly-reported "QUOTAROOT" value |
Since 3.12
GSequence * camel_imapx_mailbox_copy_message_map
(CamelIMAPXMailbox *mailbox
);
Creates a copy of mailbox
's message map: a GSequence of 32-bit integers
which map message sequence numbers (MSNs) to unique identifiers (UIDs).
Free the returned GSequence with g_sequeuce_free()
when finished with it.
|
a CamelIMAPXMailbox |
Returns : |
a GSequence mapping MSNs to UIDs |
Since 3.12
void camel_imapx_mailbox_take_message_map (CamelIMAPXMailbox *mailbox
,GSequence *message_map
);
Takes ownership of a GSequence of 32-bit integers which map message
sequence numbers (MSNs) to unique identifiers (UIDs) for mailbox
.
The message_map
is expected to be assembled from a local cache of
previously fetched UIDs. The mailbox
will update it as untagged
server responses are processed.
|
a CamelIMAPXMailbox |
|
a GSequence mapping MSNs to UIDs |
Since 3.12
gboolean camel_imapx_mailbox_get_msn_for_uid (CamelIMAPXMailbox *mailbox
,guint32 uid
,guint32 *out_msn
);
Given a message's unique identifier (uid
), write the message's sequence
number to out_msn
and return TRUE
. If the unique identifier is unknown
(as far as mailbox
has been informed), the function returns FALSE
.
|
a CamelIMAPXMailbox |
|
a message's unique identifier |
|
return location for the message's sequence number, or NULL
|
Returns : |
whether out_msn was set |
Since 3.12
gboolean camel_imapx_mailbox_get_uid_for_msn (CamelIMAPXMailbox *mailbox
,guint32 msn
,guint32 *out_uid
);
Given a message's sequence number (msn
), write the message's unique
identifier to out_uid
and return TRUE
. If the sequence number is out of
range (as far as mailbox
has been informed), the function returns FALSE
.
|
a CamelIMAPXMailbox |
|
a message's sequence number (1..n) |
|
return location for the message's unique identifier, or NULL
|
Returns : |
whether out_uid was set |
Since 3.12
void camel_imapx_mailbox_deleted (CamelIMAPXMailbox *mailbox
);
Adds the CAMEL_IMAPX_LIST_ATTR_NONEXISTENT attribute to mailbox
.
Call this function after successfully completing a DELETE command.
|
a CamelIMAPXMailbox |
Since 3.12
void camel_imapx_mailbox_subscribed (CamelIMAPXMailbox *mailbox
);
Add the CAMEL_IMAPX_LIST_ATTR_SUBSCRIBED attribute to mailbox
.
Call this function after successfully completing a SUBSCRIBE command.
|
a CamelIMAPXMailbox |
Since 3.12
void camel_imapx_mailbox_unsubscribed (CamelIMAPXMailbox *mailbox
);
Removes the CAMEL_IMAPX_LIST_ATTR_SUBSCRIBED attribute from mailbox
.
Call this function after successfully completing an UNSUBSCRIBE command.
|
a CamelIMAPXMailbox |
Since 3.12
gboolean camel_imapx_mailbox_has_attribute (CamelIMAPXMailbox *mailbox
,const gchar *attribute
);
Returns whether mailbox
includes the given mailbox attribute.
The attribute
should be one of the LIST attribute macros defined
for CamelIMAPXListResponse.
|
a CamelIMAPXMailbox |
|
a mailbox attribute |
Returns : |
TRUE if mailbox has attribute , or else FALSE
|
Since 3.12
void camel_imapx_mailbox_handle_list_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXListResponse *response
);
Updates the internal state of mailbox
from the data in response
.
|
a CamelIMAPXMailbox |
|
a CamelIMAPXListResponse |
Since 3.12
void camel_imapx_mailbox_handle_lsub_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXListResponse *response
);
Updates the internal state of mailbox
from the data in response
.
|
a CamelIMAPXMailbox |
|
a CamelIMAPXListResponse |
Since 3.12
void camel_imapx_mailbox_handle_status_response (CamelIMAPXMailbox *mailbox
,CamelIMAPXStatusResponse *response
);
Updates the internal state of mailbox
from the data in response
.
|
a CamelIMAPXMailbox |
|
a CamelIMAPXStatusResponse |
Since 3.12