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
(cherry picked from commit afd15274e7)

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:

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 */

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 },