AMI: Add documentation for the missing Cdr/CEL events.

This patch adds AMI event documentation for the Cdr and CEL AMI events.

Note that while these events do share fields with each other and with other
channel related events, they do not contain all of the fields in a standard
channel snapshot, nor is the description of the fields identical. As such,
the patch opts for documentation for each field, for each event.

Review: https://reviewboard.asterisk.org/r/4350/

ASTERISK-24671 #close
Reported by: Dan Jenkins


git-svn-id: https://origsvn.digium.com/svn/asterisk/branches/13@430862 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 286 insertions, 0 deletions

diff --git a/cdr/cdr_manager.c b/cdr/cdr_manager.c
index 97e51e1fc..4fd5fdf61 100644
--- a/cdr/cdr_manager.c
+++ b/cdr/cdr_manager.c
@@ -38,6 +38,132 @@
 	<support_level>core</support_level>
  ***/
 
+/*** DOCUMENTATION
+	<managerEvent language="en_US" name="Cdr">
+		<managerEventInstance class="EVENT_FLAG_CDR">
+			<synopsis>Raised when a CDR is generated.</synopsis>
+			<syntax>
+				<parameter name="AccountCode">
+					<para>The account code of the Party A channel.</para>
+				</parameter>
+				<parameter name="Source">
+					<para>The Caller ID number associated with the Party A in the CDR.</para>
+				</parameter>
+				<parameter name="Destination">
+					<para>The dialplan extension the Party A was executing.</para>
+				</parameter>
+				<parameter name="DestinationContext">
+					<para>The dialplan context the Party A was executing.</para>
+				</parameter>
+				<parameter name="CallerID">
+					<para>The Caller ID name associated with the Party A in the CDR.</para>
+				</parameter>
+				<parameter name="Channel">
+					<para>The channel name of the Party A.</para>
+				</parameter>
+				<parameter name="DestinationChannel">
+					<para>The channel name of the Party B.</para>
+				</parameter>
+				<parameter name="LastApplication">
+					<para>The last dialplan application the Party A executed.</para>
+				</parameter>
+				<parameter name="LastData">
+					<para>
+						The parameters passed to the last dialplan application the
+						Party A executed.
+					</para>
+				</parameter>
+				<parameter name="StartTime">
+					<para>The time the CDR was created.</para>
+				</parameter>
+				<parameter name="AnswerTime">
+					<para>
+						The earliest of either the time when Party A answered, or
+						the start time of this CDR.
+					</para>
+				</parameter>
+				<parameter name="EndTime">
+					<para>
+						The time when the CDR was finished. This occurs when the
+						Party A hangs up or when the bridge between Party A and
+						Party B is broken.
+					</para>
+				</parameter>
+				<parameter name="Duration">
+					<para>The time, in seconds, of <replaceable>EndTime</replaceable> - <replaceable>StartTime</replaceable>.</para>
+				</parameter>
+				<parameter name="BillableSeconds">
+					<para>The time, in seconds, of <replaceable>AnswerTime</replaceable> - <replaceable>StartTime</replaceable>.</para>
+				</parameter>
+				<parameter name="Disposition">
+					<para>The final known disposition of the CDR.</para>
+					<enumlist>
+						<enum name="NO ANSWER">
+							<para>The channel was not answered. This is the default disposition.</para>
+						</enum>
+						<enum name="FAILED">
+							<para>The channel attempted to dial but the call failed.</para>
+							<note>
+								<para>The congestion setting in <filename>cdr.conf</filename> can result
+								in the <literal>AST_CAUSE_CONGESTION</literal> hang up cause or the
+								<literal>CONGESTION</literal> dial status to map to this disposition.
+								</para>
+							</note>
+						</enum>
+						<enum name="BUSY">
+							<para>The channel attempted to dial but the remote party was busy.</para>
+						</enum>
+						<enum name="ANSWERED">
+							<para>The channel was answered. The hang up cause will no longer
+							impact the disposition of the CDR.</para>
+						</enum>
+						<enum name="CONGESTION">
+							<para>The channel attempted to dial but the remote party was congested.</para>
+						</enum>
+					</enumlist>
+				</parameter>
+				<parameter name="AMAFlags">
+					<para>A flag that informs a billing system how to treat the CDR.</para>
+					<enumlist>
+						<enum name="OMIT">
+							<para>This CDR should be ignored.</para>
+						</enum>
+						<enum name="BILLING">
+							<para>This CDR contains valid billing data.</para>
+						</enum>
+						<enum name="DOCUMENTATION">
+							<para>This CDR is for documentation purposes.</para>
+						</enum>
+					</enumlist>
+				</parameter>
+				<parameter name="UniqueID">
+					<para>A unique identifier for the Party A channel.</para>
+				</parameter>
+				<parameter name="UserField">
+					<para>
+						A user defined field set on the channels. If set on both the Party A
+						and Party B channel, the userfields of both are concatenated and
+						separated by a <literal>;</literal>.
+					</para>
+				</parameter>
+			</syntax>
+			<description>
+				<para>
+					The <replaceable>Cdr</replaceable> event is only raised when the
+					<filename>cdr_manager</filename> backend is loaded and registered with
+					the CDR engine.
+				</para>
+				<note>
+					<para>
+						This event can contain additional fields depending on the configuration
+						provided by <filename>cdr_manager.conf</filename>.
+					</para>
+				</note>
+			</description>
+		</managerEventInstance>
+	</managerEvent>
+ ***/
+
 #include "asterisk.h"
 
 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
diff --git a/cel/cel_manager.c b/cel/cel_manager.c
index f0d081c8d..b3ff6a5de 100644
--- a/cel/cel_manager.c
+++ b/cel/cel_manager.c
@@ -33,6 +33,166 @@
 	<support_level>core</support_level>
  ***/
 
