IMAPIContainer::GetHierarchyTable
The IMAPIContainer::GetHierarchyTable
method returns a pointer to the container s hierarchy table.
Quick Info
See IMAPIContainer
: IMAPIProp.
HRESULT GetHierarchyTable(
|
ULONG ulFlags,
|
|
|
LPMAPITABLE FAR * lppTable |
|
|
) |
|
Parameters
ulFlags
[in] Bitmask
of flags that controls how information is returned in the table. The following
flags can be set:
CONVENIENT_DEPTH
Fills the
hierarchy table with containers from multiple levels. If CONVENIENT_DEPTH is
not set, the hierarchy table contains only the container s immediate child
containers.
MAPI_DEFERRED_ERRORS
GetHierarchyTable can return successfully, possibly before the table is
made accessible to the caller. If the table is not accessible, making a
subsequent table call can result in an error.
MAPI_UNICODE
Requests that
the columns containing string data be returned in the Unicode format. If the
MAPI_UNICODE flag is not set, the strings should be returned in the ANSI
format.
lppTable
[out] Pointer
to a pointer to the hierarchy table.
Return Values
S_OK
The hierarchy
table was successfully retrieved.
MAPI_E_BAD_CHARWIDTH
Either the
MAPI_UNICODE flag was set and the implementation does not support Unicode, or
MAPI_UNICODE was not set and the implementation only supports Unicode.
MAPI_E_NO_SUPPORT
The container
has no child containers and cannot provide a hierarchy table.
Remarks
The IMAPIContainer::GetHierarchyTable
method returns a pointer to the hierarchy table of a container. A hierarchy
table holds summary information about the child containers within the
container. Folder hierarchy tables hold information about child folders; address
book hierarchy tables hold information about child address book containers and
distribution lists.
It is
possible for some containers to have no child containers. These containers
return MAPI_E_NO_SUPPORT from their implementations of GetHierarchyTable.
When the
CONVENIENT_DEPTH flag is set, each row in the hierarchy table also includes the
PR_DEPTH property
as a column. PR_DEPTH indicates the level of each container relative to the
container implementing the table. The implementing container s immediate child
containers are at depth zero, child containers within the zero depth containers
are at depth one, and so on. The values of PR_DEPTH increase sequentially as
the hierarchy of levels deepens.
For a
complete list of required and optional columns in hierarchy tables, see Hierarchy
Tables.
Notes to Implementers
If you
support a hierarchy table for your container, you must also:
Support a call to the
container s IMAPIProp::OpenProperty method to open the PR_CONTAINER_HIERARCHY property.
Return PR_CONTAINER_HIERARCHY
from a call to the container s IMAPIProp::GetProps or IMAPIProp::GetPropList method.
Notes to Callers
String and
binary contents table columns can be truncated. Typically, providers return 255
characters. Because you cannot know ahead of time whether or not a table
includes truncated columns, assume that a column is truncated if the length of
the column is either 255 or 510 bytes. You can always retrieve the full value
of a truncated column if necessary from the object directly by using its entry
identifier to open it and then calling the IMAPIProp::GetProps method.
Depending on
the provider s implementation, restrictions and sorting operations can apply to
an entire string or to the truncated version of that string.
See Also