[svn-commits] mmichelson: branch mmichelson/atxfer_features r393357 - /team/mmichelson/atxf...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Mon Jul 1 16:10:58 CDT 2013
Author: mmichelson
Date: Mon Jul 1 16:10:57 2013
New Revision: 393357
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=393357
Log:
Add detailed state documentation.
Modified:
team/mmichelson/atxfer_features/main/bridging_basic.c
Modified: team/mmichelson/atxfer_features/main/bridging_basic.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/atxfer_features/main/bridging_basic.c?view=diff&rev=393357&r1=393356&r2=393357
==============================================================================
--- team/mmichelson/atxfer_features/main/bridging_basic.c (original)
+++ team/mmichelson/atxfer_features/main/bridging_basic.c Mon Jul 1 16:10:57 2013
@@ -327,41 +327,506 @@
return "default";
}
+/*!
+ * \brief Attended transfer superstates.
+ *
+ * An attended transfer's progress is facilitated by a state machine.
+ * The individual states of the state machine fall into the realm of
+ * one of two superstates.
+ */
enum attended_transfer_superstate {
- STATE_TRANSFER,
- STATE_RECALL,
+ /*!
+ * \brief Transfer superstate
+ *
+ * The attended transfer state machine begins in this superstate. The
+ * goal of this state is for a transferer channel to facilitate a
+ * transfer from a transferee to a transfer target.
+ *
+ * There are two bridges used in this superstate. The transferee bridge is
+ * the bridge that the transferer and transferee channels originally
+ * communicate in, and the target bridge is the bridge where the transfer
+ * target is being dialed.
+ *
+ * The transferer channel is capable of moving between the bridges using
+ * the DTMF swap sequence.
+ */
+ SUPERSTATE_TRANSFER,
+ /*!
+ * \brief Recall superstate
+ *
+ * The attended transfer state machine moves to this superstate if
+ * atxferdropcall is set to "no" and the transferer channel hangs up
+ * during a transfer. The goal in this superstate is to call back either
+ * the transfer target or transferer and rebridge with the transferee
+ * channel(s).
+ *
+ * In this superstate, there is only a single bridge used, the original
+ * transferee bridge. Rather than distinguishing between a transferer
+ * and transfer target, all outbound calls are toward a "recall_target"
+ * channel.
+ */
+ SUPERSTATE_RECALL,
};
+/*!
+ * The states in the attended transfer state machine.
+ */
enum attended_transfer_state {
- /* Transfer target is ringing, Transferer is in target bridge */
+ /*!
+ * \brief Calling Target state
+ *
+ * This state describes the initial state of a transfer. The transferer
+ * waits in the transfer target's bridge for the transfer target to answer.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is RINGING
+ * 2) Transferer is in transferee bridge
+ * 3) Transferee is on hold
+ *
+ * Transitions to TRANSFER_CALLING_TARGET:
+ * 1) This is the initial state for an attended transfer.
+ * 2) TRANSFER_HESITANT: Transferer presses DTMF swap sequence
+ *
+ * State operation:
+ * The transferer is moved from the transferee bridge into the transfer
+ * target bridge.
+ *
+ * Transitions from TRANSFER_CALLING_TARGET:
+ * 1) TRANSFER_FAIL: Transferee hangs up.
+ * 2) TRANSFER_BLOND: Transferer hangs up or presses DTMF swap sequence
+ * and configured atxferdropcall setting is yes.
+ * 3) TRANSFER_BLOND_NONFINAL: Transferer hangs up or presses DTMF swap
+ * sequence and configured atxferdroppcall setting is no.
+ * 4) TRANSFER_CONSULTING: Transfer target answers the call.
+ * 5) TRANSFER_REBRIDGE: Transfer target hangs up, call to transfer target
+ * times out, or transferer presses DTMF abort sequence.
+ * 6) TRANSFER_THREEWAY: Transferer presses DTMF threeway sequence.
+ * 7) TRANSFER_HESITANT: Transferer presses DTMF swap sequence.
+ */
TRANSFER_CALLING_TARGET,
- /* Transfer target is ringing, Transferer is in transferee bridge */
+ /*!
+ * \brief Hesitant state
+ *
+ * This state only arises if when waiting for the transfer target to
+ * answer, the transferer presses the DTMF swap sequence. This will
+ * cause the transferer to be rebridged with the transferee temporarily.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is in ringing state
+ * 2) Transferer is in transfer target bridge
+ * 3) Transferee is on hold
+ *
+ * Transitions to TRANSFER_HESITANT:
+ * 1) TRANSFER_CALLING_TARGET: Transferer presses DTMF swap sequence.
+ *
+ * State operation:
+ * The transferer is moved from the transfer target bridge into the
+ * transferee bridge, and the transferee is taken off hold.
+ *
+ * Transitions from TRANSFER_HESITANT:
+ * 1) TRANSFER_FAIL: Transferee hangs up
+ * 2) TRANSFER_BLOND: Transferer hangs up or presses DTMF swap sequence
+ * and configured atxferdropcall setting is yes.
+ * 3) TRANSFER_BLOND_NONFINAL: Transferer hangs up or presses DTMF swap
+ * sequence and configured atxferdroppcall setting is no.
+ * 4) TRANSFER_DOUBLECHECKING: Transfer target answers the call
+ * 5) TRANSFER_RESUME: Transfer target hangs up, call to transfer target
+ * times out, or transferer presses DTMF abort sequence.
+ * 6) TRANSFER_THREEWAY: Transferer presses DTMF threeway sequence.
+ * 7) TRANSFER_CALLING_TARGET: Transferer presses DTMF swap sequence.
+ */
TRANSFER_HESITANT,
- /* Transfer is aborted, Transferer is in target bridge */
+ /*!
+ * \brief Rebridge state
+ *
+ * This is a terminal state that indicates that the transferer needs
+ * to move back to the transferee's bridge. This is a failed attended
+ * transfer result.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transferer is in transfer target bridge
+ * 2) Transferee is on hold
+ *
+ * Transitions to TRANSFER_REBRIDGE:
+ * 1) TRANSFER_CALLING_TARGET: Transfer target hangs up, call to transfer target
+ * times out, or transferer presses DTMF abort sequence.
+ * 2) TRANSFER_STATE_CONSULTING: Transfer target hangs up, or transferer presses
+ * DTMF abort sequence.
+ *
+ * State operation:
+ * The transferer channel is moved from the transfer target bridge to the
+ * transferee bridge. The transferee is taken off hold. A stasis transfer
+ * message is published indicating a failed attended transfer.
+ *
+ * Transitions from TRANSFER_REBRIDGE:
+ * None
+ */
TRANSFER_REBRIDGE,
- /* Transfer is aborted, Transferer is in transferee bridge */
+ /*!
+ * \brief Resume state
+ *
+ * This is a terminal state that indicates that the party bridged with the
+ * transferee is the final party to be bridged with that transferee. This state
+ * may come about due to a successful recall or due to a failed transfer.
+ *
+ * Superstate: Transfer or Recall
+ *
+ * Preconditions:
+ * In Transfer Superstate:
+ * 1) Transferer is in transferee bridge
+ * 2) Transferee is not on hold
+ * In Recall Superstate:
+ * 1) The recall target is in the transferee bridge
+ * 2) Transferee is not on hold
+ *
+ * Transitions to TRANSFER_RESUME:
+ * TRANSFER_HESITANT: Transfer target hangs up, call to transfer target times out,
+ * or transferer presses DTMF abort sequence.
+ * TRANSFER_DOUBLECHECKING: Transfer target hangs up or transferer presses DTMF
+ * abort sequence.
+ * TRANSFER_BLOND_NONFINAL: Recall target answers
+ * TRANSFER_RECALLING: Recall target answers
+ * TRANSFER_RETRANSFER: Recall target answers
+ *
+ * State operations:
+ * None
+ *
+ * Transitions from TRANSFER_RESUME:
+ * None
+ */
TRANSFER_RESUME,
- /* Transfer has been turned into a three-way call */
+ /*!
+ * \brief Threeway state
+ *
+ * This state results when the transferer wishes to have all parties involved
+ * in a transfer to be in the same bridge together.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target state is either RINGING or UP
+ * 2) Transferer is in either bridge
+ * 3) Transferee is not on hold
+ *
+ * Transitions to TRANSFER_THREEWAY:
+ * 1) TRANSFER_CALLING_TARGET: Transferer presses DTMF threeway sequence.
+ * 2) TRANSFER_HESITANT: Transferer presses DTMF threeway sequence.
+ * 3) TRANSFER_CONSULTING: Transferer presses DTMF threeway sequence.
+ * 4) TRANSFER_DOUBLECHECKING: Transferer presses DTMF threeway sequence.
+ *
+ * State operation:
+ * The transfer target bridge is merged into the transferee bridge.
+ *
+ * Transitions from TRANSFER_THREEWAY:
+ * None.
+ */
TRANSFER_THREEWAY,
- /* The transfer target is up, Transferer is in the target bridge */
+ /*!
+ * \brief Consulting state
+ *
+ * This state describes the case where the transferer and transfer target
+ * are able to converse in the transfer target's bridge prior to completing
+ * the transfer.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is UP
+ * 2) Transferer is in target bridge
+ * 3) Transferee is on hold
+ *
+ * Transitions to TRANSFER_CONSULTING:
+ * 1) TRANSFER_CALLING_TARGET: Transfer target answers.
+ * 2) TRANSFER_DOUBLECHECKING: Transferer presses DTMF swap sequence.
+ *
+ * State operations:
+ * None.
+ *
+ * Transitions from TRANSFER_CONSULTING:
+ * TRANSFER_COMPLETE: Transferer hangs up or transferer presses DTMF complete sequence.
+ * TRANSFER_REBRIDGE: Transfer target hangs up or transferer presses DTMF abort sequence.
+ * TRANSFER_THREEWAY: Transferer presses DTMF threeway sequence.
+ * TRANSFER_DOUBLECHECKING: Transferer presses DTMF swap sequence.
+ */
TRANSFER_CONSULTING,
- /* The transfer target is up, Transferer is in the transferee bridge */
+ /*!
+ * \brief Double-checking state
+ *
+ * This state describes the case where the transferer and transferee are
+ * able to converse in the transferee's bridge prior to completing the transfer. The
+ * difference between this and TRANSFER_HESITANT is that the transfer target is
+ * UP in this case.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is UP and on hold
+ * 2) Transferer is in transferee bridge
+ * 3) Transferee is off hold
+ *
+ * Transitions to TRANSFER_DOUBLECHECKING:
+ * 1) TRANSFER_HESITANT: Transfer target answers.
+ * 2) TRANSFER_CONSULTING: Transferer presses DTMF swap sequence.
+ *
+ * State operations:
+ * None.
+ *
+ * Transitions from TRANSFER_DOUBLECHECKING:
+ * 1) TRANSFER_FAIL: Transferee hangs up.
+ * 2) TRANSFER_COMPLETE: Transferer hangs up or presses DTMF complete sequence.
+ * 3) TRANSFER_RESUME: Transfer target hangs up or transferer presses DTMF abort sequence.
+ * 4) TRANSFER_THREEWAY: Transferer presses DTMF threeway sequence.
+ * 5) TRANSFER_CONSULTING: Transferer presses the DTMF swap sequence.
+ */
TRANSFER_DOUBLECHECKING,
- /* The transfer has reached a successful conclusion */
+ /*!
+ * \brief Complete state
+ *
+ * This is a terminal state where a transferer has successfully completed an attended
+ * transfer. This state's goal is to get the transfer target and transferee into
+ * the same bridge and the transferer off the call.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is UP and off hold.
+ * 2) Transferer is in either bridge.
+ * 3) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_COMPLETE:
+ * 1) TRANSFER_CONSULTING: transferer hangs up or presses the DTMF complete sequence.
+ * 2) TRANSFER_DOUBLECHECKING: transferer hangs up or presses the DTMF complete sequence.
+ *
+ * State operation:
+ * The transfer target bridge is merged into the transferee bridge. The transferer
+ * channel is kicked out of the bridges as part of the merge.
+ *
+ * State operations:
+ * 1) Merge the transfer target bridge into the transferee bridge,
+ * excluding the transferer channel from the merge.
+ * 2) Publish a stasis transfer message.
+ *
+ * Exit operations:
+ * This is a terminal state, so there are no exit operations.
+ */
TRANSFER_COMPLETE,
- /* Transfer target is ringing, Transferer has hung up. atxferdropcall=yes */
+ /*!
+ * \brief Blond state
+ *
+ * This is a terminal state where a transferer has completed an attended transfer prior
+ * to the transfer target answering. This state is only entered if atxferdropcall
+ * is set to 'yes'. This is considered to be a successful attended transfer.
+ *
+ * Superstate: Transfer
+ *
+ * Preconditions:
+ * 1) Transfer target is RINGING.
+ * 2) Transferer is in either bridge.
+ * 3) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_BLOND:
+ * 1) TRANSFER_CALLING_TARGET: Transferer hangs up or presses the DTMF complete sequence.
+ * atxferdropcall is set to 'yes'.
+ * 2) TRANSFER_HESITANT: Transferer hangs up or presses the DTMF complete sequence.
+ * atxferdropcall is set to 'yes'.
+ *
+ * State operations:
+ * The transfer target bridge is merged into the transferee bridge. The transferer
+ * channel is kicked out of the bridges as part of the merge. A stasis transfer
+ * publication is sent indicating a successful transfer.
+ *
+ * Transitions from TRANSFER_BLOND:
+ * None
+ */
TRANSFER_BLOND,
- /* Transfer target is ringing, Transferer has hung up. atxferdropcall=no */
+ /*!
+ * \brief Blond non-final state
+ *
+ * This state is very similar to the TRANSFER_BLOND state, except that
+ * this state is entered when atxferdropcall is set to 'no'. This is the
+ * initial state of the Recall superstate, so state operations mainly involve
+ * moving to the Recall superstate. This means that the transfer target, that
+ * is currently ringing is now known as the recall target.
+ *
+ * Superstate: Recall
+ *
+ * Preconditions:
+ * 1) Recall target is RINGING.
+ * 2) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_BLOND_NONFINAL:
+ * 1) TRANSFER_CALLING_TARGET: Transferer hangs up or presses the DTMF complete sequence.
+ * atxferdropcall is set to 'no'.
+ * 2) TRANSFER_HESITANT: Transferer hangs up or presses the DTMF complete sequence.
+ * atxferdropcall is set to 'no'.
+ *
+ * State operation:
+ * The superstate of the attended transfer is changed from Transfer to Recall.
+ * The transfer target bridge is merged into the transferee bridge. The transferer
+ * channel is kicked out of the bridges as part of the merge.
+ *
+ * Transitions from TRANSFER_BLOND_NONFINAL:
+ * 1) TRANSFER_FAIL: Transferee hangs up
+ * 2) TRANSFER_RESUME: Recall target answers
+ * 3) TRANSFER_RECALLING: Recall target hangs up or time expires.
+ */
TRANSFER_BLOND_NONFINAL,
- /* Transfer target did not answer, re-call transferer */
+ /*!
+ * \brief Recalling state
+ *
+ * This state is entered if the recall target from the TRANSFER_BLOND_NONFINAL
+ * or TRANSFER_RETRANSFER states hangs up or does not answer. The goal of this
+ * state is to call back the original transferer in an attempt to recover the
+ * original call.
+ *
+ * Superstate: Recall
+ *
+ * Preconditions:
+ * 1) Recall target is down.
+ * 2) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_RECALLING:
+ * 1) TRANSFER_BLOND_NONFINAL: Recall target hangs up or time expires.
+ * 2) TRANSFER_RETRANSFER: Recall target hangs up or time expires.
+ * atxferloopdelay is non-zero.
+ * 3) TRANSFER_WAIT_TO_RECALL: Time expires.
+ *
+ * State operation:
+ * The original transferer becomes the recall target and is called using the Dialing API.
+ * Ringing is indicated to the transferee.
+ *
+ * Transitions from TRANSFER_RECALLING:
+ * 1) TRANSFER_FAIL:
+ * a) Transferee hangs up.
+ * b) Recall target hangs up or time expires, and number of recall attempts exceeds atxfercallbackretries
+ * 2) TRANSFER_WAIT_TO_RETRANSFER: Recall target hangs up or time expires.
+ * atxferloopdelay is non-zero.
+ * 3) TRANSFER_RETRANSFER: Recall target hangs up or time expires.
+ * atxferloopdelay is zero.
+ * 4) TRANSFER_RESUME: Recall target answers.
+ */
TRANSFER_RECALLING,
- /* Transferer did not answer re-call, wait a bit */
+ /*!
+ * \brief Wait to Retransfer state
+ *
+ * This state is used simply to give a bit of breathing room between attempting
+ * to call back the original transferer and attempting to call back the original
+ * transfer target. The transferee hears music on hold during this state as an
+ * auditory clue that no one is currently being dialed.
+ *
+ * Superstate: Recall
+ *
+ * Preconditions:
+ * 1) Recall target is down.
+ * 2) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_WAIT_TO_RETRANSFER:
+ * 1) TRANSFER_RECALLING: Recall target hangs up or time expires.
+ * atxferloopdelay is non-zero.
+ *
+ * State operation:
+ * The transferee is placed on hold.
+ *
+ * Transitions from TRANSFER_WAIT_TO_RETRANSFER:
+ * 1) TRANSFER_FAIL: Transferee hangs up.
+ * 2) TRANSFER_RETRANSFER: Time expires.
+ */
TRANSFER_WAIT_TO_RETRANSFER,
- /* Transferer did not answer re-call, re-call transfer target */
+ /*!
+ * \brief Retransfer state
+ *
+ * This state is used in order to attempt to call back the original
+ * transfer target channel from the transfer. The transferee hears
+ * ringing during this state as an auditory cue that a party is being
+ * dialed.
+ *
+ * Superstate: Recall
+ *
+ * Preconditions:
+ * 1) Recall target is down.
+ * 2) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_RETRANSFER:
+ * 1) TRANSFER_RECALLING: Recall target hangs up or time expires.
+ * atxferloopdelay is zero.
+ * 2) TRANSFER_WAIT_TO_RETRANSFER: Time expires.
+ *
+ * State operation:
+ * The original transfer target is requested and is set as the recall target.
+ * The recall target is called and placed into the transferee bridge.
+ *
+ * Transitions from TRANSFER_RETRANSFER:
+ * 1) TRANSFER_FAIL: Transferee hangs up.
+ * 2) TRANSFER_WAIT_TO_RECALL: Recall target hangs up or time expires.
+ * atxferloopdelay is non-zero.
+ * 3) TRANSFER_RECALLING: Recall target hangs up or time expires.
+ * atxferloopdelay is zero.
+ */
TRANSFER_RETRANSFER,
- /* Transfer target did not answer re-call, wait a bit */
+ /*!
+ * \brief Wait to recall state
+ *
+ * This state is used simply to give a bit of breathing room between attempting
+ * to call back the original transfer target and attempting to call back the
+ * original transferer. The transferee hears music on hold during this state as an
+ * auditory clue that no one is currently being dialed.
+ *
+ * Superstate: Recall
+ *
+ * Preconditions:
+ * 1) Recall target is down.
+ * 2) Transferee is off hold.
+ *
+ * Transitions to TRANSFER_WAIT_TO_RECALL:
+ * 1) TRANSFER_RETRANSFER: Recall target hangs up or time expires.
+ * atxferloopdelay is non-zero.
+ *
+ * State operation:
+ * Transferee is placed on hold.
+ *
+ * Transitions from TRANSFER_WAIT_TO_RECALL:
+ * 1) TRANSFER_FAIL: Transferee hangs up
+ * 2) TRANSFER_RECALLING: Time expires
+ */
TRANSFER_WAIT_TO_RECALL,
- /* The transfer did not succeed. All parties will disappear */
+ /*!
+ * \brief Fail state
+ *
+ * This state indicates that something occurred during the transfer that
+ * makes a graceful completion impossible. The most common stimulus for this
+ * state is when the transferee hangs up.
+ *
+ * Superstate: Transfer and Recall
+ *
+ * Preconditions:
+ * None
+ *
+ * Transitions to TRANSFER_FAIL:
+ * 1) TRANSFER_CALLING_TARGET: Transferee hangs up.
+ * 2) TRANSFER_HESITANT: Transferee hangs up.
+ * 3) TRANSFER_DOUBLECHECKING: Transferee hangs up.
+ * 4) TRANSFER_BLOND_NONFINAL: Transferee hangs up.
+ * 5) TRANSFER_RECALLING:
+ * a) Transferee hangs up.
+ * b) Recall target hangs up or time expires, and number of
+ * recall attempts exceeds atxfercallbackretries.
+ * 6) TRANSFER_WAIT_TO_RETRANSFER: Transferee hangs up.
+ * 7) TRANSFER_RETRANSFER: Transferee hangs up.
+ * 8) TRANSFER_WAIT_TO_RECALL: Transferee hangs up.
+ *
+ * State operation:
+ * A transfer stasis publication is made indicating a failed transfer.
+ * The transferee bridge is destroyed.
+ *
+ * Transitions from TRANSFER_FAIL:
+ * None.
+ */
TRANSFER_FAIL,
};
@@ -925,7 +1390,7 @@
static int blond_nonfinal_enter(struct attended_transfer_properties *props)
{
- props->superstate = STATE_RECALL;
+ props->superstate = SUPERSTATE_RECALL;
return blond_enter(props);
}
@@ -1354,7 +1819,7 @@
if (event == AST_FRAMEHOOK_EVENT_READ &&
frame && frame->frametype == AST_FRAME_CONTROL &&
frame->subclass.integer == AST_CONTROL_ANSWER) {
- if (props->superstate == STATE_TRANSFER) {
+ if (props->superstate == SUPERSTATE_TRANSFER) {
stimulate_attended_transfer(props, STIMULUS_TRANSFER_TARGET_ANSWER);
} else {
stimulate_attended_transfer(props, STIMULUS_RECALL_TARGET_ANSWER);
@@ -1531,10 +1996,10 @@
struct attended_transfer_properties *props = personality->pvt;
switch (props->superstate) {
- case STATE_TRANSFER:
+ case SUPERSTATE_TRANSFER:
transfer_pull(self, bridge_channel, props);
break;
- case STATE_RECALL:
+ case SUPERSTATE_RECALL:
recall_pull(self, bridge_channel, props);
break;
}
More information about the svn-commits
mailing list