SIP SUBSCRIBE and NOTIFY Requests

SUBSCRIBE and NOTIFY (rfc 3265) 

1. ability to receive asynchronous notification of events, on subscription
2. general concept is that the entities in the network can SUBSCRIBE (which needs to be refreshed periodically) to resource or call state, and be notified when the state changes
3. SUBSCRIBE requests create a dialog
4. terms and definitions
   1. Event Package, set of state info to be reported by a notifier to a SUBSCRIBEr
   2. Event Template Package, special kind of event package which defines a set of event packages with a set od states which may be applied to all possible event packages
   3. Notification, act of sending a NOTIFY message to the SUBSCRIBER, informaing the state of resource
   4. Notifier, UA which generates the NOTIFY request, and typically accepts SUBSCRIBE request to create subscriptions
   5. State Agent, notifier which publishes the state on behalf of a resource, they may need to gather such info from multiple sources
   6. SUBSCRIBER, UA which receives a NOTIFY request, typically generate SUBSCRIBE request
   7. subscription is a set of application state associated with a dialog, containing a pointer to the associate dialog, the even package name, and an identifiction token
   8. Subscription Migration, act of moving a subscription from one notifier to another
5. "Expires" Header
   1. SUBSCRIBE requests should contain an "Expires" header, indicating the duration of subscription 
   2. if no "Expires" header is present then the implied default defined in the even package is used
   3. 200 class response to a SUBSCRIBE request must contain an "Expires" header, the period can be shorter(but not longer) than specified in the request
   4. SUBSCRIBE with an "Expires" of 0 means
      1. the request is for unSUBSCRIBE from an event
      2. can also cause a fetch of state
      3. successful unsubscription will also trigger a final NOTIFY message
6. Identification of Events and Event Classes
   1. Request URI, Event Type and Optionally Message Body
   2. SUBSCRIBErs must include exactly one "Event" header in SUBSCRIBE requests, indication which event or class of events they are subscribing
   3. the "Event" header may contain an "id" param which identifies a specific subscription with in a dialog, "id" is only valid within the scope of a single dialog
7. Additional SUBSCRIBE Header values
   1. as the SUBSCRIBE request create a dialog, they may contain a "Accept" header, if present it indicates the body formats allowed in subsequent NOTIFY requests.
8. Subscription behavior
   1. intial SUSCRIBE request is generally a request outside of a dialog
   2. the SUBSCRIBE request will be confirmed with a final response (200 class), and a NOTIFY will be send immediately
   3. the "Expires" header in a 200 class response indicates the actual duration for which the subscription will remain active
   4. a SUBSCRIBE request may contiain an "id" param in its "Event" header to differentiate between multiple subscriptions in the same dialog
   5. the "489 bad event" is used to indicate that the server did not understand the even package specefied in the "Event" header field
9. refershing of subscriptions
   1. by sending another SUBSCRIBE ewquest on the same dialog as the existing subscription and with the same "Event" header and "id" parameter if present
   2. if the "id" param is not present in the initial SUBSCRIBE and refresh SUBSCRIBE will contain an "id" param, it will be considered as a anew subscription in the existing dialog
   3. a "481 call/transaction does not exist" response to refresh SUBSCRIBE means that the subscription has been terminated
10. unsubscribing
    1. done by setting the "Expires" header to "0"
    2. a successfull unsubscription will also trigger a NOTIFY message
11. proxy SUBSCRIBE behavior
    1. if a proxy wishes to see all of the SUBSCRIBE and NOTIFY requests for a given dialog it must record-route the initial SUBSCRIBE and any dialog establishing NOTIFY requests
12. notifier SUBSCRIBE behavior
    1. notifiers must not wait for a user response before returning a final response to a SUBSCRIBE request
    2. if the "Event" header is not understood then the notifier should return a "489 bad event" response
    3. notifier should perform any necessary authentication and authorization
    4. notifier may also check that the duration in the "Expires" header is too small, if the expiration is greater than zero AND smaller than one hour AND less than a notifier configured minimum, the notifier may return a "423 Interval too small" error which containes a "Min-Expires" header field
    5. if the notifier cannot immediately create the subscription, it will return a "202 Accepted" response
    6. when a sunscription is created in the notifier, it stores the event package name and the "Event" header "id" param as part of the subscription information
    7. the server must not lenghten (can shorten it) the "Expires" header value in the SUBSCRIBE 200 class responses (same as in REGSTER response),
    8. state information will be communicated via a subsequent NOTIFY request from the notifer
    9. authentication for a SUBSCRIBE request will always be performed via a "401 unauthorized" response, not a "407 proxy authentication required", notifiers always act as a user agents when accepting subscriptions and sending notifications
    10. if the authorization fails the notifer should reply to the request with a "403 forbidden" or a "603 decline" response
    11. notifier may convey authorization declined, by sending a NOTIFY message containing a "Subscription-State" header with a value of "terminated" and a reason param of "rejected"
    12. on receiving a subscription refresh, the notifer (server) may shorten the amount of time until expiration, but must not increase it
    13. if the duration specified in the SUBSCRIBE is unacceptably short the notifier should respond with a "423 subscription too brief"
    14. on removing a subscription the notifier should send a NOTIFY message with a "Subscription-State" value of "terminated" and "reason=timeout" param, this NOTIFY also allows the corresponding dialog to be terminated
