In November and December 2011, Exchange content made its debut on the Learn Open Specifications and Interoperability page in the Open Specifications Developer Center:

The updates include nine new Microsoft Exchange Learning Modules:

• Getting Started
• The Mailbox, Folders, and Public Storage
• Messages and Attachments
• Calendars
• Contacts and Address Books
• Tasks, Documents, and Notes
• Inbox Rules and Spam Filtering
• Synchronization
• Search and Miscellaneous

While you’re on the Learn tab exploring the new Exchange learning modules, don’t miss the Open Specifications Interactive Pivot, which also includes Exchange open specifications documents. We’re very excited about the Pivot, which makes it easy to find the open specifications documents you need in a visual, intuitive way. The Pivot uses Silverlight Deep zoom technology, which lets you visually search and filter the open specifications documents. Once you use it, you’ll see why we’re excited.

Are you ready? The EWS Managed API 1.2 documentation is now available, so let the preparation, planning, and architecting begin. The new EWS Managed API will have some updates that you may want to incorporate into your application. Take a look at the What’s New topic to learn more about the new content that is available to support the new EWS Managed API 1.2 functionality. Take a look at the Exchange Web Services Managed API 1.2 SDK topic to learn about the new EWS Managed API 1.2 functionality. 

Did you say “Where is the API download?” It’s coming soon. We are releasing the documentation earlier than usual so that you can get a jump on your planning for the next update of your EWS client application. So go have a feature review, maybe update your design specs, and get ready to implement your next update to your EWS client application.

Exchange Web Services (EWS) is a robust API that exposes many Exchange client access features. Many popular clients use this API on many different platforms. What if you want to limit client access via EWS, however? You do have an option. In Exchange 2010, you can use the Set-CASMailbox command to modify EWS access.

Note:   The Set-CASMailbox command in Exchange 2007 does not provide options for limiting EWS access.

The following options that the Set-CASMailbox command exposes enable you to change the settings on a per-user basis:

• Turn EWS on/off
• Turn EWS on/off for Outlook, Mac Outlook, and Entourage
• Turn EWS on/off using allow/block lists for user agent filtering

These options make use of the user agent header to filter access. While useful in many scenarios, user agent filtering has one  inherent disadvantage: User agent strings can easily be written to represent agents on an allowed list, including Outlook, Mac Outlook, and Entourage. Of equal importance is the fact that specific EWS features can’t be blocked. EWS feature access is not segmented to allow access to particular EWS operations — it’s all or nothing. Turning off EWS will affect clients that use the OOF settings, availability, mail tips, and so on. It is important to take this into consideration when planning the client-server interaction part of your system architecture.

UPDATE: 8 November 2011, Thom Randolph - MSFT.

The following API reference information in this post applies to the Windows Extensible Storage Engine (ESE) APIs, that are available on MSDN at the following URL:

http://msdn.microsoft.com/en-us/library/windows/desktop/gg269259(v=EXCHG.10).aspx

The ESE APIs that ship in Windows should not be used with Exchange mailbox or public folder databases.

The JET_ERRINFOBASIC_W API includes a group of constants, a structure, and a function, as defined in the header file Esent.h. These are described in this blog post.

Note: This documentation is based on a preliminary release of the Extensible Storage Engine. This information is subject to change.

JET_ERRCAT Constants

The JET_ERRCAT group of constants describes higher-level classifications or categories of errors. This group of constants enables applications to define default treatment for a classification of errors, rather than handling each error case individually. It also ensures that the application does not have to handle new error conditions that are included in existing classifications.

The JET_ERRCAT constants are arranged in a specific hierarchy of conditions and subconditions, as follows:

|--- Error
|--- Operation(al)
| |--- Fatal
| |--- IO
| |--- Resource
| |--- Memory
| |--- Quota
| |--- Disk
|
|--- Data
| |--- Corruption
| |--- Inconsistent
| |--- Fragmentation
|
|--- Api
|--- Usage
|--- State

The following table lists the JET_ERRCAT constants and provides a description and recovery information, as applicable.

Requirements

JET_ERRINFOBASIC_W Structure

The JET_ERRINFOBASIC_W structure defines the data that is returned from the JetGetErrorInfo() method when the JET_ErrorInfoSpecificErr InfoLevel [LG1] is passed in.

typedef struct {
         unsigned long    cbStruct;
         JET_ERR          errValue;
         JET_ERRCAT       errcatMostSpecific;
         unsigned char    rgCategoricalHierarchy[8];
         unsigned long    lSourceLine;
         WCHAR            rgszSourceFile[64];
} JET_ERRINFOBASIC_W;

Members

cbStruct
The size of the structure, in bytes. It must be set to sizeof( JET_ERRINFOBASIC ).

errValue
The error value that was evaluated, as passed in for the pvResult argument to JetGetErrorInfo().

errcatMostSpecific
The lowest-level JET_errcat constant that is associated with the error; that is, the leaf-level category in the category hierarchy documented in JET_ERRCAT.

rgCategoricalHierarchy[8]
The hierarchy of error categories that is associated with the error. Position 0 is the highest level in the hierarchy of JET_ERRCAT, and the rest are subcategories until the most specific category is set, after which all categories are JET_errcatUnknown.

lSourceLine
Reserved.

rgszSourceFile[64]
Reserved.

Requirements

JetGetErrorInfoW Function

The JetGetErrorInfoW function BAS_ of the database engine.

JET_ERR JET_API JetGetErrorInfoW(
         _In_opt_ void *                    pvContext,
         _Out_writes_bytes_( cbMax ) void * pvResult,
         _In_ unsigned long                 cbMax,
         _In_ unsigned long                 InfoLevel,
         _In_ JET_GRBIT                     grbit );

Parameters

pvContext
The context or error value for which the extended error information is needed. The value passed in depends on the InfoLevel parameter value.

pvResult
A pointer to a buffer that will receive the information. The type of the buffer depends on the InfoLevel parameter value. The caller must be configured to align the buffer appropriately.

cbMax
The maximum size of the pvResult structure that is passed in.

