Review Board 1.7.16

Add AMI event documentation

Review Request #1967 - Created June 5, 2012 and submitted

Matt Jordan
mmichelson, wdoekes
This patch begins to add AMI event documentation to Asterisk.  This patch includes the following:

* Pulling AMI event XML documentation out of the Asterisk source and into the XML documentation produced by the build tools
* Validating the XML when -dev-mode is enabled
* Reading/parsing the XML documentation when Asterisk starts
* Two new CLI commands: 'manager show events' and 'manager show event [event_name]'
* Event documentation for the core applications

So... AMI events are a bit trickier then other things we've attempted to document in the past.  There were a number of factors to consider when approaching this:
1. There are a lot of AMI events, and they are located throughout the code base
2. AMI events can occur multiple times with different parameters, but still be the same 'event' type
3. AMI events can occur multiple times, in different implementation files
4. There is a significant amount of repeated information between events
5. Much of the information that a person cares about (AMI event keys) are - more often then not - easily obtained from a method call

To that end, documentation for AMI events is treated a bit differently then other items.  There are a few major shifts in how the documentation is extracted:
1. The previous documentation extraction used an awk script that pulled the documentation from a single comment block (delineated by /*** DOCUMENTATION ... ***/).  That still exists; however, if you want AMI event documentation, you have to use 'make full'.  This calls a different documentation extraction script, written in python.  That script lets us do a few things that the awk script did not:
 * Documentation can now exist anywhere in the source file
 * The documentation for manager events can be co-located with the method calls that raise the event.  If the method call is recognized, event parameters are automatically read from the method call and populated in the documentation
 * Documentation is combined where appropriate.  Thus, if the same event is raised in multiple places, the parameters only need to be defined once.
2. Previously, documentation was registered with the application/function/command that it was associated with.  Events are never registered with any controller; requiring them to do so would incur a run-time performance penalty for little gain.  Hence, the xmldoc core now allow documentation for an entire source type to be requested at run-time.  When requested, the documentation is built from the XML read in.

Example manager events:

Event: ChanSpyStart
Raised when a channel has started spying on another channel.

Event: ChanSpyStart
SpyerChannel: <value>
SpyeeChannel: <value>

[See Also]
ChanSpy(), ExtenSpy(), ChanSpyStop


Event: Dial
Raised when a dial action has started.

Event: Dial
SubEvent: <value>
Channel: <value>
Destination: <value>
CallerIDNum: <value>
CallerIDName: <value>
ConnectedLineNum: <value>
ConnectedLineName: <value>
UniqueID: <value>
DestUniqueID: <value>
Dialstring: <value>

    A sub event type, specifying whether or not the dial action has begun
    or ended.

Raised when a dial action has ended.

Event: Dial
DialStatus: <value>
SubEvent: <value>
Channel: <value>
UniqueID: <value>

    The value of the ${DIALSTATUS} channel variable.
    A sub event type, specifying whether or not the dial action has begun
    or ended.


Event: QueueMemberStatus
Raised when a Queue member's status has changed.

Event: QueueMemberStatus
Queue: <value>
Location: <value>
MemberName: <value>
StateInterface: <value>
Membership: <value>
Penalty: <value>
CallsTaken: <value>
LastCall: <value>
Status: <value>
Paused: <value>

    The name of the queue.
    The queue member's channel technology or location.
    The name of the queue member.
    Channel technology or location from which to read device state
    The penalty associated with the queue member.
    The number of calls this queue member has serviced.
    The time this member last took call, expressed in seconds since 00:00,
    Jan 1, 1970 UTC.
    The status of the queue member.  This will be a device state value.

Review request changed
Updated (June 11, 2012, 4:13 a.m.)
Addressed Russell's findings.
Posted (June 18, 2012, 9:42 a.m.)
Bumping this again for more review.
Ship it!
Posted (June 19, 2012, 8:53 a.m.)
As far as I'm concerned, this is the way to go and what you have looks like a good method of doing things. I know there were questions from others about having documentation with the events rather than at the top of the file. I think your answers have mostly swayed people to seeing things your way, but I'd hesitate on moving forward just in case there are still some valid complaints from people about the proposed method.
./apps/app_dial.c (Diff revision 3)
I think the "or not" needs to be removed from this sentence. runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to