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

[Mark Michelson]

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



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24055>

    I think the hint line is the verbatim hint from the dialplan and therefore can contain devices as well as presences.



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24058>

    This explanation is a bit "programmer-y", and it's also not really correct. The mention of powers of 2 and bitflags is really unnecessary and just makes this sound more complex than it needs to be.
    
    In addition, it's not really possible for any of the states to combine with each other. As you have noted in the StatusText portion, the only states that can be combined are inuse&ringing, and inuse&hold.
    
    With all that said, I think the explanation of Status can be simplified down to something like "A numerical representation of the extension state". The enumeration afterwards can list all of the possible states and what they mean. You'll just need to add states 9 and 17 for Inuse&Ringing and Inuse&Hold.



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24056>

    Consider placing <literal> tags around the words "inuse" and "busy" to make them stand out more when printing help on the CLI.



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24059>

    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.



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24057>

    "UNREGISTERED" appears in all caps here as if to indicate it as a device state. However, UNREGISTERED is not a valid device state.



/branches/13/main/manager.c
<https://reviewboard.asterisk.org/r/4085/#comment24054>

    The second sentence needs some work. I don't know what you mean by "more strictly defined". More strictly defined than what? Also, I'm not a big fan of the word "thing". Maybe "selection" or "item" would work better?


- Mark Michelson


On Oct. 15, 2014, 7: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, 7: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/20141015/3bddec4b/attachment-0001.html>