GetEvents Operation
Topic Last Modified: 2008-09-05
The GetEvents operation is used by pull subscription clients to request notifications from the Client Access server. The GetEvents response returns an array of items and events that have occurred in a mailbox since the last the notification.
Remarks
Changes to Calendar items may result in the generation of multiple eventsgenerated. These events are the result of temporary items being created in the mailbox, Free/Busy data storage items being changed as part of the normal Calendar operations, or both. Events for item class "IPM.SchedulePlus.FreeBusy.BinaryData" should be ignored by Web service clients. These temporary items are deleted after they are created; therefore, if an attempt is made to retrieve these items, an error will be returned that states that the item was not found.
GetEvents Request Example
Description
The following example shows how to request the events and items that are associated with a subscription that is identified by the subscription identifier and watermark.
Code
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
<soap:Body>
<GetEvents xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<SubscriptionId>f6bc657d-dde1-4f94-952d-143b95d6483d</SubscriptionId>
<Watermark>AAAAAMAGAAAAAAAAAQ==</Watermark>
</GetEvents>
</soap:Body>
</soap:Envelope>
GetEvents Request Elements
The following elements are used in the request:
Successful GetEvents Response Example
Description
The following example of a response shows a notification of the existence of two new mail messages since the last notification request was sent to the server.
Code
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://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="628" MinorBuildNumber="0"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<GetEventsResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:GetEventsResponseMessage ResponseClass="Success">
<m:ResponseCode>NoError</m:ResponseCode>
<m:Notification>
<t:SubscriptionId>f6bc657d-dde1-4f94-952d-143b95d6483d</t:SubscriptionId>
<t:PreviousWatermark>AAAAAMAGAAAAAAAAAQ==</t:PreviousWatermark>
<t:MoreEvents>false</t:MoreEvents>
<t:NewMailEvent>
<t:Watermark>AAAAAM4GAAAAAAAAAQ==</t:Watermark>
<t:TimeStamp>2006-08-22T00:36:29Z</t:TimeStamp>
<t:ItemId Id="AQApAHR" ChangeKey="CQAAAA==" />
<t:ParentFolderId Id="AQApAH" ChangeKey="AQAAAA==" />
</t:NewMailEvent>
<t:NewMailEvent>
<t:Watermark>AAAAAOQGAAAAAAAAAQ==</t:Watermark>
<t:TimeStamp>2006-08-22T01:00:50Z</t:TimeStamp>
<t:ItemId Id="AQApAHRw" ChangeKey="CQAAAA==" />
<t:ParentFolderId Id="AQApAH" ChangeKey="AQAAAA==" />
</t:NewMailEvent>
</m:Notification>
</m:GetEventsResponseMessage>
</m:ResponseMessages>
</GetEventsResponse>
</soap:Body>
</soap:Envelope>
Comments
Note
The item and folder identifiers have been shortened to preserve readability.
GetEvents Response Elements
The following elements are used in the response:
- ServerVersionInfo
- GetEventsResponse
- ResponseMessages
- GetEventsResponseMessage
- ResponseCode
- Notification
- SubscriptionId
- PreviousWatermark
- MoreEvents
- NewMailEvent
- Watermark
- TimeStamp
- ItemId
- ParentFolderId
To find other options for the response message of the GetEvents operation, explore the schema hierarchy. Start at the Notification element.
GetEvents Error Response Example
Description
The following example shows an error response to a GetEvents request.
Code
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="https://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="628" MinorBuildNumber="0"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<GetEventsResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<m:ResponseMessages>
<m:GetEventsResponseMessage ResponseClass="Error">
<m:MessageText>Access is denied. Only the subscription owner may access the subscription.</m:MessageText>
<m:ResponseCode>ErrorSubscriptionAccessDenied</m:ResponseCode>
<m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
</m:GetEventsResponseMessage>
</m:ResponseMessages>
</GetEventsResponse>
</soap:Body>
</soap:Envelope>
Remarks
When processing a GetEvents request, the Client Access server performs the following steps:
- The SubscriptionID of the request is confirmed to be a valid subscription that is hosted on the Client Access server. If it is not, the GetEvents call fails.
- The SMTP address of the authenticated user for the request is compared to the SMTP address of the user who created the subscription. If they do not match, the GetEvents request fails.
- The subscription queue is queried for events that are waiting to be sent to the client. If the queue is not empty, the first 50 events from the queue are pulled from the queue and encoded into a notification.
- If no events are found in the queue, a StatusEvent is generated and encoded into a notification response.
- The notification response is returned to the client.
- The events that are included in the notification are removed from the subscription queue and the Client Access server–local last watermark for the subscription is set to the watermark of the last event that is returned.
- The timeout timer for the subscription is reset.