Share this page
imap_status
| Example: imap_status | Internet Messaging Functions (IMAP) |
Requests the mailbox status.
int imap_status( char *transaction, char *mailbox, char *item, LAST );
| 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 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, get the status values with imap_get_attribute_int.
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.
The imap_status function, unlike imap_list, 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, the imap_status 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 global sessions. For multiple sessions, use the imap_status_ex function, which allows you to specify a 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.