InfoLevel
The type of information that will be retrieved for the error info/context is specified by the pvContext parameter. The format of the data that is stored in pvResult is dependent on InfoLevel.

The following table lists the possible values for this parameter.

grbit
Reserved.

Return Value

This function returns the JET_ERR data type with one of the return codes listed in the following table. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

On success, the output buffer that is appropriate for the requested error context/value will be set to the extended error info requested.

On failure, the state of the output buffers will be undefined.

Remarks

The JET_ERRINFOBASIC_W function and JET_ERRCAT group of constants contain documentation about the extended error information that is returned for InfoLevel = JET_ErrorInfoSpecificErr.

Requirements

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers.

Microsoft Exchange ActiveSync policies are the primary tool by which IT administrators can manage devices that connect to Microsoft Exchange mailboxes. Administrators can create policy settings to manage security settings such as PIN length, data encryption, and so on. Policies define the terms by which a client can synchronize mailbox data. The provisioning process is a communication that occurs between the client and server that indicates whether the client can enforces the required policies.

In addition to policies, Microsoft Exchange Server 2010 introduces another tool for administrators, known as Allow/Block/Quarantine (ABQ). ABQ enables administrators to control which devices or families of devices can synchronize data with Exchange ActiveSync. Administrators can also use ABQ to block certain devices or all unknown devices from synchronizing data.

Both ABQ and policies help administrators control how and whether data is synchronized onto a device. Remote Wipe is another Exchange ActiveSync feature that is used to remove data from a device. This feature is important when, for example, individuals leave the company, or a device is lost or stolen.

If you are creating an enterprise-class Exchange ActiveSync client, it is important for you to understand and support provisioning and policies, ABQ, and remote wipe. This post provides the information you need to know about these features, in the following sections:

• Provisioning
• Policies
• Remote wipe
• ABQ

Provisioning

The client’s goal in provisioning is to obtain a policy key from the Exchange server. This policy key enables the client to synchronize with a mailbox. Provisioning involves the following steps:

• The client sends information to the server to identify itself.
• The server sends security policies to the client that the client must enforce.
• The client indicates whether it is able to enforce the security policies.
• If the policies are applied successfully, the client is given a policy key that it then submits with subsequent requests to synchronize the mailbox.

For a detailed description of this process, see [MS-ASPROV]: ActiveSync Provisioning Protocol Specification section 3.1.5.1.

The following figure shows the two-step provisioning process.

Figure 1: Two-step provisioning process

Provisioning step 1: policy exchange between client and server

The policy exchange process involves a client Provision command request and a server Provision command response.

Client provisioning request

In its first request to the Exchange server, the client sends a Provision command request, as shown in the following example.

POST /Microsoft-Server-ActiveSync?User=deviceuser&DeviceId=6F24CAD599A5BF1A690246B8C68FAE8D&DeviceType=PocketPC&Cmd=Provision HTTP/1.1

Accept-Language: en-us

MS-ASProtocolVersion: 14.0

Content-Type: application/vnd.ms-sync.wbxml

X-MS-PolicyKey: 0

User-Agent: ASOM

Host: EXCH-B-003

 

<?xml version="1.0" encoding="utf-8"?>

<Provision xmlns="Provision:" xmlns:settings="Settings:">

    <settings:DeviceInformation>

        <settings:Set>

            <settings:Model>… </settings:Model>

            <settings:IMEI>...</settings:IMEI>

            <settings:FriendlyName>...</settings:FriendlyName>

            <settings:OS>...</settings:OS>

            <settings:OSLanguage>...</settings:OSLanguage>

            <settings:PhoneNumber>...</settings:PhoneNumber>

            <settings:MobileOperator>...</settings:MobileOperator>

            <settings:UserAgent>...</settings:UserAgent>

        </settings:Set>

    </settings:DeviceInformation>

     <Policies>

          <Policy>

               <PolicyType>MS-EAS-Provisioning-WBXML</PolicyType>

          </Policy>

     </Policies>

</Provision>

The client Provision command request includes information contained within two parent elements:

• settings:DeviceInformation element
• Policies element

I will discuss the settings.DeviceInformation element in more detail in the "ABQ" section later in this post.

In the Policies element section, the client indicates in the PolicyType element the format of the policy information that the client wants the server to use. The client should always send the “MS-EAS-Provisioning-WBXML” value, as described in [MS-ASPROV] section 2.2.2.42.

Provisioning request for different Exchange ActiveSync protocol versions

The use of the settings:DeviceInformation element in the provisioning request varies based on the version of the Exchange ActiveSync protocol the client is using, as described in the following table.

For more information about the differences between Exchange ActiveSync protocol versions in client provisioning requests, see [MS-ASPROV] section 6.

Server provisioning response

The following example shows a server response to a client provisioning request.

Note: The policies listed in this example do not represent all the possible policies that the server might send. For a complete list of policies, see [MS-ASPROV] section 2.2.2.

HTTP/1.1 200 OK

Connection: Keep-Alive

Content-Length: 1069

Date: Mon, 01 May 2006 20:15:15 GMT

Content-Type: application/vnd.ms-sync.wbxml

Server: Microsoft-IIS/6.0

X-Powered-By: ASP.NET

X-AspNet-Version: 2.0.50727

MS-Server-ActiveSync: 8.0

Cache-Control: private

 

<?xml version="1.0" encoding="utf-8"?>

