4D Doc Center : IMAP

Home

4D Internet Commands v14

IMAP_ListMBs


IMAP_ListMBs ( imap_ID ; mbRefName ; mbName ; mbNamesArray ; mbAttribsArray ; mbHierarArray ; subscribedMB ) -> Function result

Parameter	Type	Description
imap_ID	Longint	Reference to an IMAP login
mbRefName	Text	Null string or Mailbox name or level of mailbox hierarchy
mbName	Text	Null string or MailBoxName or wildcards
mbNamesArray	String array	Array of mailbox names (pathnames)
mbAttribsArray	String array	Array of mailbox attributes
mbHierarArray	String array	Array of hierarchy delimiters
subscribedMB	Integer	0 = List all available user mailboxes 1 = List only subscribed mailboxes
Function result	Integer	Error code

Description

The IMAP_ListMBs command returns the list of available mailboxes for the connected user and attached information. If this command fails, specified arrays are initialized.

mbRefName and mbName must be considered together since the resulting Mailbox list will depend on the combination of these two parameter values.

The returned list may be restricted to subscribed mailboxes (see IMAP_SubscribeMB) when the last parameter, subscribedMB, is set to 1.

When the execution of IMAP_ListMBs is very long, either because a large number of mailboxes are being scanned, or because of numerous and complex hierarchical mailbox structures, and so on, you can:

use wildcards (see below) with IMAP_ListMBs,
or use the IMAP_ListMBs command, with the subscribedMB parameter set to 1, to list only a set of mailboxes defined using the IMAP_SubscribeMB command.

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

mbRefName is a text value that should be combined with the mbName parameter to determine which mailboxes should be looked for. The reference name (mbRefName) should be used as a Current Working Directory on Unix systems. In other words, the mailbox name (mbName) is interpreted as a file located in the directory specified by the reference name (mbRefName). Be sure that the IMAP specification leaves the interpretation of the reference name (mbRefName) “implementation-dependent”. We strongly recommend that the user be given an operational mode that does not use any mbRefName reference argument. As such, it can interoperate with older servers that did not implement the use of reference arguments.

If mbRefName is a null string, only the mbName parameter is used to list mailboxes.

If mbRefName contains the name of a mailbox or a level of mailbox hierarchy, it should be used to define the context in which the mbName parameter must be interpreted.

Note: We strongly recommend that you place a trailing hierarchy delimiter on the reference argument when used. This will ensure full compliance whichever IMAP server is used.

mbName is a text value, intended to be combined with the mbRefName parameter, which usually defines the context in which the mbName parameter must be interpreted.

If mbName is a null string, the hierarchy delimiter is returned.

Note: If you implement a breakout facility using the mbRefName parameter, you should allow the user to choose whether or not to use a leading hierarchy delimiter on the mailbox argument. This is because the handling of a leading mailbox hierarchy delimiter varies from one server to another, and even between different electronic mail stores on the same server. In some cases, a leading hierarchy delimiter means “discard the reference argument”; whereas in other cases, the two are concatenated and the extra hierarchy delimiter is discarded.

The mbNamesArray array receives the list of available mailboxes’ names.

The mbAttribsArray array receives the list of available mailboxes’ attributes.

Mailbox attributes
There are four mailbox attributes defined as follows:

\Noinferiors: no child levels currently exist and none can be created.
\Noselect: this name cannot be used as a selectable mailbox.
\Marked: the server has marked the mailbox as “interesting”; the mailbox probably contains messages added since the last selection.
\Unmarked: the mailbox does not contain any additional messages since the last selection.

The mbHierarArray array receives the list of available mailboxes’ hierarchy delimiters.

The hierarchy delimiter is a character used to delimit hierarchy levels in a mailbox name. You can use it to create child mailboxes and to search higher or lower levels of the naming hierarchy. All children of a top-level hierarchy node use the same separator character.

subscribedMB is an integer value which can be specified when you simply want to list “subscribed” mailboxes. A zero value lists all available user mailboxes. A value of 1 only lists subscribed user mailboxes. subscribedMB is an optional parameter that will default to zero if not otherwise specified.

Example 1

The following example:

IMAP_ListMBs(imap_ID;"4DIC/Work/";"Test";mbNamesArray;mbAttribsArray;mbHierarArray)

...returns all available mailboxes from the “4DIC/Work/Test” mailbox.
Remember that if the IMAP server does not interpret as was intended, do not use the mbRefName and concatenate the mbRefName and mbName values into mbName:

IMAP_ListMBs(imap_ID;"";"4DIC/Work/Test";mbNamesArray;mbAttribsArray;mbHierarArray)

Example 2

The following example:

IMAP_ListMBs(imap_ID;"";"";mbNamesArray;mbAttribsArray;mbHierarArray)

...returns the hierarchy delimiter.

Using the Wildcard character

You can use wildcards in the mbRefName and mbName parameters to make mailbox selection easier. You will find an example of current wildcards below, but please note that the interpretation of wildcards will depend on the IMAP server; consequently, these examples may not work. In this case, check your IMAP server wildcards.

“ * ” matches zero or more characters in its position:

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

... returns all mailboxes available to the connected user.

IMAP_ListMBs(imap_ID;"";"Work*";mbNamesArray;mbAttribsArray;mbHierarArray)

... returns all available mailboxes matching the root “Work”.

“ % ” is similar to “ * ”, but it does not match a hierarchy delimiter. If the “%” wildcard is the last character of the mbName parameter, matching hierarchy levels are also returned. If these hierarchy levels are not selectable mailboxes, they are returned with the \Noselect mailbox attribute (see paragraph “Mailbox attributes”).

IMAP_ListMBs(imap_ID"";"Work/%";mbNamesArray;mbAttribsArray;mbHierarArray)

... returns all mailboxes matching the root “Work”, plus one hierarchy level available for the connected user.

“%” can be helpful in order to parse the mailbox hierarchy level by level.
Given the following mailbox hierarchy:

INBOX
   MailboxA
      MailboxAA
      MailboxAB
   MailboxB
      MailboxBA
      MailboxBB
   MailboxC
      MailboxCA
      MailboxCB

IMAP_ListMBs(imap_ID;"";"%";mbNamesArray;mbAttribsArray;mbHierarArray)

... returns INBOX, MailboxA, MailboxB and MailboxC.

IMAP_ListMBs(imap_ID;"";"MailboxA%";mbNamesArray;mbAttribsArray;mbHierarArray)

... returns MailboxAA and MailboxAB.

Using this technique, you can give the user complete flexibility without being bogged down by the voluminous reply to

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

Note that IMAP servers themselves may limit the number of levels to be scanned.