The ImapGetFirstMailbox function is used to begin
enumerating the available mailboxes for the current user on the
IMAP server. Subsequent mailbox names are returned by calling
ImapGetNextMailbox until the function returns IMAP_ERROR
with an error code of ST_ERROR_NO_MORE_MAILBOXES.
The function of the lpszReference and lpszWildcard
parameters are implementation dependent and generally are tied to
the underlying operating system. On a UNIX based system, it can be
helpful to think of the reference name as the directory where
mailbox folders are stored, and the mailbox name as the name to
search for in that directory and any subdirectories, if applicable.
If the reference name is an empty string or NULL pointer, this
typically refers to the current user's home directory.
Generally speaking, a reference name should only be specified if
you or the user of the application knows the directory structure on
the IMAP server. Incorrectly using a reference name can have
serious negative side-effects. For example, specifying a reference
name of "/" on a UNIX based system could cause the IMAP server to
return search every directory on the system for a matching mailbox
name. Similarly, the IMAP server may be unable to distinguish
between regular files in the user's home directory and mailboxes.
For this reason, most IMAP clients require that the user specify
the directory on the server where their mailboxes are stored.
Typically this is subdirectory named "mail" or "Mail" under the
user's home directory. For non-UNIX servers, the mailbox hierarchy
may represented differently, including a flat hierarchy.
Hidden mailboxes are those mailboxes which use the UNIX
convention of the name beginning with a period. Therefore, a
mailbox named ".secrets" would not normally be returned by the
ImapGetFirstMailbox and ImapGetNextMailbox functions.
The IMAP_LIST_HIDDEN option causes all mailboxes to be
returned.
The IMAP_LIST_INFERIOR option will return inferior mailboxes
(mailboxes located in folders or subdirectories) if a wildcard mask
is not specified. If a wildcard mask is specified, this option has
no effect and only those mailboxes which match the wildcard will be
returned.
Subscribed mailboxes are those which were specified using the
ImapSubscribeMailbox function. Marked mailboxes are
typically those which have some special importance to the user.