<Provision xmlns:A0="AirSync:" xmlns:A1="POOMCONTACTS:" xmlns:A2="POOMMAIL:" xmlns:A3="AirNotify:" xmlns:A4="POOMCAL:" xmlns:A5="Move:" xmlns:A6="GetItemEstimate:" xmlns:A7="FolderHierarchy:" xmlns:A8="MeetingResponse:" xmlns:A9="POOMTASKS:" xmlns:A10="ResolveRecipients:" xmlns:A11="ValidateCert:" xmlns:A12="POOMCONTACTS2:" xmlns:A13="Ping:" xmlns:A15="Search:" xmlns:A16="Gal:" xmlns:A17="AirSyncBase:" xmlns:A18="Settings:" xmlns:A19="DocumentLibrary:" xmlns:A20="ItemOperations:" xmlns:A21="ComposeMail:" xmlns:A22="POOMMAIL2:" xmlns:A23="Notes:" xmlns:A24="RightsManagement:" xmlns="Provision:">

  <Status>1 Success</Status>

  <Policies>

    <Policy>

      <PolicyType>MS-EAS-Provisioning-WBXML</PolicyType>

      <Status>1 Success</Status>

      <PolicyKey>2488355417</PolicyKey>

      <Data>

        <eas-provisioningdoc>

          <DevicePasswordEnabled>1</DevicePasswordEnabled>

          <AlphanumericDevicePasswordRequired>0</AlphanumericDevicePasswordRequired>

          <PasswordRecoveryEnabled>0</PasswordRecoveryEnabled>

          <RequireStorageCardEncryption>0</RequireStorageCardEncryption>

          <AttachmentsEnabled>1</AttachmentsEnabled>

          <MinDevicePasswordLength>4</MinDevicePasswordLength>

          <MaxInactivityTimeDeviceLock>900</MaxInactivityTimeDeviceLock>

          <MaxDevicePasswordFailedAttempts>8</MaxDevicePasswordFailedAttempts>

          <MaxAttachmentSize/>

          <AllowSimpleDevicePassword>1</AllowSimpleDevicePassword>

          <DevicePasswordExpiration/>

          <DevicePasswordHistory>0</DevicePasswordHistory>

          <AllowStorageCard>1</AllowStorageCard>

          <AllowCamera>1</AllowCamera>

          <RequireDeviceEncryption>0</RequireDeviceEncryption>

          <AllowUnsignedApplications>1</AllowUnsignedApplications>

          <AllowUnsignedInstallationPackages>1</AllowUnsignedInstallationPackages>

          <MinDevicePasswordComplexCharacters>1</MinDevicePasswordComplexCharacters>

          <AllowWiFi>1</AllowWiFi>

          <AllowTextMessaging>1</AllowTextMessaging>

          <AllowPOPIMAPEmail>1</AllowPOPIMAPEmail>

          <AllowBluetooth>2</AllowBluetooth>

          <AllowIrDA>1</AllowIrDA>

          <RequireManualSyncWhenRoaming>0</RequireManualSyncWhenRoaming>

          <AllowDesktopSync>1</AllowDesktopSync>

          <MaxCalendarAgeFilter>0</MaxCalendarAgeFilter>

          <AllowHTMLEmail>1</AllowHTMLEmail>

          <MaxEmailAgeFilter>0</MaxEmailAgeFilter>

          <MaxEmailBodyTruncationSize>-1</MaxEmailBodyTruncationSize>

          <MaxEmailHTMLBodyTruncationSize>-1</MaxEmailHTMLBodyTruncationSize>

          <RequireSignedSMIMEMessages>0</RequireSignedSMIMEMessages>

          <RequireEncryptedSMIMEMessages>0</RequireEncryptedSMIMEMessages>

          <RequireSignedSMIMEAlgorithm>0</RequireSignedSMIMEAlgorithm>

          <RequireEncryptionSMIMEAlgorithm>0</RequireEncryptionSMIMEAlgorithm>

          <AllowSMIMEEncryptionAlgorithmNegotiation>2</AllowSMIMEEncryptionAlgorithmNegotiation>

          <AllowSMIMESoftCerts>1</AllowSMIMESoftCerts>

          <AllowBrowser>1</AllowBrowser>

          <AllowConsumerEmail>1</AllowConsumerEmail>

          <AllowRemoteDesktop>1</AllowRemoteDesktop>

          <AllowInternetSharing>1</AllowInternetSharing>

          <UnapprovedInROMApplicationList/>

          <ApprovedApplicationList/>

        </eas-provisioningdoc>

      </Data>

    </Policy>

  </Policies>

</Provision>

The response includes the following:

• A PolicyKey element, which contains a policy key that the client should retain and submit to the server with its next request.
• A Data element and its child elements, which contain the policy settings that the server requires the client to apply. For more information about individual policy settings, see "Policies" later in this blog post.

Notice that the response contains two Status elements. The first Status element is a child of the Provision element and indicates the general status of the Exchange server’s ability to process the client’s request. The following table lists the possible values for the first Status element.

The second Status element is a child of the Policy element and indicates whether the policy settings were applied correctly. The following table lists the possible values for the Status element.

Provisioning step 2: client acknowledges and applies policies

At this point, the server relies on the client to apply the policies as requested. After applying the security policy settings, the client sends another Provision command request to the server to acknowledge the policies and indicate its ability to apply them on the device.

The following example shows the second Provision request that the client sends to the server.

POST /Microsoft-Server-ActiveSync?User=deviceuser&DeviceId=6F24CAD599A5BF1A690246B8C68FAE8D&DeviceType=PocketPC&Cmd=Provision HTTP/1.1

Accept-Language: en-us

MS-ASProtocolVersion: 14.0

Content-Type: application/vnd.ms-sync.wbxml

X-MS-PolicyKey: 1307199584

User-Agent: ASOM

Host: EXCH-B-003

 

<?xml version="1.0" encoding="utf-8"?>

<Provision xmlns="Provision:">

     <Policies>

          <Policy>

               <PolicyType>MS-EAS-Provisioning-WBXML</PolicyType>

 <PolicyKey>1307199584</PolicyKey>

               <Status>1</Status>

          </Policy>

     </Policies>

</Provision>

This request contains the policy key value that the server sent to the client in step 1. It also contains a Status element that indicates whether the client was able to apply the policy settings. The following table lists the possible values of the Status element.

Note: If a Microsoft Exchange administrator sets the "Allow non-provisionable devices" option in the Exchange ActiveSync policy, the server will allow all clients to synchronize mailbox data regardless of whether the client asked for policy settings or applied them successfully. However, if the administrator chooses to disable the "Allow non-provisionable devices" option, only clients that respond with "Success" are allowed to connect to the mailbox.

Note: If the DevicePasswordEnabled policy is set to true, and the device is not able to enforce the password, it must return "failure" in response to the Provision command, regardless of whether it can enforce any other policy. The client can return "partial success" if it cannot enforce any other policies. For example, if the client enabled a password but failed to encrypt the device, it can return "partial success" rather than "failure".

The following example shows the server's response to the second client Provision request.

HTTP/1.1 200 OK

Connection: Keep-Alive

Content-Length: 63

Date: Mon, 01 May 2006 20:15:17 GMT

Content-Type: application/vnd.ms-sync.wbxml

Server: Microsoft-IIS/6.0

X-Powered-By: ASP.NET

X-AspNet-Version: 2.0.50727

MS-Server-ActiveSync: 8.0

Cache-Control: private

 

<?xml version="1.0" encoding="utf-8"?>

<Provision xmlns="Provision:">

     <Status>1</Status>

     <Policies>

          <Policy>

               <PolicyType> MS-EAS-Provisioning-WBXML </PolicyType>

               <Status>1</Status>

               <PolicyKey>3942919513</PolicyKey>

          </Policy>

     </Policies>

</Provision>

This response does not include a Data element that contains the list of policy settings. The server simply responds with a Status element (the values for which are listed in the "Server provisioning response" section) and a new policy key. This new policy key is the permanent key that the client should save and resubmit when it sends subsequent requests to the server.

Client handling of the policy key

The policy key represents the current security policy settings that are applied on the client. It can be up to 64 characters long and can contain any of the characters that are allowed in an HTTP header. The client should retain only the latest policy key that it has received from the server and submit it with all requests.

Note: Submitting the policy key is optional the Ping command and the HTTP OPTIONS commands.

The following example shows a client request that includes the policy key.

POST /Microsoft-Server-ActiveSync?User=deviceuser&DeviceId=6F24CAD599A5BF1A690246B8C68FAE8D&DeviceType=PocketPC&Cmd=FolderSync HTTP/1.1

Accept-Language: en-us

MS-ASProtocolVersion: 14.0

Content-Type: application/vnd.ms-sync.wbxml

X-MS-PolicyKey: 3942919513

User-Agent: ASOM

Host: EXCH-B-003

 

<?xml version="1.0" encoding="utf-8"?>

<FolderSync xmlns="FolderHierarchy:">

     <SyncKey>0</SyncKey>

</FolderSync>

When should a client provision?

Clients should send a Provision command request when they first contact the server. In some scenarios, the server may require the client to provision again, after an initial provision sequence. The server indicates this by sending a 449 HTTP error response or a success response with one of the status codes listed in the following table in response to any client request. The client should immediately send a Provision command request after receiving one of these statuses in a response.

In version 12.1 of the Exchange ActiveSync protocol, the server only sends an HTTP 449 response to inform the client that it needs to provision; it does not send the status codes listed in the previous table. Because this error response does not enable the client to distinguish between transient and potentially nontransient provisioning errors, the client should try to provision. If subsequent requests fail with additional HTTP 449 error respon ses, the client should suggest that the user contact their administrator. At that point, the client may choose to try to provision once per hour to determine whether the policy has changed.

Policies

Because it is up to the client to enforce policies, it is important to understand the effects that each policy will have on the device when applied. For a list of the elements that contain policy information, see [MS-ASPROV] section 2.2.2. This information will help you to determine acceptable values and expected results for each policy. For more information about policies in general, see Understanding Exchange ActiveSync Mailbox Policies on Microsoft TechNet.

This section lists and describes some of the policies that are available; it does not provide a comprehensive list of all policies. For more information about policies, see [MS-ASPROV].

The following table lists policies that clients can ignore and describes the conditions in which they can be ignored. If the conditions apply, the client can return "success" although the policy is not applied. Policies that are not listed in this table cannot be ignored under any conditions.

The following table lists additional policies and describes the expected behavior:

Remote Wipe

The remote wipe process enables administrators to request that the client erase all data from a device. Remote wipe is used in scenarios in which a device is lost or stolen or when a user has left the company or no longer has permission to synchronize corporate data. Administrators can use the Exchange Management Shell or the Exchange Management Console (EMC) to request a remote wipe. For more information, see Understanding Remote Device Wipe on Microsoft TechNet.

After an administrator requests a remote wipe, the next time the client sends a request to the server, the server will respond with status code 140, RemoteWipeRequested. The client should then submit a Provision command request. If the server's response contains a RemoteWipe element, the client should send an acknowledgement that it is about to wipe the device first. Because the wipe will erase all data from memory and storage, the client sends the acknowledgement first because it will not have the information it needs to send requests after it wipes the device. For examples of the requests and responses that are sent during the remote wipe process, see [MS-ASPROV] section 4.2.

The following is an example of a server response to a Provision command request that includes a RemoteWipe element.

Content-Type: application/vnd.ms-sync.wbxml

Date: Wed, 25 Mar 2009 01:23:58 GMT

Content-Length: 14

 

<?xml version="1.0" encoding="utf-8"?>

<Provision>

<Status>1</Status>

<RemoteWipe />

</Provision>

The following example shows a Provision command request from the client that contains the remote wipe status.

POST /Microsoft-Server-ActiveSync?Cmd=Provision&User=T0SyncUser1v14.0&DeviceId=Device1&DeviceType=PocketPC HTTP/1.1

Content-Type: application/vnd.ms-sync.wbxml

MS-ASProtocolVersion: 14.0

X-MS-PolicyKey: 0

User-Agent: ASOM

Host: EXCH-B-003

 

<?xml version="1.0" encoding="utf-8"?>

<Provision xmlns="Provision:">

    <RemoteWipe>

        <Status>1</Status>

    </RemoteWipe>

</Provision>

The client should include one of the following values in the Status element:

• 1 (Success) — Indicates that the client will wipe the device shortly after sending.
• 2 (Failure) — Indicates that the client could not wipe the device.

ABQ

Allow/Block/Quarantine (ABQ) is a new feature introduced in Exchange 2010 that enables administrators to control device access to mailboxes based on device type. While provisioning and policies focus on managing device features such as passwords, cameras, encryption, and so on, ABQ simply controls access to the mailbox. Administrators use ABQ along with policies to manage Exchange ActiveSync clients. For more information, see Controlling Exchange ActiveSync device access using the Allow/Block/Quarantine list on the Exchange Team Blog.

Microsoft Exchange manages access to the mailbox through ABQ by using device information that it relies on the client to provide. The client sends this information in the Provision command request or as part of the Settings command, as shown in the following example.

<?xml version="1.0" encoding="utf-8"?>

<Settings xmlns="Settings:">

    <DeviceInformation>

        <Set>

            <Model>CONTOSO</Model>

            <IMEI>123456789012345</IMEI>

            <FriendlyName>Matt's Phone</FriendlyName>

            <OS>Contoso Phone1.0.1234</OS>

            <OSLanguage>English</OSLanguage>

            <PhoneNumber>555-555-1234</PhoneNumber>

            <MobileOperator>ContosoTelecom</MobileOperator>

            <UserAgent>ContosoPhone1</UserAgent>

            <EnableOutboundSMS>1</EnableOutboundSMS>

        </Set>

    </DeviceInformation>

</Settings>

The elements set by the client are listed in the following table:

Related Resources

[MS-ASCMD]: ActiveSync Command Reference Protocol Specification

[MS-ASPROV]: ActiveSync Provisioning Protocol Specification

Understanding Exchange ActiveSync Mailbox Policies

Understanding Remote Device Wipe

Controlling Exchange ActiveSync device access using the Allow/Block/Quarantine list

Post authored by: Matt Stehle, Microsoft Corporation

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers. This post applies to Exchange ActiveSync protocol version 14.1. Where applicable, differences between protocol versions are noted.

The ability to respond to meeting requests is an important aspect of collaboration and communication for Microsoft Exchange users. Responses to meeting requests inform meeting organizers of invitees' attendance status and automatically book the time on attendees' Calendars. This post provides information for developers about working with meeting responses, including the following topics:

• How the Exchange ActiveSync client responds to meeting requests.
• How the Exchange ActiveSync client should interpret responses to meetings organized by the client user.

For information about working with meeting requests, see the blog post Working with Meeting Requests in Exchange ActiveSync.

The following figure shows an overview of the meeting response process and the two key scenarios involved. In this example, Exchange ActiveSync user Bob has received a meeting invitation from the organizer, Alice, on his Exchange ActiveSync client. Bob responds to the meeting request using his Exchange ActiveSync device and Alice can verify his response status using her device.

Figure 1:   Meeting response process

This post does not cover adding the meeting request email message to the invitee's Inbox and a creating tentative placeholder item on the invitee's Calendar. For information about the meeting request process, see Working with Meeting Requests in Exchange ActiveSync.

Scenario 1: Invitee uses an Exchange ActiveSync client to respond to a meeting request

In our example, an invitee, Bob, finds a meeting request from Alice waiting in his Inbox, and a placeholder Calendar item tentatively marking the time of the meeting on his Calendar. Bob can choose to accept, tentatively accept, or decline the meeting and send his response to the organizer from either the meeting invitation in his Inbox or the Calendar placeholder item. Bob accepts the meeting request by using the options provided by the meeting request email displayed on his Exchange ActiveSync client. The Exchange server then deletes the meeting request from his Inbox and changes the status of the placeholder Calendar item from tentative to busy. In addition, the Exchange ActiveSync client sends a meeting acceptance notification to the organizer. A copy of this message appears in Bob's Sent Items folder.

The following figure shows the Exchange ActiveSync client meeting response process.

Figure 2:   Exchange ActiveSync client meeting response process

Responding to meeting requests involves the following steps:

1. The user, in this case Bob, accepts the meeting from his Exchange ActiveSync client by using the options exposed in the meeting request. Upon doing so, the following takes place:
   1. The server deletes the meeting request email message from his Inbox.
   2. The server deletes the tentative meeting from his Calendar and adds an accepted meeting in its place.

Note:   If Bob's Exchange server is not configured to process incoming meeting requests automatically, a tentative meeting placeholder item does not appear on his Calendar. In this case, the server does not delete any Calendar item, and the MeetingResponse command cannot be sent from the Calendar folder; it can be used on the meeting request in the Inbox only.

1. When Bob issues a Sync command on Calendar folder, the tentative meeting is deleted from the Calendar by the Exchange  server, and a new accepted meeting is added.

Note:   If Bob syncs his Deleted Items folder, a copy of the original meeting item is added to that folder. (This step is not shown in Figure 2 and is not described in this blog post.)

1. Bob's client sends an email message to the organizer that indicates his acceptance.
2. The server adds a copy of the meeting acceptance email message in Bob's Sent Items folder. If Bob syncs his Sent Items folder, a copy of the notification will appear there.

 When the ResponseRequested element is set to 1, the Exchange ActiveSync client allows the user to act on the meeting request from both the Inbox and the Calendar item.

Responding to meeting requests from the Inbox

When the client displays a meeting request message in a user's Inbox, the user has the option to accept, tentatively accept, or decline the meeting invitation. After the user selects a response, the client sends a MeetingResponse command to the server.

MeetingResponse command

The following example shows a MeetingResponse command request.

POST /Microsoft-Server-ActiveSync?Cmd=MeetingResponse&User=Bob&DeviceId=ABCDEF&DeviceType=SmartPhone HTTP/1.1

Content-Type: application/vnd.ms-sync.wbxml

MS-ASProtocolVersion: 14.1

User-Agent: ASOM

Host: mail.contoso.com

 

<?xml version="1.0" encoding="utf-8"?>

<MeetingResponse xmlns="MeetingResponse:">

  <Request>

    <UserResponse>1</UserResponse>

    <CollectionId>6</CollectionId>

    <RequestId>6:17</RequestId>

  </Request>

</MeetingResponse>

