Version negotiation in Exchange ActiveSync
In this article
How does the client negotiate the protocol version?
When should the client negotiate the protocol version?
Additional Resources
By Katarzyna Puchala and Matt Stehle
This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers.
The Microsoft Exchange ActiveSync protocol has evolved with each major release of Microsoft Exchange Server from Exchange 2003 to Exchange 2010, and through the numerous service pack releases of those product versions. Version negotiation is the process that an Exchange ActiveSync client uses to evaluate the Exchange ActiveSync protocol versions that are supported by the client and the server, and select the protocol version it will use when communicating with the Exchange server. The process is a "negotiation" because it requires identifying the most recent protocol version that is supported by both the client and the server. We recommend using the most recent version since it offers the richest capabilities that the client can use to its advantage. The client will not be able to use new features supported by newer Exchange ActiveSync protocol versions until it negotiates and upgrades to the newer protocol version.
How does the client negotiate the protocol version?
There are two ways in which the server can indicate to the client which protocol versions it supports, with a response to the HTTP OPTIONS command and in response to the FolderSync command with a SyncKey of 0.
HTTP OPTIONS command
The client first issues the OPTIONS command, and in response the Exchange server sends the MS-ASProtocolVersions header that contains the protocol versions that it supports.
Request
The HTTP OPTIONS command, as defined in [RFC2616], is used to discover what protocol versions are supported, and which protocol commands are supported on the server.
OPTIONS /Microsoft-Server-ActiveSync HTTP/1.1
Host: eas.contoso.com
Response
The MS-ASProtocolVersions header contains a comma-delimited list of version numbers. The following example shows the server response to an HTTP OPTIONS command request. In this example, the value of the MS-ASProtocolVersions header indicates that the server supports Exchange ActiveSync protocol versions 2.0, 2.1, 2.5, 12.0, 12.1, 14.0 and 14.1.
For information about the HTTP OPTIONS response and the MS-ASProtocolVersions header, see [MS-ASHTTP]: ActiveSync HTTP Protocol Specification section 2.2.4.
Based upon the list of values returned by the server, the client should choose the highest version that they both support, and start using it. The client needs to send this version to the server in every POST request.
FolderSync with SyncKey 0
In some cases, firewalls may prevent the server from sending an HTTP OPTIONS command response that contains the MS-ASProtocolVersions header. If the client does not receive the MS-ASProtocolVersions header in the server’s HTTP OPTIONS command response, it should send a FolderSync command request to the server with the SyncKey element value set to 0 (zero). The response from the server will contain the MS-ASProtocolVersions header.
Request
The request must contain MS-ASProtocolVersion header (as mandated in [MS-ASHTTP]: ActiveSync HTTP Protocol Specification section 2.2.1.1.2), which specifies the version of the Exchange ActiveSync protocol that the client prefers to use. For more information about the MS-ASProtocolVersion header, see [MS-ASHTTP]: ActiveSync HTTP Protocol Specification section 2.2.1.1.2.4.
If the client has not yet received the server’s response to its HTTP OPTIONS command request and it does not know which versions of Exchange ActiveSync are supported by the protocol, it may not know which version of the protocol to use in its MS-ASProtocolVersion header. In this case, we recommend that the client uses the most recent version of the Exchange ActiveSync protocol that it supports.
The following example shows a FolderSync command request.
POST /Microsoft-Server-ActiveSync?Cmd=FolderSync&User=kpuchala&DeviceId=MyPhone&DeviceType=SmartPhone HTTP/1.1
Content-Type: application/vnd.ms-sync.wbxml
MS-ASProtocolVersion: 14.1
Host: eas.contoso.com
<?xml version="1.0" encoding="utf-8"?>
<FolderSync xmlns="FolderHierarchy:">
<SyncKey>0</SyncKey>
</FolderSync>
Response
The following example shows the server’s FolderSync command response that will contain the MS-ASProtocolVersions header, allowing the client to select the protocol version. (Some details of the response have been omitted and abbreviated with "…" in this example.)
HTTP/1.1 200 OK
Content-Type: application/vnd.ms-sync.wbxml
MS-ASProtocolVersions: 2.0,2.1,2.5,12.0,12.1,14.0,14.1
MS-ASProtocolCommands: Sync,SendMail,SmartForward,SmartReply,GetAttachment,GetHierarchy,CreateCollection,DeleteCollection,MoveCollection,FolderSync,FolderCreate,FolderDelete,FolderUpdate,MoveItems,GetItemEstimate,MeetingResponse,Search,Settings,Ping,ItemOperations,Provision,ResolveRecipients,ValidateCert
Date: Mon, 12 Mar 2012 23:36:27 GMT
Content-Length: 382
<?xml version="1.0" encoding="utf-8"?>
<FolderSync>
<Status>1</Status>
<SyncKey>1</SyncKey>
<Changes>
<Count>12</Count>
<Add>
<ServerId>1</ServerId>
<ParentId>0</ParentId>
<DisplayName>Calendar</DisplayName>
<Type>8</Type>
</Add>
…
</Changes>
</FolderSync>
For more information about the FolderSync command, see [MS-ASCMD]: ActiveSync Command Reference Protocol Specification section 2.2.2.4.
There is no specific server-side error code that indicates that the client used a more recent version of the protocol for the particular Exchange server. If the server responds with an HTTP error code 400 ("Bad request"), it may mean that the server does not support the Exchange ActiveSync protocol version that the client used. In this case, the client should attempt to communicate with the Exchange server by using the previous Exchange ActiveSync protocol version, and should continue this process (using an earlier Exchange ActiveSync protocol version each time), until the server sends a success response.
When should the client negotiate the protocol version?
When a client communicates with an Exchange server for the first time, it should send an HTTP OPTIONS command to the server to get the MS-ASProtocolVersions header value that specifies the Exchange ActiveSync protocol versions supported by the server. Following this initial communication, the client should perform version negotiation periodically to determine if the Exchange ActiveSync protocol versions supported by the server have changed. Two scenarios may change the protocol versions that the server supports: server upgrades and server downgrades.
Detecting server upgrades
Newer versions of Exchange Server support nearly all previous versions of the Exchange ActiveSync protocol (the current exception is version 1.0). A server upgrade is often not obvious to the client. For example, if the client initially negotiates with an Exchange 2007 server with Service Pack 1 applied and decides to use Exchange ActiveSync version 12.1, and the server is subsequently upgraded to Exchange 2010, the client can continue using Exchange ActiveSync version 12.1 without issues. While it is nice that Exchange 2010 is backward compatible (that is, it supports previous versions of the Exchange ActiveSync protocol), the client will not be able to use new features supported by Exchange ActiveSync version 14.0 until it renegotiates and upgrades to using the most recent protocol version. With this in mind, the client should perform version negotiation periodically to detect a server upgrade—checking once every 24 hours is a reasonable interval. If the client detects a more recent version, the client should re-sync the entire partnership.
Note If the client is already using the most recent protocol version it supports, it does not need to check for server upgrades.
Detecting server downgrades
Server downgrades are easily detectable when the server does not support the currently negotiated Exchange ActiveSync protocol version. In this scenario, the server will respond with HTTP status code 400 ("Bad request"). If the client subsequently performs the OPTIONS command or the FolderSync command returns the revised protocol version list, then the client should treat is as a server downgrade. In this scenario, the client should also negotiate the new version for the new partnership and then re-sync everything.
Additional Resources
For more information, see the following resources: