4D Doc Center : IMAP

Home

4D Internet Commands v14

IMAP_SetCurrentMB


IMAP_SetCurrentMB ( imap_ID ; mbName ; msgNber ; newMsgNber ; customFlags ; permanentFlags ; mbUID ) -> Function result

Parameter	Type	Description
imap_ID	Longint	Reference to an IMAP login
mbName	Text	Name of the mailbox to select
msgNber	Longint	Number of messages in the current mailbox
newMsgNber	Longint	Number of messages with the \Recent flag set
customFlags	Text	List of flags currently used for the mailbox
permanentFlags	Text	List of flags permanently modifiable
mbUID	Longint	Mailbox unique identifier value
Function result	Integer	Error code

Description

The IMAP_SetCurrentMB command allows you to open a session (i.e. selects the current working Mailbox) in order to manage the messages of the specified mailbox.

Only one session can be opened at a time during a connection; simultaneous access to multiple mailboxes requires multiple connections (multiple IMAP_Login). The IMAP_SetCurrentMB command automatically closes the current session before attempting the new selection. Consequently, if a mailbox is defined as current and an IMAP_SetCurrentMB command fails, there will no longer be any mailbox defined as current.

You can close a session, (i.e. close the current mailbox) without selecting a new one, by executing the IMAP_SetCurrentMB command using a non-existing mbName and while managing the returned error, either by executing the IMAP_CloseCurrentMB, or by executing the IMAP_Logout command.

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

mbName is the full name of an existing mailbox to be defined as current.

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

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

customFlags returns the complete list of flags used in the current mailbox. Note that only flags listed in the permanentFlags string can be modified.

permanentFlags returns the list of mailbox message flags that can be changed permanently (except for the \Recent flag, which is managed by the IMAP server). (Set to null string when IMAP_SetCurrentMB is called). Note that the permanentFlags string can also include the special flag \*, which means that keywords can be created by trying to store those flags in the mailbox (see IMAP_SetFlags).

If permanentFlags returns a null string, this means that all the flags listed in the customFlags parameter can be permanently changed.

mbUID returns a unique identifier validity value for the current mailbox.
This identifier can be particularly useful if a mailbox is deleted and a new mailbox with the same name is created at a later date. Since the name is the same, a client may not know that this is a new mailbox unless the unique identifier validity is different.