[asterisk-commits] mjordan: branch mjordan/cdrs-of-doom r387021 - /team/mjordan/cdrs-of-doom/inc...

Tue Apr 30 15:51:31 CDT 2013

Author: mjordan
Date: Tue Apr 30 15:51:27 2013
New Revision: 387021

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=387021
Log:
Add some more doxygen to cdr.h

Modified:
    team/mjordan/cdrs-of-doom/include/asterisk/cdr.h

Modified: team/mjordan/cdrs-of-doom/include/asterisk/cdr.h
URL: http://svnview.digium.com/svn/asterisk/team/mjordan/cdrs-of-doom/include/asterisk/cdr.h?view=diff&rev=387021&r1=387020&r2=387021
==============================================================================

--- team/mjordan/cdrs-of-doom/include/asterisk/cdr.h (original)
+++ team/mjordan/cdrs-of-doom/include/asterisk/cdr.h Tue Apr 30 15:51:27 2013
@@ -170,88 +170,35 @@
  * As such, it takes A as its Party B.
  * \li New CDRs are generated. D gets new CDRs for D -> B and D -> C.
  *
- * The following transition can occur while in the DialedPending state:
- * \li If a \ref ast_bridge_blob_type is received or a \ref ast_channel_snapshot
- * is received that indicates that a Party B has left the bridge or hungup, the
- * state is transitioned to finalized.
- * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
- * state transitions to Bridge (through the Dial state)
-
- * Once a \ref stasis_message has been created, it is immutable and cannot
- * change. The same goes for the value of the message (although this cannot be
- * enforced in code). Messages themselves are reference-counted, AO2 objects,
- * along with their values. By being both reference counted and immutable,
- * messages can be shared throughout the system without any concerns for
- * threading.
- *
- * The type of a message is defined by an instance of \ref stasis_message_type,
- * which can be created by calling stasis_message_type_create(). Message types
- * are named, which is useful in debugging. It is recommended that the string
- * name for a message type match the name of the struct that's stored in the
- * message. For example, name for \ref stasis_cache_update's message type is \c
- * "stasis_cache_update".
- *
- * \par stasis_topic
- *
- * A \ref stasis_topic is an object to which \ref stasis_subscriber's may be
- * subscribed, and \ref stasis_message's may be published. Any message published
- * to the topic is dispatched to all of its subscribers. The topic itself may be
- * named, which is useful in debugging.
- *
- * Topics themselves are reference counted objects. Since topics are referred to
- * by their subscibers, they will not be freed until all of their subscribers
- * have unsubscribed. Topics are also thread safe, so no worries about
- * publishing/subscribing/unsubscribing to a topic concurrently from multiple
- * threads. It's also designed to handle the case of unsubscribing from a topic
- * from within the subscription handler.
- *
- * \par Forwarding
- *
- * There is one special case of topics that's worth noting: forwarding
- * messages. It's a fairly common use case to want to forward all the messages
- * published on one topic to another one (for example, an aggregator topic that
- * publishes all the events from a set of other topics). This can be
- * accomplished easily using stasis_forward_all(). This sets up the forwarding
- * between the two topics, and returns a \ref stasis_subscription, which can be
- * unsubscribed to stop the forwarding.
- *
- * \par Caching
- *
- * Another common use case is to want to cache certain messages that are
- * published on the bus. Usually these events are snapshots of the current state
- * in the system, and it's desirable to query that state from the cache without
- * locking the original object. It's also desirable for subscribers of the
- * caching topic to receive messages that have both the old cache value and the
- * new value being put into the cache. For this, we have
- * stasis_caching_topic_create(), providing it with the topic which publishes
- * the messages that you wish to cache, and a function that can identify
- * cacheable messages.
- *
- * The returned \ref stasis_caching_topic provides a topic that forwards
- * non-cacheable messages unchanged. A cacheable message is wrapped in a \ref
- * stasis_cache_update message which provides the old snapshot (or \c NULL if
- * this is a new cache entry), and the new snapshot (or \c NULL if the entry was
- * removed from the cache). A stasis_cache_clear_create() message must be sent
- * to the topic in order to remove entries from the cache.
- *
- * In order to unsubscribe a \ref stasis_caching_topic from the upstream topic,
- * call stasis_caching_unsubscribe(). Due to cyclic references, the \ref
- * stasis_caching_topic will not be freed until after it has been unsubscribed,
- * and all other ao2_ref()'s have been cleaned up.
- *
- * \par stasis_subscriber
- *
- * Any topic may be subscribed to by simply providing stasis_subscribe() the
- * \ref stasis_topic to subscribe to, a handler function and \c void pointer to
- * data that is passed back to the handler. Invocations on the subscription's
- * handler are serialized, but different invocations may occur on different
- * threads (this usually isn't important unless you use thread locals or
- * something similar).
- *
- * In order to stop receiving messages, call stasis_unsubscribe() with your \ref
- * stasis_subscription. Due to cyclic references, the \ref
- * stasis_subscription will not be freed until after it has been unsubscribed,
- * and all other ao2_ref()'s have been cleaned up.
+ * The following transitions can occur while in the Bridge state:
+ * \li If a \ref ast_bridge_blob_type message indicating a leave is received,
+ * the state transitions to the Pending state
+ *
+ * \par Pending
+ *
+ * After a channel leaves a bridge, we often don't know what's going to happen
+ * to it. It can enter another bridge; it can be hung up; it can continue on
+ * in the dialplan. It can even enter into limbo! Pending holds the state of the
+ * CDR until we get a subsequent Stasis message telling us what should happen.
+ *
+ * The following transitions can occur while in the Pending state:
+ * \li If a \ref ast_bridge_blob_type message is received, a new CDR is created
+ * and it is transitioned to the Bridge state
+ * \li If a \ref ast_channel_dial_type indicating a Dial Begin is received, a
+ * new CDR is created and it is transitioned to the Dial state
+ * \li If a \ref ast_channel_cache_update is received indicating a change in
+ * Context/Extension/Priority, a new CDR is created and transitioned to the
+ * Single state. If the update indicates that the party has been hung up, the
+ * CDR is transitioned to the Finalized state.
+ *
+ * \par Finalized
+ *
+ * Once a CDR enters the finalized state, it is finished. No further updates
+ * can be made to the party information, and the CDR cannot be changed.
+ *
+ * One exception to this occurs during linkedid propagation, in which the CDRs
+ * linkedids are updated based on who the channel is bridged with. In general,
+ * however, a finalized CDR is waiting for dispatch to the CDR backends.
  */
 
 /*! \brief CDR engine settings */


