Using Pull Subscriptions (Exchange Web Services)
Topic Last Modified: 2007-09-17
Exchange Web Services provides a pull subscription so that client applications can discover events that occur in the Exchange store. Using pull subscriptions involves the following three basic steps:
- Creating a subscription
- Retrieving store events
- Ending the subscription
For more information about these steps, see the procedures in this topic.
To create the binding and set the credentials
Create the binding used by the Subscribe, GetEvents, and Unsubscribe operations. For more information, see Setting Up the ExchangeServiceBinding Proxy Class.
Identify the URL of the Client Access server and the user credentials used to send the requests.
To create a pull subscription
Create a new Subscribe request.
Identify the folders to monitor for events.
Identify the events to monitor for the subscription.
Define the timeout period for the subscription.
Send the Subscribe request and receive the Subscribe response. The Subscribe response includes the Subscription ID and the initial watermark that is used for the first GetEvents call.
To get event notifications
Create a new GetEvents request.
Use the SubscriptionId returned in the subscribe response. For the first GetEvents request, use the watermark returned in the subscribe response. For subsequent GetEvents requests, use the last watermark returned in the previous GetEvents request.
Send the GetEvents request and receive the GetEvents response. Each GetEvents response includes information about one or more events. A watermark is returned for each event. The last watermark must be saved and used in the next GetEvents request.
Note
If no store events have occurred since the last GetEvents request, a status event is returned.
To unsubscribe to a pull subscription
Create an Unsubscribe request.
Identify the subscription to unsubscribe from.
Send the Unsubscribe request and receive the Unsubscribe response.
Note
A subscription is also deleted if a GetEvents request is not made within the timeout period. The timeout period is specified when the subscription is created with the Subscribe Operation.
Example
The following example shows the steps involved in using a pull subscription.
static void PullNotification()
{
// Create the binding and set the credentials.
ExchangeServiceBinding esb = new ExchangeServiceBinding();
esb.Url = "http://CAS.example.com/EWS/Exchange.asmx";
esb.Credentials = new NetworkCredential("Username", "Password", "Domain");
// Create a new Subscribe request.
SubscribeType subscribeRequest = new SubscribeType();
PullSubscriptionRequestType pullSubscription = new PullSubscriptionRequestType();
// Identify the folders that are monitored for events.
BaseFolderIdType[] folders = new BaseFolderIdType[1];
DistinguishedFolderIdType folderId = new DistinguishedFolderIdType();
folderId.Id = DistinguishedFolderIdNameType.inbox;
folders[0] = folderId;
pullSubscription.FolderIds = folders;
// Identify the events that are monitored for the subscription.
NotificationEventTypeType[] eventTypes = new NotificationEventTypeType[1];
eventTypes[0] = NotificationEventTypeType.NewMailEvent;
pullSubscription.EventTypes = eventTypes;
// Define the timeout period for the subscription.
pullSubscription.Timeout = 10;
subscribeRequest.Item = pullSubscription;
// Send the Subscribe request and receive the Subscribe response.
SubscribeResponseType subscribeResponse = esb.Subscribe(subscribeRequest);
// Check the results.
if (subscribeResponse.ResponseMessages.Items.Length > 0 &&
subscribeResponse.ResponseMessages.Items[0].ResponseClass == ResponseClassType.Success)
{
SubscribeResponseMessageType subscribeResponseMessage = subscribeResponse.ResponseMessages.Items[0] as SubscribeResponseMessageType;
Console.WriteLine("Subscribed for Pull notifications: {0}", subscribeResponseMessage.SubscriptionId);
// Wait 30 seconds before receiving event notifications.
Thread.Sleep(30000);
// Create a new GetEvents request.
GetEventsType getEventsRequest = new GetEventsType();
// Identify the subscription identifier and watermark for the subscription
// that will be polled for changes in the Exchange store.
getEventsRequest.SubscriptionId = subscribeResponseMessage.SubscriptionId;
getEventsRequest.Watermark = subscribeResponseMessage.Watermark;
// Send the GetEvents request and receive the GetEvents response.
GetEventsResponseType eventsResponse = esb.GetEvents(getEventsRequest);
// Check the results.
if (eventsResponse.ResponseMessages.Items.Length > 0 &&
eventsResponse.ResponseMessages.Items[0].ResponseClass == ResponseClassType.Success)
{
GetEventsResponseMessageType eventsResponseMessage = eventsResponse.ResponseMessages.Items[0] as GetEventsResponseMessageType;
foreach (ItemsChoiceType type in eventsResponseMessage.Notification.ItemsElementName)
{
Console.WriteLine(type.ToString());
}
}
// Create an Unsubscribe request.
UnsubscribeType unsubscribeRequest = new UnsubscribeType();
// Identify the subscription to unsubscribe from.
unsubscribeRequest.SubscriptionId = subscribeResponseMessage.SubscriptionId;
// Send the Unsubscribe request and receive the Unsubscribe response.
UnsubscribeResponseType unsubscribeResponse = esb.Unsubscribe(unsubscribeRequest);
// Check the results
if (unsubscribeResponse.ResponseMessages.Items.Length > 0 &&
unsubscribeResponse.ResponseMessages.Items[0].ResponseClass == ResponseClassType.Success)
{
Console.WriteLine("Subscribtion {0} unsubscribed successfully", unsubscribeRequest.SubscriptionId);
}
}
}
The following XML example shows the Subscribe request message that is sent from the client to the server.
<?xml version="1.0" encoding="utf-8"?>
<Subscribe xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PullSubscriptionRequest xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<FolderIds xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<DistinguishedFolderId Id="inbox" />
</FolderIds>
<EventTypes xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<EventType>NewMailEvent</EventType>
</EventTypes>
<Timeout xmlns="https://schemas.microsoft.com/exchange/services/2006/types">10</Timeout>
</PullSubscriptionRequest>
</Subscribe>
The following XML example shows the Subscribe response message that is sent from the server to the client.
<?xml version="1.0" encoding="utf-8"?>
<SubscribeResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<SubscribeResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
<SubscriptionId>d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
<Watermark>AAAAAGUhAAAAAAAAAQ==</Watermark>
</SubscribeResponseMessage>
</ResponseMessages>
</SubscribeResponse>
The following XML example shows the GetEvents request message that is sent from the client to the server.
<?xml version="1.0" encoding="utf-8"?>
<GetEvents xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SubscriptionId xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
<Watermark xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">AAAAAGUhAAAAAAAAAQ==</Watermark>
</GetEvents>
The following XML example shows the GetEvents response message that is sent from the server to the client.
<?xml version="1.0" encoding="utf-8"?>
<GetEventsResponseType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<GetEventsResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
<Notification>
<SubscriptionId xmlns="https://schemas.microsoft.com/exchange/services/2006/types">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
<PreviousWatermark xmlns="https://schemas.microsoft.com/exchange/services/2006/types">AAAAAGUhAAAAAAAAAQ==</PreviousWatermark>
<MoreEvents xmlns="https://schemas.microsoft.com/exchange/services/2006/types">false</MoreEvents>
<NewMailEvent xmlns="https://schemas.microsoft.com/exchange/services/2006/types">
<Watermark>AAAAAHMhAAAAAAAAAQ==</Watermark>
<TimeStamp>2006-08-24T21:37:01Z</TimeStamp>
<ItemId Id="AAAtA=" ChangeKey="CQAAAA==" />
<ParentFolderId Id="AQAtAEFkbWA==" ChangeKey="AQAAAA==" />
</NewMailEvent>
</Notification>
</GetEventsResponseMessage>
</ResponseMessages>
</GetEventsResponse>
The following XML example shows the GetEvents request message that is sent from the client to the server.
<?xml version="1.0" encoding="utf-8"?>
<UnsubscribeType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SubscriptionId xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">d581ab79-a2ec-4653-9c8e-564d7cfc1d8c</SubscriptionId>
</UnsubscribeType>
The following XML example shows the GetEvents response message that is sent from the server to the client.
<?xml version="1.0" encoding="utf-8"?>
<UnsubscribeResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ResponseMessages xmlns="https://schemas.microsoft.com/exchange/services/2006/messages">
<UnsubscribeResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
</UnsubscribeResponseMessage>
</ResponseMessages>
</UnsubscribeResponse>
The SOAP messages that are passed between the Exchange Web Services client and server are defined by the XML schema and WSDL files. The XML schema and WSDL files define the contract between the client and server. Proxy class generators create an object-model abstraction of those SOAP messages, which can simplify programming. This code example uses a proxy class library that was generated by Microsoft Visual Studio 2005. Different proxy class generators create different object models for a given Web service. This proxy class code example is an illustration only. Refer to the proxy class generator documentation for support for proxy classes.
Note
The item identifiers and change key have been shortened to preserve readability.