EWS_Folders

Call

error:=EWS_Folders(ObjectPointer)

Requires

a pointer to an object with at least a ParentFolderId

Does

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.

The ParentFolderID may be any valid folder id or a so called WellKnownFolderName like MsgFolderRoot; PublicFoldersRoot; Inbox; SentItems etc.

Parameters

Required Parameter Object Elements

ParentFolderIdtext Parent FolderId or name of desired DistinctFolder 

The ParentFolderId is either a valid FolderId or a DistinctFolderName.

For no apparent reason, when using WellKnownFolderNames, they need to be passed in lowercase. When using the built-in commands from this component, this is taken care of for you.

Optional Parameter Object Elements

BaseShapetext The BaseShape of the Folder Item, defaults to “Default” 

The BaseShape defines the data set that will be returned for each folder found.
The allowed values are:

  • IdOnly
    Returns only the item or folder ID
  • Default
    Returns a set of properties that are defined as the default for the item or folder
  • AllProperties
    Returns all the properties used by the Exchange Business Logic layer to construct a folder

Parameter Object Example

{
    "ParentFolderId": "msgfolderroot",
    "BaseShape": "IdOnly"
}

Response

Response Object content

The response object contains vital information on the execution of the method and the resulting data in an embedded ARRAY OBJECT

  • ResponseClass
    either Success or Error
  • ResponseCode
    either NoError or an abbreviated error message like ErrorInvalidIdMalformed
  • Count
    The number of folders found
  • MessageText
    In case of an error the verbose error message
  • Folders
    An array of objects with one object per folder found

If the ResponseClass is Error, please check the default error elements in the parameter object and aditionally in the Error object.

Folder Object Content

Each object in the Folders array contains normally this information, unless a different BaseShape has been selected:

  • FolderId
    the unique id of the folder, quite a long string actually…
  • ChangeKey
    another long string you can use to determine if a folder has changed
  • FolderClass
    the folder default content type, possible types are shown further down
  • ItemType
    always “Folder”
  • DisplayName
    the display name of the folder, no surprises here
  • TotalCount
    the total count of items in the folder
  • ChildFolderCount
    the number of child folders
  • UnreadCount
    the number of items that do not have the “read” flag

Some objects may not be present, as Exchange only passes them if they contain meaningful data. In the case of Folders, the “*count” Elements will not be passed if the value would be 0.

Response Object Example

{
    "ParentFolderId": "msgfolderroot",
    "SOAP_Action": "FindFolder",
    "SOAP_Envelope": "<?xml  .... /soap:Envelope>\r",
    "SOAP_Response": "HTTP/1.1 401 .... </s:Envelope>",
    "GetFolderResponse": "<?xml ....</s:Envelope>",
    "XmlRef_Response": "04C30E000698E658",
    "XmlRef_ResponseMessage": "04C30E000698F958",
    "ResponseClass": "Success",
    "ResponseCode": "NoError",
    "Folders": [{
        "FolderType": "CalendarFolder",
        "Id": "AAM....=",
        "ChangeKey": "AgA....x",
        "FolderClass": "IPF.Appointment",
        "DisplayName": "Calendar",
        "TotalCount": "16",
        "ChildFolderCount": "1"
    }, {
        "FolderType": "ContactsFolder",
        "Id": "AAM....=",
        "ChangeKey": "AwA....=",
        "FolderClass": "IPF.Contact",
        "DisplayName": "Contacts",
        "TotalCount": "1",
        "ChildFolderCount": "2"
    }, {
        "FolderType": "Folder",
        "Id": "AAM....=",
        "ChangeKey": "AQA....=",
        "DisplayName": "TestFolder",
        "TotalCount": "0",
        "ChildFolderCount": "0",
        "UnreadCount": "0"
    }],
    "FolderCount": 13
}

Miscellaneous

Useful Folder Classes

Exchange knows an abundance of folder classes, but for all practical purposes we only need to observe these few:

  • IPF.Task
    to-dos
  • IPF.Appointment
    calendar entries
  • IPF.Contact
    contacts
  • IPF.Note
    actually these contain emails … ask Bill why
  • IPF.StickyNote
    the redmond version of post-its
  • IPF.Journal
    no idea what this is, never needed it…

actually each folder class may also contain items of other types, but the folder class determines the “usual” content class… “IPF.Contact.MOC.QuickContacts” I never found these to contain anything useful though so feel free to ignore them.

External References

MSDN : EWS FindFolder Operation

MSDN : EWS DistinctFolderNames

MSDN : EWS BaseShape

Usage example

The following code gets all folders in the main root of the users exchange store – corresponding to the folder view for the account in outlook – and puts the names and ids into arrays

$o_ews:=new Object()
$c_folders:=new Collection()
$o_ews.ParentFolderId:="msgfolderroot"
$l_Error:=EWS_Folders ($o_ews)
case of
    :($l_Error#0)
        //handle the error
    :($o_ews.Folders.length=0)
else
    For each($o_Folder;$o_Params.Folders)
        $c_folders.push($o_Folder.Name)
    End for each
end if
EWS_ObjectClear (->$o_Params;True;True)

XML examples

XML request example

<xml version="1.0"Encoding ="utf-8">
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"   
        mlns: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>

XML success response example

<?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>

XML error response example

<?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>