IMAPSelectMailbox

Command group Flag affected Reversible Execute on client Platform(s)
External commands YES NO NO All

Syntax

IMAPSelectMailbox (socket,mailboxname,messages,recent,uidnext,uidvalidity,unseen[,stsproc,responselist]) Returns status

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

IMAPSelectMailbox makes a mailbox the currently selected mailbox. Certain IMAP commands operate in the context of a selected mailbox, meaning that this command needs to be executed first.

Socket is an Omnis Long Integer field containing a socket opened to an IMAP server using IMAPConnect.

Mailboxname is the name of the mailbox to be selected.

IMAP mailbox names are left-to-right hierarchical using a single character to separate levels of hierarchy. If you execute IMAPListMailboxes with empty RefName and MailboxName parameters, the returned list has a single line from which you can access the hierarchy separator.

All the Omnis IMAP commands automatically enclose mailbox names in double quotes when sending them to the server.

Messages is an Omnis Long Integer field which receives the number of messages in the selected mailbox, if the command succeeds. If the count is not received in the response to the IMAP SELECT command, this value can be zero.

Recent is an Omnis Long Integer field which receives the number of messages in the selected mailbox with the \Recent flag set, if the command succeeds.If the count is not received in the response to the IMAP SELECT command, this value can be zero.

Uidnext is an Omnis Long Integer field which receives the next unique identifier value for the selected mailbox, if the command succeeds.If the value is not received in the response to the IMAP SELECT command, this value can be zero.

Uidvalidity is an Omnis Long Integer field which receives the unique identifier validity value for the selected mailbox, if the command succeeds.If the value is not received in the response to the IMAP SELECT command, this value can be zero.

Unseen is an Omnis Long Integer field which receives the message sequence number of the first unseen message in the selected mailbox, if the command succeeds.If the value is not received in the response to the IMAP SELECT command, this value can be zero.

Stsproc is an optional parameter containing the name of an Omnis method that this command calls with status messages. This command calls the method with no parameters, and the status information in the variable #S1. The status information logs protocol messages exchanged on the connection to the server.

Responselist is an optional parameter into which this command places response lines received from the IMAP server. Before calling this command, define the responselist to have a single Character column. When the command returns successfully, the response list contains the untagged and tagged responses received from the IMAP server as a result of executing this command. These sometimes include unsolicited information, for example, an update on the current number of messages in the selected mailbox. Each line in the response list is a response line received from the server. See RFC 3501 for more details, if you need to handle this sort of information.

This command returns an integer, which is less than zero if an error occurred. Possible error codes are listed in the Web Command Error Codes Appendix.

Example

; Make INBOX the currently selected mailbox
Calculate iMailbox as "INBOX"
IMAPSelectMailbox (iIMAPSocket,iMailbox,iMessages,iRecent,iUIDNext,iUIDValidity,iUnseen) Returns lStatus
If lStatus<0
  ; SELECT command failed
End If