• Article

FindFolder Operation

Topic Last Modified: 2008-07-08

The FindFolder operation uses Exchange Web Services to find subfolders of an identified folder and returns a set of properties that describe the set of subfolders.

Remarks

FindFolder returns only the first 512 bytes of any streamable property. For Unicode, it returns the first 255 characters by using a null-terminated Unicode string.

Deep traversal queries are not allowed on public folders.

Restrictions are permitted and should only use the folder properties, not the item properties. Sorting functionality is not available for FindFolder responses. Grouped queries are not available for FindFolder queries.

Note   The FindFolder operation is also used to find managed folders.

FindFolder Request Example

Description

The following example of a FindFolder request shows how to form a request to find all the folders located in an Inbox.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
  xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <FindFolder Traversal="Shallow" xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <FolderShape>
        <t:BaseShape>Default</t:BaseShape>
      </FolderShape>
      <ParentFolderIds>
        <t:DistinguishedFolderId Id="inbox"/>
      </ParentFolderIds>
    </FindFolder>
  </soap:Body>
</soap:Envelope>

Comments

Using the Default value for the BaseShape, the response returns the folder name, the folder ID, the number of subfolders, the number of child folders found in the folder, and an unread item count.

Request Elements

This FindFolder request includes the following elements:

See the schema for additional FindFolder request elements.

Note

The default location of the schema is \Program Files\Microsoft\Exchange Server\ClientAccess\exchweb\EPI on the computer that is running Microsoft Exchange Server 2007 that has the Client Access server role installed.

FindFolder Response Example

Description

The following Simple Object Access Protocol (SOAP) body example shows a successful response to the FindFolder request. The response contains the elements that are returned when the Default value for the BaseShape is used.

Note

The folder ID and the change key have been shortened to preserve readability.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="652" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                        xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                        xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:FindFolderResponseMessage ResponseClass="Success">
          <m:ResponseCode>NoError</m:ResponseCode>
          <m:RootFolder TotalItemsInView="1" IncludesLastItemInRange="true">
            <t:Folders>
              <t:Folder>
                <t:FolderId Id="AQAnAH" ChangeKey="AQAAABY" />
                <t:DisplayName>TestFolder</t:DisplayName>
                <t:TotalCount>0</t:TotalCount>
                <t:ChildFolderCount>0</t:ChildFolderCount>
                <t:UnreadCount>0</t:UnreadCount>
              </t:Folder>
            </t:Folders>
          </m:RootFolder>
        </m:FindFolderResponseMessage>
      </m:ResponseMessages>
    </FindFolderResponse>
  </soap:Body>
</soap:Envelope>

Response Elements

The properties that are returned in the response are determined by the BaseShape and the AdditionalProperties if it is used. A successful FindFolder response includes the following elements:

Comments

FindFolder responses to a request with the AllProperties response shape will not return the TotalCount and UnreadCount for public folder searches.

FindFolder Error Response Example

Description

The following SOAP body example shows an error response that occurs when you search for a folder that is identified by a malformed folder identifier.

Code

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Header>
    <t:ServerVersionInfo MajorVersion="8" MinorVersion="0" MajorBuildNumber="652" MinorBuildNumber="0" 
                         xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
      <m:ResponseMessages>
        <m:FindFolderResponseMessage ResponseClass="Error">
          <m:MessageText>Id is malformed.</m:MessageText>
          <m:ResponseCode>ErrorInvalidIdMalformed</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
        </m:FindFolderResponseMessage>
      </m:ResponseMessages>
    </FindFolderResponse>
  </soap:Body>
</soap:Envelope>

Error Response Elements

The FindFolder error response includes the following elements:

Additional Information

  • The folder DisplayName element is always included in the default shape.
  • The UnreadCount element is included in Tasks and Notes folders.
  • Use the PropertyTag value of 0x672D with a property type of Integer to identify a managed folder by using the ExtendedFieldURI element.

See Also

Other Resources

Finding Folders (Exchange Web Services)