The RequestId element specifies the server ID of the meeting request in the Inbox collection. The UserResponse element can contain one of the values listed in the following table.

Server response to the MeetingResponse command

After the MeetingResponse command has finished, the server automatically deletes the meeting request item from the Inbox. The following example shows the server response.

HTTP/1.1 200 OK

MS-Server-ActiveSync: 14.0

 

<?xml version="1.0" encoding="utf-8" ?>

<MeetingResponse xmlns="MeetingResponse:">

  <Result>

    <RequestId>6:17</RequestId>

    <Status>1</Status>

    <CalendarId>2:25</CalendarId>

  </Result>

</MeetingResponse>

The RequestId element specifies the meeting request that the client is responding to. If the meeting invitation is accepted or tentatively accepted, the server adds or updates the corresponding Calendar item and returns the item's server ID in the CalendarId element of the response.

The following table lists the possible values for the Status element.

Note:   The Exchange ActiveSync client should handle the response to the MeetingResponse command in the same way that it handles the status responses to email commands.

When an invitee responds from the Inbox item, the Exchange server deletes the meeting invitation from the Inbox. The invitee can, however, change their response to the meeting request from the Calendar item with new MeetingResponse command. If the user declines the meeting, the server deletes the Calendar item, and it can no longer be used to respond to the meeting request.

The Exchange server automatically deletes the email invitation from the Inbox after the user has responded to the request. When the Exchange ActiveSync client syncs the Deleted Items folder, the deleted item is automatically added to the Deleted Items folder on the client.

Responding to meeting requests from the Calendar folder

Users respond to a meeting request from the Calendar folder in the same way that they respond to the request from the Inbox. The client uses the MeetingResponse command, but in this case, the RequestId element value indicates the Calendar item. This option is only available in Exchange ActiveSync version 14.0 and later versions. Just like when the user responds from the Inbox, the meeting request item in the Inbox is automatically deleted by the server when the user responds from the Calendar item.

Replacing the placeholder Calendar item with a new item

When the user responds to the meeting request, the original tentative Calendar item is deleted. If the user declines the meeting request, the server does not add a new item to the Calendar. If the user accepts or tentatively accepts the meeting request, the server creates a new Calendar item with the status as indicated by the user. The following example shows the sync process for the Calendar collection, after the user has accepted the meeting request. The original meeting item is deleted, and new item with a status of Accepted is added in its place. The UID element value of the new accepted item is identical to the value of the tentative placeholder item.

HTTP/1.1 200 OK

Content-Type: application/vnd.ms-sync.wbxml

 

<?xml version="1.0" encoding="utf-8"?>

<Sync >

  <Collections>

    <Collection>

      <SyncKey>1598194209</SyncKey>

      <CollectionId>2</CollectionId>

      <Status>1</Status>

      <Commands>

        <Add>

          <ServerId>2:25</ServerId>

          <ApplicationData>

            <calendar:TimeZone>4AEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

              AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAsAAAABAA

              IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

              AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMAAAACAAIAAA

              AAAAAAxP///w==</calendar:TimeZone>

            <calendar:DtStamp>20110510T185139Z</calendar:DtStamp>

            <calendar:StartTime>20110510T170000Z</calendar:StartTime>

            <calendar:Subject>Quarterly Planning</calendar:Subject>

            <calendar:UID>A3561BDAAE8E4B30AC255FD3F31A3AD7000000000000000000000

              00000000000</calendar:UID>

            <calendar:OrganizerName>Alice </calendar:OrganizerName>

            <calendar:OrganizerEmail>alice@contoso.com</calendar:OrganizerEmail>

            <calendar:Attendees>

              <calendar:Attendee>

                <calendar:Email>bob@contoso.com</calendar:Email>

                <calendar:Name>Bob </calendar:Name>

                <calendar:AttendeeType>1</calendar:AttendeeType>

              </calendar:Attendee>

            </calendar:Attendees>

            <calendar:Location>Office</calendar:Location>

            <calendar:EndTime>20110510T180000Z</calendar:EndTime>

            <airsyncbase:Body>

              <airsyncbase:Type>1</airsyncbase:Type>

              <airsyncbase:EstimatedDataSize>127</airsyncbase:EstimatedDataSize>

              <airsyncbase:Truncated>1</airsyncbase:Truncated>

            </airsyncbase:Body>

            <calendar:Sensitivity>0</calendar:Sensitivity>

            <calendar:BusyStatus>2</calendar:BusyStatus>

            <calendar:AllDayEvent>0</calendar:AllDayEvent>

            <calendar:Reminder>15</calendar:Reminder>

            <calendar:MeetingStatus>3</calendar:MeetingStatus>

            <airsyncbase:NativeBodyType>3</airsyncbase:NativeBodyType>

            <calendar:ResponseRequested>1</calendar:ResponseRequested>

            <calendar:AppointmentReplyTime>20110506T165252Z</AppointmentReplyTime>

            <calendar:ResponseType>3</calendar:ResponseType>

          </ApplicationData>

        </Add>

        <Delete>

          <ServerId>2:24</ServerId>

        </Delete>

     </Commands>

    </Collection>

  </Collections>

</Sync>

The client has to sync the Calendar folder after the user accepts or tentatively accepts a meeting request in order for the new Calendar item to appear on the user's Calendar.

Deleting the Calendar item when the meeting is declined

If the user declines the meeting, the Exchange server automatically deletes the corresponding Calendar item. The client must not delete the Calendar item on behalf of the user.

When a user declines a meeting request, the response does not contain a meetingresponse:CalendarId element because the server deletes the corresponding Calendar item.

Sending response notifications

The client sends a notification to the meeting organizer if the user chooses to send a response. The client uses the SendMail command to send the notification. The client should send the email notification only after the MeetingResponse command finishes successfully; otherwise, the invitee's Calendar and the status information that the invitee reports to the organizer will be in conflict. If the ResponseRequested element is set to 0 (false) on the meeting request, the client does not expose an option to the user to send a response notification to the organizer.

