4D Doc Center : IMAP

Home

4D Internet Commands v14

IMAP_GetMBStatus


IMAP_GetMBStatus ( imap_ID ; mbName ; msgNber ; newMsgNber ; unseenMsgNber ; mbUID ) -> Function result

Parameter	Type	Description
imap_ID	Longint	Reference to an IMAP login
mbName	Text	Name of the mailbox
msgNber	Longint	Number of messages in the specified mailbox
newMsgNber	Longint	Number of messages with the \Recent flag set
unseenMsgNber	Longint	Number of messages with no \Seen flag
mbUID	Longint	Specified mailbox unique identifier
Function result	Integer	Error code

Description

The IMAP_GetMBStatus command returns the status parameter values of the mailbox specified by mbName. It does not change the current mailbox (see IMAP_SetCurrentMB), nor does it affect the state of any messages in the specified mailbox (in particular, it usually does not cause messages to lose the \Recent flag, but this can vary depending on the IMAP4 server implementation). This is an alternative used to check mailbox status parameters without deselecting the current mailbox.

This command is particularly useful to:

Check or retrieve the mailbox unique identifier, and/or,
Check recent and unseen messages without opening a session for the mailbox.

Important: We strongly recommend that you do not call the IMAP_GetMBStatus command using the current mailbox. By doing so, you may encounter problems and the information returned will not necessarily be synchronized with the current mailbox status (in particular for new e-mails).

imap_ID is a long integer reference to an open connection created with IMAP_Login.

mbName is the full name of the existing mailbox for which you want to get the status parameter values.

Note: Unlike the IMAP_ListMBs command, the mbName parameter does not accept wildcards.

msgNber returns the number of messages in the current mailbox (set to zero when the command is called and returns -1 if error).

newMsgNber returns the number of recent messages in the current mailbox (set to zero when the command is called and returns -1 if error).

unseenMsgNber returns the number of unseen messages in the current mailbox (set to zero when the command is called and returns -1 if error)

mbUID returns the mailbox unique identifier validity value (set to zero when the command is called and returns –1 if error ).

With the IMAP4 protocol, the mailbox name is not sufficient to identify a mailbox. As such, a unique identifier validity value is associated with each mailbox. This identifier is particularly valuable for synchronizing tasks.
Thus, you can verify if mailbox “A” has been renamed as “B” or deleted, simply by checking the unique identifier validity value.
On the other hand, this identifier allows you to check whether a mailbox named “A” has been deleted and if another “A” mailbox has been created.