chan_dahdi: Fix wrong channel state when RINGING recieved.

Previously, when AST_CONTROL_RINGING was received by
a DAHDI device, it would set its channel state to
AST_STATE_RINGING. However, an analysis of the codebase
and other channel drivers reveals RINGING corresponds to
physical power ringing, whereas AST_STATE_RING should be
used for audible ringback on the channel. This also ensures
the correct device state is returned by the channel state
to device state conversion.

Since there seems to be confusion in various places regarding
AST_STATE_RING vs. AST_STATE_RINGING, some documentation has
been added or corrected to clarify the actual purposes of these
two channel states, and the associated device state mapping.

An edge case that prompted this fix, but isn't explicitly
addressed here, is that of an incoming call to an FXO port.
The channel state will be "Ring", which maps to a device state
of "In Use", not "Ringing" as would be more intuitive. However,
this is semantic, since technically, Asterisk is treating this
the same as any other incoming call, and so "Ring" is the
semantic state (put another way, Asterisk isn't ringing anything,
like in the cases where channels are in the "Ringing" state).

Since FXO ports don't currently support Call Waiting, a suitable
workaround for the above would be to ignore the device state and
instead check the channel state (e.g. IMPORT(DAHDI/1-1,CHANNEL(state)))
since it will be Ring if the FXO port is idle (but a call is ringing
on it) and Up if the FXO port is actually in use. (In both cases,
the device state would misleadingly be "In Use".)

Resolves: #1029

diff --git a/channels/chan_dahdi.c b/channels/chan_dahdi.c
index 7db72836ac607bba7a8431d75be396f10dd5a1a1..42bd2360a2a202f5ab25057104d8e056b4647b28 100644 (file)
--- a/channels/chan_dahdi.c
+++ b/channels/chan_dahdi.c
@@ -9395,8 +9395,11 @@ static int dahdi_indicate(struct ast_channel *chan, int condition, const void *d
                                if ((ast_channel_state(chan) != AST_STATE_RING) ||
                                        ((p->sig != SIG_FXSKS) &&
                                 (p->sig != SIG_FXSLS) &&
-                                (p->sig != SIG_FXSGS)))
-                               ast_setstate(chan, AST_STATE_RINGING);
+                                (p->sig != SIG_FXSGS))) {
+                                       /* We're playing audible ringback tone on the channel,
+                                        * so set state to AST_STATE_RING, not AST_STATE_RINGING. */
+                                       ast_setstate(chan, AST_STATE_RING);
+                               }
                        }
                        break;
                case AST_CONTROL_INCOMPLETE:

diff --git a/include/asterisk/channelstate.h b/include/asterisk/channelstate.h
index 08f908256d8760fb71089955a7ee6d4464b0026e..e453c6f2fecc18dce278ee604803d622921bcb75 100644 (file)
--- a/include/asterisk/channelstate.h
+++ b/include/asterisk/channelstate.h
@@ -37,8 +37,8 @@ enum ast_channel_state {
        AST_STATE_RESERVED,             /*!< Channel is down, but reserved */
        AST_STATE_OFFHOOK,              /*!< Channel is off hook */
        AST_STATE_DIALING,              /*!< Digits (or equivalent) have been dialed */
-       AST_STATE_RING,                 /*!< Line is ringing */
-       AST_STATE_RINGING,              /*!< Remote end is ringing */
+       AST_STATE_RING,                 /*!< Remote end is ringing (e.g. listening to audible ringback tone). Also often used for initial state for a new channel. */
+       AST_STATE_RINGING,              /*!< Line is ringing */
        AST_STATE_UP,                   /*!< Line is up */
        AST_STATE_BUSY,                 /*!< Line is busy */
        AST_STATE_DIALING_OFFHOOK,      /*!< Digits (or equivalent) have been dialed while offhook */

diff --git a/main/devicestate.c b/main/devicestate.c
index a964f64f6df5bf52e5e109494972cc062a8bdef8..a47d1df1c519535463c755a0615de1656728867e 100644 (file)
--- a/main/devicestate.c
+++ b/main/devicestate.c
@@ -179,8 +179,8 @@ static const struct chan2dev {
        { AST_STATE_RESERVED,        AST_DEVICE_INUSE },
        { AST_STATE_OFFHOOK,         AST_DEVICE_INUSE },
        { AST_STATE_DIALING,         AST_DEVICE_INUSE },
-       { AST_STATE_RING,            AST_DEVICE_INUSE },
-       { AST_STATE_RINGING,         AST_DEVICE_RINGING },
+       { AST_STATE_RING,            AST_DEVICE_INUSE }, /* Audible ringback tone */
+       { AST_STATE_RINGING,         AST_DEVICE_RINGING }, /* Actual ringing */
        { AST_STATE_UP,              AST_DEVICE_INUSE },
        { AST_STATE_BUSY,            AST_DEVICE_BUSY },
        { AST_STATE_DIALING_OFFHOOK, AST_DEVICE_INUSE },