The client indicates its response in the subject of the email message, as well by using an iCalendar reply command, as shown in the following example.

POST /Microsoft-Server-ActiveSync?Cmd=SendMail&User=Bob&DeviceId=ABCDEF&DeviceType=SmartPhone HTTP/1.1

Content-Type: application/vnd.ms-sync.wbxml

MS-ASProtocolVersion: 14.0

Host: mail.contoso.com

 

<?xml version="1.0" encoding="utf-8" ?>

<SendMail xmlns="ComposeMail:">

  <ClientId>13554</ClientId>

  <SaveInSentItems/>

  <Mime>

    Subject: Accepted: Quarterly Planning

    From: Bob@contoso.com

    Content-Type: multipart/alternative;

    boundary=NextPart

    To: Alice  <Alice@contoso.com>

 

--NextPart

Content-Type: text/plain;

                    charset=us-ascii

Sure, I will be there!

 

--NextPart

Content-Type: text/calendar;

                    charset=utf-8;

                    name=meeting.ics;

                    method=REPLY

Content-Transfer-Encoding: quoted-printable

 

BEGIN:VCALENDAR…<more iCalendar content follows>

 

</Mime>

</SendMail>

The following table lists the possible response types.

Meeting updates

If the organizer makes updates to the meeting, the Exchange ActiveSync client might receive multiple meeting notification email messages. All mail items that are related to the same meeting have the same GlobalObjId element value (for the email notification) and the same UID element value (for the Calendar item). If the Exchange ActiveSync client receives multiple updates that share the same ID, it is important for the client to enable the user to respond to the most recent item only based on the DtStamp value.

Scenario 2: Organizer uses an Exchange ActiveSync client to verify the meeting response status

After the invitees have responded to the meeting request, the organizer might want to determine the status of the responses. The organizer can view the responses in the Inbox as they arrive from individual invitees. In addition, the Exchange server automatically parses the invitee responses and updates the Calendar item accordingly. The organizer can view the response status on the Calendar item based on updates from the server to the Exchange ActiveSync client.

Syncing meeting responses in the organizer's Inbox

As invitees respond to the meeting request, the organizer's Exchange ActiveSync client runs a Sync command on the Inbox folder to discover the responses, as shown in the following example.

HTTP/1.1 200 OK

Content-Type: application/vnd.ms-sync.wbxml

 

<?xml version="1.0" encoding="utf-8"?>

