INT GetFirstMailbox(
	LPCTSTR lpszReference,
	LPCTSTR lpszWildcard,
	DWORD dwOptions,
	LPTSTR lpszMailbox,
	INT nMaxLength
	LPDWORD lpdwFlags
);

INT GetFirstMailbox(
	CString& strMailbox,
	LPDWORD lpdwFlags
);

The GetFirstMailbox method returns the name of the first matching mailbox.

Parameters

lpszReference

A pointer to a string which specifies the reference name. An empty string or NULL pointer specifies that the default mailbox hierarchy for the current user is returned. If the reference name is provided, this must be the name of a mailbox or a level of the mailbox hierarchy which provides the context in which the mailbox name is interpreted.

lpszWildcard

A pointer to a null terminated string which specifies the mailbox name to match. The wildcard character "*" may be used to match any portion of the mailbox hierarchy, including the delimiter. The wildcard character "%" matches any portion of the mailbox name, but does not match the mailbox delimiter. An empty string or NULL pointer specifies that all mailboxes in the context of the lpszReference parameter should be returned.

dwOptions

Specifies one or more options which controls how mailboxes are returned by the method. The options are bit flags which may be combined using a bitwise operator. One or more of the following values may be used:

Constant	Description
IMAP_LIST_DEFAULT	This option specifies that all regular, selectable mailboxes should be returned.
IMAP_LIST_SUBSCRIBED	This option specifies that only subscribed mailboxes should be returned.
IMAP_LIST_FOLDERS	This option specifies that non-selectable mailbox folders should also be returned.
IMAP_LIST_HIDDEN	This option specifies that hidden mailboxes should be returned.
IMAP_LIST_INFERIOR	This option specifies that inferior mailboxes should be returned if an explicit wildcard mask is not specified.

lpszMailbox

A pointer to a string buffer which will contain the first matching mailbox. This parameter cannot be NULL. A minimum buffer size of at least 128 character is recommended.

nMaxLength

Specifies the maximum length of the string buffer. The maximum length of the buffer should be large enough to accommodate most path names on the IMAP server.

lpdwFlags

A pointer to an unsigned integer which will contain the mailbox flags for the first matching mailbox. This parameter may be NULL, in which case the mailbox flags are not returned. Otherwise, one or more of the following bit flags may be returned:

Constant	Description
IMAP_FLAG_NOINFERIORS	The mailbox does not contain any sub-mailboxes. In the IMAP protocol, these are referred to as inferior hierarchical mailbox names.
IMAP_FLAG_NOSELECT	The mailbox cannot be selected or examined. This flag is typically used by servers to indicate that the mailbox name refers to a directory on the server, not a mailbox file.
IMAP_FLAG_MARKED	The mailbox is marked as being of interest to a client. If this flag is used, it typically means that the mailbox contains messages. An application should not depend on this flag being present for any given mailbox. Some IMAP servers do not support marked or unmarked flags for mailboxes.
IMAP_FLAG_UNMARKED	The mailbox is marked as not being of interest to a client. If this flag is used, it typically means that the mailbox does not contain any messages. An application should not depend on this flag being present for any given mailbox. Some IMAP servers do not support marked or unmarked flags for mailboxes.

Return Value

If the method succeeds, it returns the length of the mailbox name. If an error occurs, the method returns IMAP_ERROR. To get extended error information, call GetLastError.

Remarks

The GetFirstMailbox method is used to begin enumerating the available mailboxes for the current user on the IMAP server. Subsequent mailbox names are returned by calling GetNextMailbox until the method returns IMAP_ERROR with an error code of ST_ERROR_NO_MORE_MAILBOXES.

The method 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 GetFirstMailbox and GetNextMailbox methods. 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 SubscribeMailbox method. Marked mailboxes are typically those which have some special importance to the user.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: csmapv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

DeleteMailbox, GetMailboxStatus, GetNextMailbox, RenameMailbox, SelectMailbox

Copyright © 2023 Catalyst Development Corporation. All rights reserved.