SUBSCRIBE Method

Topic Last Modified: 2006-06-13

This topic applies to Exchange 2000 Server SP2 or later.

The WebDAV SUBSCRIBE 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.

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

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.

The following example renews subscription 21.

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

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

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

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>