<Sync>

  <Collections>

    <Collection>

      <SyncKey>378940377</SyncKey>

      <CollectionId>6</CollectionId>

      <Status>1</Status>

      <Commands>

        <Add>

          <ServerId>6:22</ServerId>

          <ApplicationData>

            <email:To>"Alice" &lt;alice@contoso.com&gt;</email:To>

            <email:From>"Bob" &lt;bob@contoso.com&gt;</email:From>

            <email:Subject>Accepted: Quarterly Planning</email:Subject>

            <email:DateReceived>20110506T165454Z</email:DateReceived>

            <email:DisplayTo>Alice </email:DisplayTo>

            <email:ThreadTopic>Quarterly Planning</email:ThreadTopic>

            <email:Importance>1</email:Importance>

            <email:Read>0</email:Read>

            <airsyncbase:Body>

              <airsyncbase:Type>1</airsyncbase:Type>

              <airsyncbase:EstimatedDataSize>0</airsyncbase:EstimatedDataSize>

              <airsyncbase:Truncated>1</airsyncbase:Truncated>

            </airsyncbase:Body>

            <email:MessageClass>IPM.Schedule.Meeting.Resp.Pos</email:MessageClass>

            <email:MeetingRequest>

              <email:AllDayEvent>0</email:AllDayEvent>

              <email:StartTime>20110510T17000000Z</email:StartTime>

              <email:DtStamp>20110506T165252Z </email:DtStamp>

              <email:EndTime>20110510T180000Z</email:EndTime>

              <email:InstanceType>0</email:InstanceType>

              <email:Location>Office</email:Location>

              <email:Organizer>"Bob " &lt;bob@contoso.com&gt;</email:Organizer>

              <email:Sensitivity>0</email:Sensitivity>

              <email:TimeZone>4AEAACgAVQBUAEMALQAwADgAOgAwADAAKQAgAFAAYQBjAGkAZgBpAGM

                 AIABUAGkAbQBlACAAKABVAFMAIAAmACAAQwAAAAsAAAABAAIAAAAAAAAAAAAAACgAV

                 QBUAEMALQAwADgAOgAwADAAKQAgAFAAYQBjAGkAZgBpAGMAIABUAGkAbQBlACAAKABVAF

                 MAIAAmACAAQwAAAAMAAAACAAIAAAAAAAAAxP///w==</email:TimeZone>

              <email:GlobalObjId> BAAAAIIA4AB0xbcQGoLgCAAAAAAAAAAAAAAAAAAAAAAAAAAATQAAAHZD

                 YWwtVWlkAQAAAEEzNTYxQkRBQUU4RTRCMzBBQzI1NUZEM0YzMUEzQUQ3MDAwMDAwMDA

                 wMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAA</email:GlobalObjId>

            </email:MeetingRequest>

            <email:InternetCPID>20127</email:InternetCPID>

            <email:Flag />

            <email:ContentClass>urn:content-classes:calendarmessage</email:ContentClass>

            <airsyncbase:NativeBodyType>1</airsyncbase:NativeBodyType>

            <email2:ConversationId>(Uí©E¯*O»&#x12;F               n                 &#x2;Ô</email2:ConversationId>

            <email2:ConversationIndex>Ì&#x10;1ë¯&#x0;&#x0;&#x1A;4E</email2:ConversationIndex>

            <email:Categories />

          </ApplicationData>

        </Add>

      </Commands>

    </Collection>

  </Collections>

</Sync>

Note that the ApplicationData container of the response that is synced to the organizer's Inbox contains To and From fields however, the values of these elements are different than the values in the original meeting request. In the response message, the To field indicates the organizer, because the organizer is the recipient of the response, while the From field indicates the invitee.

The MessageClass and Subject elements indicate the invitee's response to the request, as set by the client. The following are the possible values for the MessageClass element:

·        IPM.Schedule.Meeting.Resp.Pos

·        IPM.Schedule.Meeting.Resp.Tent

·        IPM.Schedule.Meeting.Resp.Neg.

Updating the organizer's Calendar item to reflect invitee responses

When the Exchange ActiveSync client syncs the organizer's Calendar folder, the original meeting item is updated to reflect any new or updated invitee responses. The client can then display the invitee status to the organizer. The following example shows a change in an attendee, Bob's, status after he accepts the meeting invitation. Note that the Calendar item shows a value of 3 for the AttendeeStatus element, rather than 0, which was the value when the request was created and before a response was received.

HTTP/1.1 200 OK

Content-Type: application/vnd.ms-sync.wbxml

 

<?xml version="1.0" encoding="utf-8"?>

<Sync>

  <Collections>

    <Collection>

      <SyncKey>124536913</SyncKey>

      <CollectionId>2</CollectionId>

      <Status>1</Status>

      <Commands>

        <Change>

          <ServerId>2:9</ServerId>

          <ApplicationData>

            <calendar:Attendees>

              <calendar:Attendee>

                <calendar:Email>bob@contoso.com</calendar:Email>

                <calendar:Name>Bob </calendar:Name>

                <calendar:AttendeeStatus>3</calendar:AttendeeStatus>

                <calendar:AttendeeType>1</calendar:AttendeeType>

              </calendar:Attendee>

            </calendar:Attendees>

          </ApplicationData>

        </Change>

      </Commands>

    </Collection>

  </Collections>

</Sync>

The following table lists the possible values for the AttendeeStatus element.

When the organizer creates the meeting request, the AttendeeStatus element is set to 0 because no invitees have yet responded. As the response notifications arrive, the organizer’s Exchange server interprets the iCalendar content in the response messages and updates the AttendeeStatus value for each attendee accordingly. An AttendeeStatus value of 5 indicates a problem with interpreting the invitee response.  

Exchange ActiveSync does not handle responses involving new time proposals. New time proposals appear as tentative or decline responses to the Exchange ActiveSync client. The new time proposal may be indicated in the subject line or the body of the message, depending on the client that the invitee uses to send the proposal.

Summary

The ability to respond to meeting requests is a critical element of a successful calendaring experience for Exchange ActiveSync client users. When you develop your Exchange ActiveSync client applications, make sure that you handle iCalendar meeting responses correctly. Keep in mind that your applications should not process incoming iCalendar meeting requests on the client; meeting requests should be processed by the Exchange server.  

Additional Resources

[MS-ASEMAIL]: ActiveSync Email Class Protocol Specification

[MS-ASCAL]: ActiveSync Calendar Class Protocol Specification

[MS-ASCMD]: ActiveSync Email Command Reference Protocol Specification

[MS-ASDTYPE]: ActiveSync Data Types

[MS-OXGLOS]: Exchange Server Protocols Master Glossary

[MS-OXCICAL]: iCalendar to Appointment Object Conversion Protocol Specification

Post authored by: Katarzyna Puchala, Microsoft Corporation

This post is part of an ongoing series that covers Microsoft Exchange ActiveSync for developers. 

In this post, we are using Exchange ActiveSync protocol version 14.1. Where applicable, we note differences between protocol versions.

Meeting requests are important for information workers who use Microsoft Exchange. Meeting requests inform attendees of a meeting, automatically book meeting time on the organizer's and attendees' calendars, provide reminders for meetings, and enable the booking of conference rooms. This post provides information for developers about working with meeting requests, including the following topics:

• How meeting requests are created by using Exchange ActiveSync.
• How invitees' Exchange ActiveSync clients interpret meeting requests.

The following figure shows an overview of the meeting request process and the two key scenarios involved. In this example, Exchange ActiveSync user Alice requests a meeting with Bob from her Exchange ActiveSync client. Bob sees the meeting request on his Exchange ActiveSync device.

Figure 1:   Meeting request process

Scenario 1: Organizer creates meeting request by using an Exchange ActiveSync client

A meeting starts out as a meeting request. The meeting organizer requests that attendees agree to participate in the meeting at a specified date, time, and location. Meeting requests are composed of the following two elements:

1.      A calendar item that reflects the proposed meeting on the organizer's and invitees' calendars.

2.      An invitation email sent by the organizer to invitees to notify them of the proposed meeting and solicit their responses.

In order for a user to create meeting requests, an Exchange ActiveSync client must do the following:

• Add a new calendar event to the organizer's calendar that includes the meeting details.

• Send an email to prospective attendees that includes the meeting details and response options.

After the Exchange ActiveSync client sends an email message that includes the meeting invitation, the Exchange server sends the invitation and saves a copy in the Sent Items folder. The following figure shows the client requests and server responses when a user, Alice, creates a meeting request from her Exchange ActiveSync client. The syncing of the Sent Items folder is optional.

Figure 2:   Sending a meeting request from an Exchange ActiveSync client

Adding meeting details to the organizer's calendar

Request to create the calendar item

When a user organizes a new meeting on the Exchange ActiveSync client, the client must create a meeting item on the organizer's calendar. The client adds the new calendar item to the Calendar collection. The calendar item contains all the meeting details, including meeting attendees. The following example shows an Exchange ActiveSync Sync command XML request that adds a meeting to Alice's calendar when she organizes a meeting and invites Bob.

For a list of and information about the Calendar schema elements for Exchange ActiveSync, see [MS-ASCAL]:  ActiveSync Calendar Class Protocol Specification section 2.2.2.

In the meeting request, the Exchange ActiveSync client must specify the start time and end time of the proposed event; this information is included in the StartTime and EndTime elements. Both dates have to be valid values of the dateTime type, as described in [MS-ASDTYPE]: ActiveSync Data Types section 2.3. All dates must be specified in Coordinated Universal Time (UTC), without any punctuation separators. Optionally, the client can use the DtStamp element to specify when the calendar item was created.