2.2.1.8 GetHierarchy
The GetHierarchy command gets the list of email folders from the server. Each folder's place within the folder hierarchy is indicated by its parent ID. The list of folders returned by the GetHierarchy command includes only email folders. For example, the Contacts folder and the Calendar folder are not included in the list.
Because the GetHierarchy command does not return a synchronization state for a folder hierarchy, the client uses the FolderSync command either to manipulate the folder hierarchy or to retrieve the complete folder hierarchy. The client can use the GetHierarchy command to obtain the collection ID of a folder, such as Sent Items folder or Deleted Items folder, that does not change and cannot be deleted. The collection ID is obtained from the ServerId element of a previous FolderSync or FolderCreate command. An HTTP status code of 500 is returned in the response if the GetHierarchy command request fails.
The FolderHierarchy namespace is the primary namespace for this section. Elements referenced in this section that are not defined in the FolderHierarchy namespace use the namespace prefixes defined in section 2.2.4.
The following table lists the elements that are used in GetHierarchy command responses. There is no XML body in a GetHierarchy command request.
|
Element name |
Scope |
Reference |
|---|---|---|
|
Folders |
Response |
section 2.2.3.75.1 |
|
Folder |
Response |
section 2.2.3.71.1 |
|
DisplayName |
Response |
section 2.2.3.49.5 |
|
ServerId |
Response |
section 2.2.3.166.6 |
|
Type |
Response |
section 2.2.3.186.4 |
|
ParentId |
Response |
section 2.2.3.129.4 |
The XML schema for the GetHierarchy command response is described in section 6.19.
Note: Unlike other commands, the GetHierarchy command does not have a top-level element of the same name. That is, there is no such top-level element called "GetHierarchy" that identifies the body of the HTTP POST as containing a GetHierarchy command. Instead, the Folders element is the top-level element.
Protocol Versions
The following table specifies the protocol versions that support this command. The client indicates the protocol version being used by setting either the MS-ASProtocolVersion header, as specified in [MS-ASHTTP] section 2.2.1.1.2.6, or the Protocol version field, as specified in [MS-ASHTTP] section 2.2.1.1.1.1, in the request.
|
Protocol version |
Command support |
|---|---|
|
2.5 |
Yes |
|
12.0 |
Yes |
|
12.1 |
Yes |
|
14.0 |
|
|
14.1 |
|
|
16.0 |
|
|
16.1 |
|
In protocol versions 14.0, 14.1, 16.0 and 16.1, the FolderSync command, as specified in section 2.2.1.5, is used to retrieve email folders from the server.