+/*** DOCUMENTATION
+	<managerEvent language="en_US" name="CEL">
+		<managerEventInstance class="EVENT_FLAG_CEL">
+			<synopsis>Raised when a Channel Event Log is generated for a channel.</synopsis>
+			<syntax>
+				<parameter name="EventName">
+					<para>
+						The name of the CEL event being raised. This can include
+						both the system defined CEL events, as well as user defined
+						events.
+					</para>
+					<note>
+						<para>All events listed here may not be raised, depending
+						on the configuration in <filename>cel.conf</filename>.</para>
+					</note>
+					<enumlist>
+						<enum name="CHAN_START">
+							<para>A channel was created.</para>
+						</enum>
+						<enum name="CHAN_END">
+							<para>A channel was terminated.</para>
+						</enum>
+						<enum name="ANSWER">
+							<para>A channel answered.</para>
+						</enum>
+						<enum name="HANGUP">
+							<para>A channel was hung up.</para>
+						</enum>
+						<enum name="BRIDGE_ENTER">
+							<para>A channel entered a bridge.</para>
+						</enum>
+						<enum name="BRIDGE_EXIT">
+							<para>A channel left a bridge.</para>
+						</enum>
+						<enum name="APP_START">
+							<para>A channel entered into a tracked application.</para>
+						</enum>
+						<enum name="APP_END">
+							<para>A channel left a tracked application.</para>
+						</enum>
+						<enum name="PARK_START">
+							<para>A channel was parked.</para>
+						</enum>
+						<enum name="PARK_END">
+							<para>A channel was unparked.</para>
+						</enum>
+						<enum name="BLINDTRANSFER">
+							<para>A channel initiated a blind transfer.</para>
+						</enum>
+						<enum name="ATTENDEDTRANSFER">
+							<para>A channel initiated an attended transfer.</para>
+						</enum>
+						<enum name="PICKUP">
+							<para>A channel initated a call pickup.</para>
+						</enum>
+						<enum name="FORWARD">
+							<para>A channel is being forwarded to another destination.</para>
+						</enum>
+						<enum name="LINKEDID_END">
+							<para>The linked ID associated with this channel is being retired.</para>
+						</enum>
+						<enum name="LOCAL_OPTIMIZE">
+							<para>A Local channel optimization has occurred.</para>
+						</enum>
+						<enum name="USER_DEFINED">
+							<para>A user defined type.</para>
+							<note>
+								<para>
+									This event is only present if <literal>show_user_defined</literal>
+									in <filename>cel.conf</filename> is <literal>True</literal>. Otherwise,
+									the user defined event will be placed directly in the
+									<replaceable>EventName</replaceable> field.
+								</para>
+							</note>
+						</enum>
+					</enumlist>
+				</parameter>
+				<parameter name="AccountCode">
+					<para>The channel's account code.</para>
+				</parameter>
+				<parameter name="CallerIDnum">
+					<para>The Caller ID number.</para>
+				</parameter>
+				<parameter name="CallerIDname">
+					<para>The Caller ID name.</para>
+				</parameter>
+				<parameter name="CallerIDani">
+					<para>The Caller ID Automatic Number Identification.</para>
+				</parameter>
+				<parameter name="CallerIDrdnis">
+					<para>The Caller ID Redirected Dialed Number Identification Service.</para>
+				</parameter>
+				<parameter name="CallerIDdnid">
+					<para>The Caller ID Dialed Number Identifier.</para>
+				</parameter>
+				<parameter name="Exten">
+					<para>The dialplan extension the channel is currently executing in.</para>
+				</parameter>
+				<parameter name="Context">
+					<para>The dialplan context the channel is currently executing in.</para>
+				</parameter>
+				<parameter name="Application">
+					<para>The dialplan application the channel is currently executing.</para>
+				</parameter>
+				<parameter name="AppData">
+					<para>The arguments passed to the dialplan <replaceable>Application</replaceable>.</para>
+				</parameter>
+				<parameter name="EventTime">
+					<para>The time the CEL event occurred.</para>
+				</parameter>
+				<parameter name="AMAFlags">
+					<para>A flag that informs a billing system how to treat the CEL.</para>
+					<enumlist>
+						<enum name="OMIT">
+							<para>This event should be ignored.</para>
+						</enum>
+						<enum name="BILLING">
+							<para>This event contains valid billing data.</para>
+						</enum>
+						<enum name="DOCUMENTATION">
+							<para>This event is for documentation purposes.</para>
+						</enum>
+					</enumlist>
+				</parameter>
+				<parameter name="UniqueID">
+					<para>The unique ID of the channel.</para>
+				</parameter>
+				<parameter name="LinkedID">
+					<para>The linked ID of the channel, which ties this event to other related channel's events.</para>
+				</parameter>
+				<parameter name="UserField">
+					<para>
+						A user defined field set on a channel, containing arbitrary
+						application specific data.
+					</para>
+				</parameter>
+				<parameter name="Peer">
+					<para>
+						If this channel is in a bridge, the channel that it is in
+						a bridge with.
+					</para>
+				</parameter>
+				<parameter name="PeerAccount">
+					<para>
+						If this channel is in a bridge, the accountcode of the
+						channel it is in a bridge with.
+					</para>
+				</parameter>
+				<parameter name="Extra">
+					<para>
+						Some events will have event specific data that accompanies the CEL record.
+						This extra data is JSON encoded, and is dependent on the event in
+						question.
+					</para>
+				</parameter>
+			</syntax>
+		</managerEventInstance>
+	</managerEvent>
+ ***/
+
 #include "asterisk.h"
 
 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")