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

[SVN commits to the Digium repositories]

Author: mmichelson
Date: Tue Nov 24 15:41:57 2009
New Revision: 231169

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=231169
Log:
More documentation about the PUBLISH components.


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=231169&r1=231168&r2=231169
==============================================================================
--- team/group/CCSS/channels/chan_sip.c (original)
+++ team/group/CCSS/channels/chan_sip.c Tue Nov 24 15:41:57 2009
@@ -1662,14 +1662,13 @@
  * 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.
+ * ESC:
+ * The main structure in chan_sip is the event_state_compositor. 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. We are
  * able to match the incoming PUBLISH to a sip_esc_entry using the Sip-If-Match header
@@ -1688,6 +1687,33 @@
  * 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.
+ *
+ * EPA:
+ * The event publication agent in chan_sip is structured quite a bit differently than the
+ * ESC. With an ESC, an appropriate entry has to be found based on the contents of an incoming
+ * PUBLISH message. With an EPA, the application interested in sending the PUBLISH can maintain
+ * a reference to the appropriate EPA entry instead. Similarly, when matching a PUBLISH response
+ * to an appropriate EPA entry, the sip_pvt can maintain a reference to the corresponding
+ * EPA entry. The result of this train of thought is that there is no compelling reason to
+ * maintain a container of these entries.
+ *
+ * Instead, there is only the sip_epa_entry structure. Every sip_epa_entry has an entity tag
+ * that it maintains so that subsequent PUBLISH requests will be identifiable by the ESC on
+ * the far end. In addition, there is a static_data field which contains information that is
+ * common to all sip_epa_entries for a specific event package. This static data includes the
+ * name of the event package and callbacks for handling specific responses for outgoing PUBLISHes.
+ * Also, there is a field for pointing to instance-specific data. This can include the current
+ * published state or other identifying information that is specific to an instance of an EPA
+ * entry of a particular event package.
+ *
+ * When an application wishes to send a PUBLISH request, it simply will call create_epa_entry,
+ * followed by transmit_request_publish in order to send the PUBLISH. That's all that is necessary.
+ * Like with ESC entries, sip_epa_entries are reference counted. Unlike ESC entries, though,
+ * sip_epa_entries reference counts have to be maintained to some degree by the application making
+ * use of the sip_epa_entry. The application will acquire a reference to the EPA entry when it
+ * calls create_epa_entry. When the application has finished using the EPA entry (which may not
+ * be until after several PUBLISH transactions have taken place) it must use ao2_ref to decrease
+ * the reference count by 1.
  */
 
 enum sip_cc_publish_state {