13. knowledge of a subscription must exist between both the SUBSCRIBEr and the notifier
14. sending a NOTIFY to a endpoint which is unaware of the subscription, results in a response "481 Subscription does not exist"
15. a single SUBSCRIBE may trigger several NOTIFY
16. as in SUBSCRIBE request, NOTIFY "Event" headers will contain a single event package name in the for which a notification is being send, and the event name must match the name in the "Event" header of the corresponding SUBSCRIBE, the "id" (same as SUBSCRIBE) must also be present
17. a NOTIFY request is considered failed if the response times out, or a non-200 class response code is received which has no "Retry-After" header
18. if a NOTIFY fails due to timeout condition, and the subscription was installed using soft-state mechanism (such as SUBSCRIBE), the NOTIFIER should remove the subscription (this behavior prevents unnecessary transmission of state information for the SUBSCRIBErs who have crashed or disappeared from the network)
19. if a NOTIFY request receives a "481 call leg/transaction does not exist" response the notifier must remove the corresponding subscription, even if the subscription was installed by non-SUBSCRIBE means (eg administrative interface)
20. NOTIFY requests must contain a "Subscription-State" header with a value of "active", "pending", or "terminated".
    1. "active" means that the subscription has been accepted
    2. "pending" means subscription has been received
    3. "terminated" means that the subscription is not active
    4. for "active" or "pending" value an "Expires" param should be included
    5. for "terminated" state notifier should also include any of the following "reason" param
       1. deactivated, subscription terminated, SUBSCRIBEr should retry immediately with a new subscription
       2. probation, subscription terminated, SUBSCRIBEr should retry after some time (use "retry-after" if present)
       3. rejected, subscription rejected due to change in the authorization policy, SUBSCRIBEr should not attempt to re-SUBSCRIBE
       4. timeout, subscription terminated as it was not refershed before it expired, SUBSCRIBEr may reSUBSCRIBE immediately
       5. giveup, subscription terminated because the notifier could not obtain authorization in a timely fashion
       6. noresource, subscription terminated, as the resource state which was being monitored no longer exists
21. detecting support for SUBSCRIBE and NOTIFY
    1. clients may probe for the support of SUBSCRIBE and NOTIFY using the OPTIONS request
    2. the presence of "Allow-Events" header in a message is sufficient to indicate support for SUBSCRIBE and NOTIFY
    3. the "methods" parameter for Contact may also be used to specifically announce support for SUBSCRIBE and NOTIFY messages while registering.
22. forking scenarios
    1. successfull SUBSCRIBE requests wil receive only one 200-class response
    2. due to forking, the subscription may be accepted by multiple nodes, thus there may me more than one NOTIFY requests with "From:" tags which differ from the "To:" tag received in the SUBSCRIBE 200-class response.
    3. if multiple NOTIFY message received in different dialog in response to a single SUBSCRIBE, each dilaog represent a different destination to which the SUBSCRIBE request is forked
23. dialog creation and termination
    1. the initial SUBSCRIBE request is not sent on a pre-existing dialog, a response to the SUBSCRIBE or a matching NOTIFY will make the complete dialog
    2. matching is done on basis of "Call-ID", "From" header "tag" and the same "Cseq".
    3. if a 200-class response matches the SUBSCRIBE, it creates a new subscription and a new dialog (if its not already there)
    4. NOTIFY request are matched to such SUBSCRIBE, by matching "Call-ID", "To" tag parameter of NOTIFY and "From" "tag" of SUBSCRIBE, and the same "Event" header field
    5. multiple subscriptions can be associated with a single dialog
    6. for the purpose of subscription and dialog lifetime, a subscription is destroyed when a notifier sends a NOTIFY request with a "Subscription-State" of "terminated"
    7. in the case of several subscription are associated with a single dialog, the dialog does not terminate until all the  subscriptions in it are destroyed
24. polling resource state
    1. an immediate fetch of the state without a persistent subscription ("Expires" greater than 0) may be effected by sending a SUBSCRIBE with "Expires" of 0   
    2. NOTIFY messages triggered by SUBSCRIBE with "Expires" as 0 will contain a "Subscription-State" of "terminated" and a "reason" param of "timeout"
25. Allow-Events header
    1. a node sending an "Allow-Events" header is advertising that it can process SUBSCRIBE and generate NOTIFY for all the event pacakges listed in the header
    2. the "Allow-Event" headers must not be inserted by proxies

Reference :http://www.ietf.org/rfc/rfc3265.txt