Export (0) Print
Expand All

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.

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.

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

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Body>
    <FindFolder Traversal="Shallow" xmlns="http://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>

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.

This FindFolder request includes the following elements:

See the schema for additional FindFolder request elements.

Aa563918.note(en-us,EXCHG.80).gifNote:
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.

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.

Aa563918.note(en-us,EXCHG.80).gifNote:
The folder ID and the change key have been shortened to preserve readability.

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://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="http://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
                        xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
                        xmlns="http://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>

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:

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

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.

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://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="http://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <FindFolderResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" 
                          xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" 
                          xmlns="http://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>

The FindFolder error response includes the following elements:

  • 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.
Show:
© 2015 Microsoft