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

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Tue Nov 24 11:45:02 2009
New Revision: 231092

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=231092
Log:
Start documenting SIP PUBLISH support.

I stopped here because I realize that I have a bit of
a hashing problem with ESCs


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=231092&r1=231091&r2=231092
==============================================================================
--- team/group/CCSS/channels/chan_sip.c (original)
+++ team/group/CCSS/channels/chan_sip.c Tue Nov 24 11:45:02 2009
@@ -1649,6 +1649,31 @@
 	enum referstatus status;			/*!< REFER status */
 };
 
+/* SIP PUBLISH support!
+ * PUBLISH support was added to chan_sip due to its use in the call-completion
+ * event package. In order to suspend and unsuspend monitoring of a called party,
+ * a PUBLISH message must be sent. Rather than try to hack in PUBLISH transmission
+ * and reception solely for the purposes of handling call-completion-related messages,
+ * an effort has been made to create a generic framework for handling PUBLISH messages.
+ *
+ * There are two main components to the effort, the event publication agent (EPA) and
+ * the event state compositor (ESC). Both of these terms appear in RFC 3903, and the
+ * implementation in Asterisk conforms to the defintions there. An EPA is a UAC that
+ * transmits PUBLISH requests. An ESC is a UAS that receives PUBLISH requests and
+ * acts appropriately based on the content of those requests.
+ *
+ * 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-
+ * 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. 
+ */
+
 enum sip_cc_publish_state {
 	CC_CLOSED,
 	CC_OPEN,