[svn-commits] mmichelson: branch group/CCSS r231094 - /team/group/CCSS/channels/chan_sip.c

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Tue Nov 24 12:39:15 2009
New Revision: 231094

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=231094
Log:
Add more documentation on SIP ESC workings.


Modified:
    team/group/CCSS/channels/chan_sip.c

Modified: team/group/CCSS/channels/chan_sip.c
URL: http://svnview.digium.com/svn/asterisk/team/group/CCSS/channels/chan_sip.c?view=diff&rev=231094&r1=231093&r2=231094
==============================================================================
--- team/group/CCSS/channels/chan_sip.c (original)
+++ team/group/CCSS/channels/chan_sip.c Tue Nov 24 12:39:15 2009
@@ -1665,13 +1665,29 @@
  * Let's take a closer look at each component, starting with the ESC. The ESC receives
  * PUBLISH requests and acts on them, depending on the content. The main structure
  * in chan_sip is the event_state_compositor struct. There is an event_state_compositor
- * structure for each event-package supported (as of Nov 2009 this is only the call-
+ * structure for each event package supported (as of Nov 2009 this is only the call-
  * completion package). The structure contains data which is intrinsic to the event
  * package itself, such as the name of the package and a set of callbacks for handling
  * incoming PUBLISH requests. In addition, the event_state_compositor struct contains
  * an ao2_container of sip_esc_entries.
  *
- * A sip_esc_entry corresponds to an entity which has sent a PUBLISH to Asterisk. 
+ * A sip_esc_entry corresponds to an entity which has sent a PUBLISH to Asterisk. We are
+ * able to match the incoming PUBLISH to a sip_esc_entry using the Sip-If-Match header
+ * of the message. Of course, if none is present, then a new sip_esc_entry will be created.
+ *
+ * Once it is determined what type of PUBLISH request has come in (from RFC 3903, it may
+ * be an initial, modify, refresh, or remove), then the event package-specific callbacks
+ * may be called. If your event package doesn't need to take any specific action for a
+ * specific PUBLISH type, it is perfectly safe to not define the callback at all. The callback
+ * only needs to take care of application-specific information. If there is a problem, it is
+ * up to the callback to take care of sending an appropriate 4xx or 5xx response code. In such
+ * a case, the callback should return -1. This will tell the function that called the handler
+ * that an appropriate error response has been sent. If the callback returns 0, however, then
+ * the caller of the callback will generate a new entity tag and send a 200 OK response.
+ *
+ * ESC entries are reference-counted, however as an implementor of a specific event package,
+ * this should be transparent, since the reference counts are handled by the general ESC
+ * framework.
  */
 
 enum sip_cc_publish_state {