UpdateFolder operation
Published: July 16, 2012
The UpdateFolder operation is used to modify properties of an existing item in the Exchange store. Each UpdateFolder operation consists of the following:
-
A FolderId element that specifies a folder to update.
-
An internal path of an element in the folder, as specified by the folder shape, which specifies the data to update.
-
A folder that contains the new value of the updated field, if the update is not a deletion.
Three basic update actions can be performed on an item. These actions are listed in the following table.
|
Action |
Description |
|---|---|
|
Append |
The append action adds data to an existing property. It preserves the data that is currently there. Append is not applicable to all properties. |
|
Set |
The set action replaces data for a property if it contains data, or creates the property and sets its value if it does not exist. The set action is only applicable to writable properties. |
|
Delete |
The delete action removes a property from a folder. This is different than setting it to an empty value. When complete, the property does not exist for the folder. Delete is only applicable to writable properties. |
Description
The following example of an UpdateFolder request shows how to update a folder display name.
Code
<?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>
<UpdateFolder xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<FolderChanges>
<t:FolderChange>
<t:FolderId Id="AScA" ChangeKey="GO3u/"/>
<t:Updates>
<t:SetFolderField>
<t:FieldURI FieldURI="folder:DisplayName"/>
<t:Folder>
<t:DisplayName>NewFolderName</t:DisplayName>
</t:Folder>
</t:SetFolderField>
</t:Updates>
</t:FolderChange>
</FolderChanges>
</UpdateFolder>
</soap:Body>
</soap:Envelope>
Comments
This example changes the display name of the folder to NewFolderName.
Note
|
|---|
|
The values of the Id and ChangeKey attributes of the FolderId element have been shortened for readability. |
Request Elements
The following elements are used in the request:
See the schema for additional elements that you can use to form an UpdateFolder request.
|
Note
|
|---|
|
The default location of the schema is in the EWS virtual directory on the computer that has the Client Access server role installed. |
Description
The following example shows a successful response to the UpdateFolder request. In this example, the new change key is returned to reflect the updated status of the folder.
Code
<?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="685" MinorBuildNumber="8"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<UpdateFolderResponse 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:UpdateFolderResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Folders>
<t:Folder>
<t:FolderId Id="AAAlAFVz" ChangeKey="AQAAAB" />
</t:Folder>
</m:Folders>
</m:UpdateFolderResponseMessage>
</m:ResponseMessages>
</UpdateFolderResponse>
</soap:Body>
</soap:Envelope>
Comments
|
Note
|
|---|
|
The folder ID and the change key have been shortened to preserve readability. |
The folder ID that is returned in the response represents the updated folder.
Successful Response Elements
The following elements are used in the response:
Description
The following example shows an error response to an UpdateFolder request.
Code
<?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="685" MinorBuildNumber="8"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<UpdateFolderResponse 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:UpdateFolderResponseMessage ResponseClass="Error">
<m:MessageText>The change key is invalid.</m:MessageText>
<m:ResponseCode>ErrorInvalidChangeKey</m:ResponseCode>
<m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
<m:Folders />
</m:UpdateFolderResponseMessage>
</m:ResponseMessages>
</UpdateFolderResponse>
</soap:Body>
</soap:Envelope>
Comments
This example shows an error response that is caused by an invalid ChangeKey attribute in the request.
Error Response Elements
The following elements are used in the error response:
