## CamelIMAPXMailbox

CamelIMAPXMailbox — Stores the state of an IMAP mailbox

## Synopsis

    #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);

## Object Hierarchy

      GObject
       +----CamelIMAPXMailbox

## Description

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.

## Details

### struct CamelIMAPXMailbox

    struct CamelIMAPXMailbox;

Contains only private data that should be read and manipulated using the functions below.

Since 3.12

### camel_imapx_mailbox_new ()

    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.

`response` : | a CamelIMAPXListResponse
`namespace_` : | a CamelIMAPXNamespace
Returns : | a CamelIMAPXMailbox

Since 3.12

### camel_imapx_mailbox_clone ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`new_mailbox_name` : | new name for the cloned mailbox
Returns : | a copy of `mailbox`, named `new_mailbox_name`

Since 3.12

### camel_imapx_mailbox_exists ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | whether `mailbox` exists

Since 3.12

### camel_imapx_mailbox_compare ()

    gint                camel_imapx_mailbox_compare         (CamelIMAPXMailbox *mailbox_a,
                                                             CamelIMAPXMailbox *mailbox_b);

Compares two CamelIMAPXMailbox instances by their mailbox names.

`mailbox_a` : | the first CamelIMAPXMailbox
`mailbox_b` : | 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

### camel_imapx_mailbox_matches ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`pattern` : | mailbox name with possible wildcards
Returns : | `TRUE` if `mailbox`'s name matches `pattern`, `FALSE` otherwise

Since 3.12

### camel_imapx_mailbox_get_name ()

    const gchar *       camel_imapx_mailbox_get_name        (CamelIMAPXMailbox *mailbox);

Returns the mailbox name for `mailbox`.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the mailbox name

Since 3.12

### camel_imapx_mailbox_get_separator ()

    gchar               camel_imapx_mailbox_get_separator   (CamelIMAPXMailbox *mailbox);

Returns the path separator character for `mailbox`.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the mailbox path separator character

Since 3.12

### camel_imapx_mailbox_get_namespace ()

    CamelIMAPXNamespace * camel_imapx_mailbox_get_namespace (CamelIMAPXMailbox *mailbox);

Returns the CamelIMAPXNamespace representing the IMAP server namespace to which `mailbox` belongs.

`mailbox` : | a CamelIMAPXMailbox
Returns : | a CamelIMAPXNamespace

Since 3.12

### camel_imapx_mailbox_get_messages ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "MESSAGES" value

Since 3.12

### camel_imapx_mailbox_set_messages ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`messages` : | a newly-reported "MESSAGES" value

Since 3.12

### camel_imapx_mailbox_get_recent ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "RECENT" value

Since 3.12

### camel_imapx_mailbox_set_recent ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`recent` : | a newly-reported "RECENT" value

Since 3.12

### camel_imapx_mailbox_get_unseen ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "UNSEEN" value

Since 3.12

### camel_imapx_mailbox_set_unseen ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`unseen` : | a newly-reported "UNSEEN" value

Since 3.12

### camel_imapx_mailbox_get_uidnext ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "UIDNEXT" value

Since 3.12

### camel_imapx_mailbox_set_uidnext ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`uidnext` : | a newly-reported "UIDNEXT" value

Since 3.12

### camel_imapx_mailbox_get_uidvalidity ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "UIDVALIDITY" value

Since 3.12

### camel_imapx_mailbox_set_uidvalidity ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`uidvalidity` : | a newly-reported "UIDVALIDITY" value

Since 3.12

### camel_imapx_mailbox_get_highestmodseq ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "HIGHESTMODSEQ" value

Since 3.12

### camel_imapx_mailbox_set_highestmodseq ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`highestmodseq` : | a newly-reported "HIGHESTMODSEQ" value

Since 3.12

### camel_imapx_mailbox_dup_quota_roots ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | the last known "QUOTAROOT" value

Since 3.12

### camel_imapx_mailbox_set_quota_roots ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`quota_roots` : | a newly-reported "QUOTAROOT" value

Since 3.12

### camel_imapx_mailbox_copy_message_map ()

    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.

`mailbox` : | a CamelIMAPXMailbox
Returns : | a GSequence mapping MSNs to UIDs

Since 3.12

### camel_imapx_mailbox_take_message_map ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`message_map` : | a GSequence mapping MSNs to UIDs

Since 3.12

### camel_imapx_mailbox_get_msn_for_uid ()

    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`.

`mailbox` : | a CamelIMAPXMailbox
`uid` : | a message's unique identifier
`out_msn` : | return location for the message's sequence number, or `NULL`
Returns : | whether `out_msn` was set

Since 3.12

### camel_imapx_mailbox_get_uid_for_msn ()

    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`.

`mailbox` : | a CamelIMAPXMailbox
`msn` : | a message's sequence number (1..n)
`out_uid` : | return location for the message's unique identifier, or `NULL`
Returns : | whether `out_uid` was set

Since 3.12

### camel_imapx_mailbox_deleted ()

    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.

`mailbox` : | a CamelIMAPXMailbox

Since 3.12

### camel_imapx_mailbox_subscribed ()

    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.

`mailbox` : | a CamelIMAPXMailbox

Since 3.12

### camel_imapx_mailbox_unsubscribed ()

    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.

`mailbox` : | a CamelIMAPXMailbox

Since 3.12

### camel_imapx_mailbox_has_attribute ()

    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.

`mailbox` : | a CamelIMAPXMailbox
`attribute` : | a mailbox attribute
Returns : | `TRUE` if `mailbox` has `attribute`, or else `FALSE`

Since 3.12

### camel_imapx_mailbox_handle_list_response ()

    void                camel_imapx_mailbox_handle_list_response
                                                            (CamelIMAPXMailbox *mailbox,
                                                             CamelIMAPXListResponse *response);

Updates the internal state of `mailbox` from the data in `response`.

`mailbox` : | a CamelIMAPXMailbox
`response` : | a CamelIMAPXListResponse

Since 3.12

### camel_imapx_mailbox_handle_lsub_response ()

    void                camel_imapx_mailbox_handle_lsub_response
                                                            (CamelIMAPXMailbox *mailbox,
                                                             CamelIMAPXListResponse *response);

Updates the internal state of `mailbox` from the data in `response`.

`mailbox` : | a CamelIMAPXMailbox
`response` : | a CamelIMAPXListResponse

Since 3.12

### camel_imapx_mailbox_handle_status_response ()

    void                camel_imapx_mailbox_handle_status_response
                                                            (CamelIMAPXMailbox *mailbox,
                                                             CamelIMAPXStatusResponse *response);

Updates the internal state of `mailbox` from the data in `response`.

`mailbox` : | a CamelIMAPXMailbox
`response` : | a CamelIMAPXStatusResponse

Since 3.12