HrValidateIPMSubtree

The HrValidateIPMSubtree function adds standard interpersonal message (IPM) folders to a message store.

Note  This function may not be supported in future versions of MAPI.

Quick Info

HrValidateIPMSubtree(
  LPMDB lpMDB,                   
  ULONG ulFlags,                 
  ULONG FAR * lpcValues,         
  LPSPropValue FAR * lppProps,   
  LPMAPIERROR FAR * lppMapiError  
);
 

Parameters

lpMDB

[in] Pointer to the message store object to which to add the folders.

ulFlags

[in] Bitmask of flags used to control how the folders are created. The following flags can be set:

MAPI_FORCE_CREATE

The folders should be verified before creation, even if message store properties indicate that they are valid. A client application typically sets this flag when an error indicates that the structure of an existing folder has been damaged.

MAPI_FULL_IPM_TREE

The full set of IPM folders should be created in the message store's root folder. The folder titles in the hierarchy are:

Folder Views
Common Views
Search Root*
IPM Subtree*
Inbox
Outbox
Deleted Items*
Sent Items

where the three folders marked with * are the minimum set created even when the MAPI_FULL_IPM_TREE flag has not been set. A client application typically sets this flag when the message store in which the folders are to be created is the default store.

lpcValues

[in, out] Pointer to the number of SPropValue structures in the array returned in the lppProps parameter. The value of the lpcValues parameter can be zero if lppProps is NULL.

lppProps

[in, out] Pointer to a pointer to an array of SPropValue structures containing property values for the PR_VALID_FOLDER_MASK property and for the appropriate folder entry identifier properties. If HrValidateIPMSubtree creates an Inbox in the message store, the SPropValue array includes an Inbox entry identifier with a special property tag coded as PROP_TAG(PT_BINARY, PROP_ID_NULL). The lppProps parameter can be NULL, indicating that the calling implementation does not require that an SPropValue array be returned.

lppMapiError

[out] Pointer to a pointer to a MAPIERROR structure containing version, component, and context information for an error. The lppMAPIError parameter is set to NULL if no MAPIERROR structure is returned.

Remarks

MAPI uses the HrValidateIPMSubtree function internally to construct the standard IPM subtree in a message store when the store is first opened, or when a store is made the default store. This function can also be used by client applications to validate or repair standard message folders.

HrValidateIPMSubtree always creates the Search Root and IPM Subtree folders in the store's root folder and the Deleted Items folder in the IPM Subtree folder. The IPM Subtree folder is the root of the IPM hierarchy in that message store. The Search Root folder can be used as the root of a subtree for search-results folders.

IPM clients should display their folder view starting at the IPM subtree root folder and showing child folders beneath it. Information in the root folder of a message store should not appear in a client's user interface. This functionality means that if a client must hide information, the information can be put in the IPM subtree root directory, where it is not visible to the user. In contrast, non-IPM applications that require messages and folders to be invisible to the user, for example in a server-based message store, can put them outside the IPM hierarchy.

HrValidateIPMSubtree sets the PR_VALID_FOLDER_MASK property to indicate whether each IPM folder it creates has a valid entry identifier. The following entry identifier properties of the message store are set to the entry identifiers of the corresponding folders and returned in the lppProps parameter along with PR_VALID_FOLDER_MASK:

PR_COMMON_VIEWS_ENTRYID
PR_FINDER_ENTRYID
PR_IPM_OUTBOX_ENTRYID
PR_IPM_SENTMAIL_ENTRYID
PR_IPM_SUBTREE_ENTRYID
PR_IPM_WASTEBASKET_ENTRYID
PR_VIEWS_ENTRYID
A placeholder PROP_TAG for the IPM Inbox (PT_BINARY, PROP_ID_NULL).

See Also

IMAPISession::OpenMsgStore