SUBSCRIBE Method

  • Article

SUBSCRIBE Method

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release. The WebDAVSUBSCRIBE method is used to create a subscription to a resource. This method is used to specify the details about the event to be monitored: where to look for it; how long the event should be monitored; what the notification mechanism is; and how long to delay before generating a notification of the event. When the SUBSCRIBE method specifies an already existing subscription, that subscription is renewed.

When you create a subscription to a resource, you cannot use the value of the resource's permanenturl Field as the target URL of the request. A 403 Forbidden status code will be returned.

If the Call-Back Header was specified in the subscription, then the server will call the NOTIFY Method to send a notification to the appropriate httpu address when events occur. Then, depending on the notification mechanism that was chosen, the POLL Method is used to either acknowledge that the client has received and responded to a particular event or to query the server for any events that may have fired.

If the Subscription-ID Header is present, then the SUBSCRIBE method is a subscription renewal, and the Call-Back Header, Notification-Type Header, and Depth Header should not be present. If the Subscription-ID Header appears with the illegal headers, it is a bad request and may be refused by the server.

Note  See Authentication and Security Using WebDAV for more information.

The list of WebDAV Protocol Status Codes in the following table is not comprehensive. For information about 500-level status codes, see WebDAV Status Codes: 500s.

Status Codes

Status Code Meaning
200 (OK) The subscription was successful. The server may have changed the parameters, such as poll-interval.
207 (Multi-Status) Multiple response codes to be found in XML body. Probably some of the subscription-IDs listed were invalid.
400 (Bad Request) Probably an illegal combination of headers, an invalid notification type, or an invalid combination of notification types. Depth: infinity requests get this error.
401 (Unauthorized) User does not have access permissions or authorization to subscribe to this resource.
403 (Forbidden) A subscription to a resource cannot be created by using the value of the resource's permanenturl Field as the target URL of the request.
404 (Not Found) The resource was not found.
412 (Precondition Failed) The subscription-ID(s) in the header did not match the resource named. This could be because the subscription-ID does not exist any more.
415 (Unsupported Media Type) The request type of the body is not supported by the server.
501 (Not Implemented) Server does not support the notification method.

Example

The Call-Back Header is used in this subscription to instruct the server to call the NOTIFY Method for the User Datagram Protocol (UDP) server at www.fourthcoffee.com using port 8080.

Request

SUBSCRIBE /public/subtest HTTP/1.1
Host: www.contoso.com
Notification-type: Update
Call-Back: httpu://www.fourthcoffee.com:8080/510

Response

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Fri, 06 Jul 2001 18:37:44 GMT
notification-type: update
Subscription-lifetime: 3600
call-back: httpu://www.fourthcoffee.com:8080/510
Content-Location: https://www.contoso.com/public/subtest/
Content-Length: 0
Subscription-id: 3

Example

The Subscription-Lifetime Header is used to make the following subscription valid for 600 seconds.

Request

SUBSCRIBE /public/subtest HTTP/1.1
Host: www.contoso.com
Notification-type: update
Subscription-lifetime: 600

Response

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Fri, 06 Jul 2001 18:39:28 GMT
notification-type: update
Subscription-lifetime: 600
Content-Location: https://www.contoso.com/public/subtest/
Content-Length: 0
Subscription-id: 4

Example

The following subscription uses the Notification-Delay Header to coalesce events for 400 seconds before calling the NOTIFY Method for the UDP server that was specified in the Call-Back Header.

Request

SUBSCRIBE /public/subtest HTTP/1.1
Host: www.contoso.com
Notification-type: update
Notification-Delay: 400
Call-Back: httpu://www.fourthcoffee.com:8080/510

Response

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Fri, 06 Jul 2001 18:43:40 GMT
notification-type: update
Subscription-lifetime: 3600
call-back: httpu://www.fourthcoffee.com:8080/510
Content-Location: https://www.contoso.com/public/subtest/
Content-Length: 0
Subscription-id: 7
Notification-delay: 400

Example

The following example renews subscription 21.

Request

SUBSCRIBE /public/subtest HTTP/1.1
Host: www.contoso.com
Subscription-id: 21

Response

HTTP/1.1 207 Multi-Status
Server: Microsoft-IIS/5.0
Date: Fri, 06 Jul 2001 18:45:37 GMT
Content-Type: text/xml
Content-Length: 272

<?xml version="1.0"?>
<a:multistatus xmlns:b="https://schemas.microsoft.com/Exchange/" xmlns:a="DAV:">
  <a:response>
    <a:href>https://www.contoso.com/public/subtest</a:href>
    <a:status>HTTP/1.1 200 OK</a:status>
    <b:subscriptionID>
      <li>21</li>
    </b:subscriptionID>
  </a:response>
</a:multistatus>

Send us your feedback about the Microsoft Exchange Server 2003 SDK.

This topic last updated: March 2005

Build: June 2007 (2007.618.1)

© 2003-2006 Microsoft Corporation. All rights reserved. Terms of use.