Share this page
imap_status_ex
| Example: imap_status_ex | Internet Messaging Functions (IMAP) |
Requests the mailbox status for a specific IMAP session.
int imap_status_ex( IMAP *ppimap, char *transaction, char *mailbox, char *item, LAST );
| ppimap | A session identifier. |
| transaction | A transaction name for this step in quotes. To avoid creating a transaction for this step, use a null string, "". |
| mailbox | The name of a mailbox in the following format:"MAILBOX=mailbox_name" |
| item | The requested data status item(s). For a list of the available items, see below. |
| LAST | A marker indicating the end of the argument list. |
The imap_status_ex function requests the status of the indicated mailbox. It does not change the currently selected mailbox, nor does it affect the state of any messages in the queried mailbox. After the status has been requested, imap_get_attribute_int_ex can be called to read the status values.
This function allows you to query a mailbox, without closing other previously opened mailboxes. It provides an alternative to opening a second IMAP4rev1 connection and calling imap_examine_ex.
The imap_status_ex function, unlike imap_list_ex, is not designed to provide a quick response. In some implementations, the server must open the mailbox internally to obtain status information, resulting in a slow response. Also, unlike the imap_list_ex, the imap_status_ex function does not accept wildcards.
The currently defined status data items that can be requested are:
| MESSAGES | The number of messages in the mailbox. |
| RECENT | The number of messages with the \Recent flag set. |
| UIDNEXT | The next UID value that will be assigned to a new message in the mailbox. This value will not change unless new messages are added to the mailbox; it will change when new messages are added, even if they are subsequently expunged. |
| UIDVALIDITY | The unique identifier validity value of the mailbox. |
| UNSEEN | The number of messages which do not have the \Seen flag set. |
This function is for use with multiple sessions. For global sessions, use the imap_status function, which leaves out the session identifier.
Return Values
If this function succeeds, it returns LR_PASS. Otherwise, it returns LR_FAIL.
Parameterization
All arguments of this function of the type char, can be parameterized with standard parameterization.
