| Command group | Flag affected | Reversible | Execute on client | Platform(s) |
|---|---|---|---|---|
| External commands | YES | NO | NO | All |
IMAPListSubscribedMailboxes (socket,refname,mailboxname,list[,stsproc,responselist]) Returns status
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.
IMAPListSubscribedMailboxes sends an LSUB command to the IMAP server, in order to get a list of a subset of mailbox names from the complete set of all subscribed names available to the client.
Socket is an Omnis Long Integer field containing a socket opened to an IMAP server using IMAPConnect.
Refname is an Omnis Character field. The command encloses refname in double quotes, and sends it as the reference name argument of the LIST command. Setting this to an empty string means the mailbox names will be interpreted from the top level. You may also set this as the name of a mailbox, in which case this will be taken as the root of the search, and only mailboxes which are subfolders of this will be included in the search. For full details, see RFC 3501.
Mailboxname is an Omnis Character field. The command encloses mailboxname in double quotes, and sends it as the mailbox name with possible wildcards argument of the LIST command. Setting this to an empty string is a special request, which will return a single list line including the hierarchy separator character. Otherwise it will return a list of mailboxes which match your search criteria. For example, Ӎ*Ԡwill return a list of mailboxes beginning with M. For full details, see RFC 3501.
List receives the mailboxes returned by the server. Before calling the command, you must define the list to have seven columns, as follows:
| Column | Contains |
|---|---|
| HasChildren | A long integer which receives the \HasChildren flag value for the mailbox. Not all servers support this flag, and even when a server supports the flag, it may not always supply a value for this flag. Supported values are kFalse if the mailbox has the \HasNoChildren flag, kTrue if the mailbox has the \HasChildren flag, and kUnknown if the mailbox has neither of these flags. |
| NoInferiors | A long integer which receives the \NoInferiors flag value for the mailbox. kTrue if the mailbox has the \NoInferiors flag, kFalse if not. |
| NoSelect | A long integer which receives the \NoSelect flag value for the mailbox. kTrue if the mailbox has the \NoSelect flag, kFalse if not. |
| Marked | A long integer which receives the \Marked flag value for the mailbox. kTrue if the mailbox has the \Marked flag, kFalse if not. |
| UnMarked | A long integer which receives the \UnMarked flag value for the mailbox. kTrue if the mailbox has the \UnMarked flag, kFalse if not. |
| Separator | The mailbox hierarchy separator character |
| MailboxName | The mailbox name |
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.
# List all subscribed mailboxes (folders) in the INBOX (INBOX is a standard IMAP mailbox)
# "." is the hierarchy separator
Do iMailboxList.$define(iHasChildren,iNoInferiors,iNoselect,iMarked,iUnmarked,iSeparator,iMailbox)
Calculate iRefName as "INBOX."
Calculate iMailbox as "%"
IMAPListSubscribedMailboxes (iIMAPSocket,iRefName,iMailbox,iMailboxList) Returns lStatus
If lStatus<0
# Command failed
End If