From 0f937ca13415ee60fb636cdbb6e6e5121d4fcb63 Mon Sep 17 00:00:00 2001 From: Moises Silva Date: Thu, 16 Dec 2010 18:29:45 -0500 Subject: [PATCH] freetdm: Add documentation on sig status --- libs/freetdm/docs/sigstatus.txt | 59 ++++++++++++++++++++++++++++++ libs/freetdm/src/include/freetdm.h | 1 + 2 files changed, 60 insertions(+) create mode 100644 libs/freetdm/docs/sigstatus.txt diff --git a/libs/freetdm/docs/sigstatus.txt b/libs/freetdm/docs/sigstatus.txt new file mode 100644 index 0000000000..10561bfb5b --- /dev/null +++ b/libs/freetdm/docs/sigstatus.txt @@ -0,0 +1,59 @@ +FreeTDM can both notify and set signaling status changes in the different protocols thru a unified interface. More +specific details on the C data types and function prototypes are found in freetdm.h + +The API provides the following functions and data types to do it: + +The signaling status in any channel/span is represented thru ftdm_signaling_status_t + + /* The signaling link is down (no d-chans up in the span/group, MFC-R2 bit pattern unidentified) */ + FTDM_SIG_STATE_DOWN, + /* The signaling link is suspended (MFC-R2 bit pattern blocked, PRI maintenance, ss7 blocked?) */ + FTDM_SIG_STATE_SUSPENDED, + /* The signaling link is ready and calls can be placed (ie: d-chan up, MFC-R2 both rx and tx in IDLE) */ + FTDM_SIG_STATE_UP, + /* Invalid status */ + FTDM_SIG_STATE_INVALID + +Changes in the signaling status are notified to the user using the standard callback notification function provided +during configuration using the sigevent type FTDM_SIGEVENT_SIGSTATUS_CHANGED which is sent when the line status changes. + +On startup the signalling status default is FTDM_SIG_STATE_DOWN, and no notification is provided until the state change, +so applications must assume the status is down unless told otherwise. + +When ftdm_span_start is called, the signaling stack takes care of attempting to bring the status to UP +but it will ultimately depend on the other side too. + +== Setting the signaling status == + +Users can set the signaling status on a given channel/span thru FreeTDM the following API functions: + +ftdm_channel_set_sig_status +ftdm_span_set_sig_status + +If the user calls ftdm_channel_set_sig_status(chan, FTDM_SIG_STATE_SUSPENDED), the signaling stack will try to set +the status of the line to the one requested, if successful, it will result in a SIGEVENT_SIGSTATUS_CHANGED notification +being sent with status FTDM_SIG_STATE_SUSPENDED. + +** MFC-R2 Signaling Notes ** +For MFC-R2, calling ftdm_span_start() results in setting the tx CAS bits to IDLE. However, if the rx bits are in BLOCKED state +the signaling status will be reported as SUSPENDED. + +If the user calls ftdm_channel_set_sig_status(chan, SUSPENDED), the tx CAS bits will be set to BLOCKED and, if, the current rx bits +are IDLE then a SIGEVENT_SIGSTATUS_CHANGED with state SUSPENDED will be sent. If the rx bits are already in blocked then no further +SIGEVENT_SIGSTATUS_CHANGED notification is needed (because it was already sent when the rx bits were initially detected as BLOCKED). + +If the user calls ftdm_channel_set_sig_status(chan, UP), the tx CAS bits will be set to IDLE and, if, the current rx bits +are IDLE, then SIGEVENT_SIGSTATUS_CHANGED with state UP will be sent. If the rx bits are BLOCKED, then no notification is +sent at all until the rx bits change. + +Bottom line is, for MFC-R2, SIGEVENT_SIGSTATUS_CHANGED UP is only sent to the user when both the rx and tx bits are in IDLE, and +SIGEVENT_SIGSTATUS_CHANGED SUSPENDED is only sent to the user when any of the rx or tx bits are in BLOCKED. + +== Getting the signaling status == +Users can get the signaling status on a given channel/span thru FreeTDM the following API functions: + +ftdm_channel_get_sig_status +ftdm_span_get_sig_status + +The line status returned should be the same as the last time a SIGEVENT_SIGSTATUS_CHANGED was reported. + diff --git a/libs/freetdm/src/include/freetdm.h b/libs/freetdm/src/include/freetdm.h index 41bf819a1c..56a9dc0577 100644 --- a/libs/freetdm/src/include/freetdm.h +++ b/libs/freetdm/src/include/freetdm.h @@ -367,6 +367,7 @@ typedef struct ftdm_channel_config { /*! \brief Signaling status on a given span or specific channel on protocols that support it + \note see docs/sigstatus.txt for more extensive documentation on signaling status */ typedef enum { /* The signaling link is down (no d-chans up in the span/group, MFC-R2 bit pattern unidentified) */