[asterisk-dev] [Code Review] 4085: ExtensionStatus: Add additional documentation describing the ExtensionStatus event

[Jonathan Rose]

> On Oct. 15, 2014, 4:30 p.m., Mark Michelson wrote:
> > /branches/13/main/manager.c, line 1225
> > <https://reviewboard.asterisk.org/r/4085/diff/1/?file=68352#file68352line1225>
> >
> >     In an experiment, I had one busy and one inuse device in a hint, and the ExtensionStatus showed 2 as the status. So I don't think all devices have to be busy for 2 to be shown. In fact, I think all of the "all devices are ..." explanations in this section are incorrect.
> >     
> >     I believe the device state aggregation rules determine which status is reported here when multiple devices have different statuses. If you have a look at ast_devstate_aggregate_add() in devicestate.c, you can find how the device states combine to form an extension state.
> >     
> >     Now, having pointed this out, I don't think it's really necessary to try to transcribe that code into an English explanation. I think it's acceptable to state for each individual state here that Asterisk has determined that the combined state of the devices is that extension state, as well as a high-level explanation of what that extension state means. If people want a deeper explanation of how Asterisk came to that conclusion, we can write a wiki article that goes more in-depth.

I got these rules directly from the comments describing the ast_extension_states enumerator in pbx.h, so they might need a look at some point.

I'll do as you suggested though and not attempt to describe specific rules for how they are determined.


- Jonathan


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/4085/#review13529
-----------------------------------------------------------


On Oct. 15, 2014, 2:01 p.m., Jonathan Rose wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/4085/
> -----------------------------------------------------------
> 
> (Updated Oct. 15, 2014, 2:01 p.m.)
> 
> 
> Review request for Asterisk Developers, Matt Jordan and Mark Michelson.
> 
> 
> Repository: Asterisk
> 
> 
> Description
> -------
> 
> Some internals developers pointed out that this event was poorly documented, particularly when it comes to Status and StatusText which really need to be explained in order to be useful.
> 
> 
> Diffs
> -----
> 
>   /branches/13/main/manager.c 425546 
> 
> Diff: https://reviewboard.asterisk.org/r/4085/diff/
> 
> 
> Testing
> -------
> 
> Checked the output of
> 
> > manager show event ExtensionStatus
> 
> Exten
>     Name of the extension.
> Context
>     Context that owns the extension.
> Hint
>     Devices mapped to the extension which determine the extension status
> Status
>     Numerical data indicating the status of the extension based on its
>     devices. Negative values indicate that the extension was removed (-2)
>     or deactivated (-1). Zero indicates that the extension is idle. Positive
>     values work as bitflags and may combine to indicate different things.
>     For example 1 would mean inuse, 2 would mean busy, and the two can add
>     together additively into 3 to mean that a line is both inuse and busy.
>     Each of the major classifications is a power of two and they can
>     potentailly be added in any combination.
>     -2 - Removed - The extension was removed. Not additive.
>     -1 - Deactivated - The extension's hit was removed. Not additive.
>     0 - Idle - No device INUSE or BUSY. Not additive.
>     1 - In Use - one or more devices INUSE. Additive.
>     2 - Busy - All devices are BUSY. Additive.
>     4 - Unavailable - All devices are UNAVAILABLE and/or UNREGISTERED.
>     Additive.
>     8 - Ringing - All devices are RINGING. Additive.
>     16 - Onhold - All devices are ONHOLD. Additive.
> StatusText
>     Human readable representation of the status. The options are also
>     more strictly defined and may only be one thing from the following
>     enumerator.
>     Idle - No device INUSE or BUSY.
>     InUse - One or more devices are INUSE.
>     Busy - All devices are BUSY.
>     Unavailable - All devices are UNAVAILABLE and/or UNREGISTERED
>     Ringing - All devices are RINGING
>     InUse&Ringing - All devices are RINGING and one or more devices are
>     INUSE
>     Hold - All devices are ONHOLD.
>     InUse&Hold - All devices are ONHOLD and one or more devices are INUSE
>     Unknown - None of the above descriptions matched the status
>     value
> 
> 
> Thanks,
> 
> Jonathan Rose
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20141016/7e093154/attachment-0001.html>