Advanced Documents

1 Sangoma SDK Interfaces
2 Sangoma HW Operation Interface Functions
3 Sangoma FreeTDM Configuration Functions
4 Sangoma FreeTDM Signaling and Media I/O Interface Functions

Sangoma SDK Interfaces

Sangoma HW Operation Interface

Detect Sangoma Hardware
- Load kernel module
- Iterate over all hw ports
- call back user for each port
Configure Sangoma HW Port
- For each port save configuration to the driver
Start Sangoma HW Port
- Start driver/hw port.
Start Sangoma HW Port
- Stop driver/hw port.

Sangoma FreeTDM Operation Interface

Once sangoma hw ports are configured and started, the FreeTDM Framework can be started for each span.

Create FreeTDM Span
Start FreeTDM Span

Refer to the Sangoma FreeTDM Configuration Interface

Sangoma FreeTDM Signaling and Media Interface

Once FreeTDM Spans are started user application will wait for events.

On call start event, do something useful
- Eg: Launch a thread and start recording the media to file from a bchannel

Refer to Sangoma FreeTDM Signaling and Media Interface

Sangoma HW Operation Interface Functions

The Sangoma SDK HW operation interface is located in:

applications/common/libsangoma_wp_config.h

HW Operation Interface Data Structures

/*!
\typedef sangoma_port_obj_t
\brief Sangoma port object structure

Sangoma port object structure contains all hw port information
It also contains all hw configuration structures needed to
operate the port. Start,Stop,Save Config etc..

The object is provided to user opaque in order to simplify development.
Methods are provided to access and manipulate the port object.
*/
typedef void *sangoma_port_obj_t;

/*!
\typedef sangoma_hw_config_reg_t
\brief Sangoma operations callback structure

The callback structure allows user application to pass on
use specific information to the sangoma library.

user_obj - is a user pointer that will be passed back to the user application
on each callback.

hw_probe_callback() - is functin that will be called for each port detected
                        during hwprobe.
*/
typedef struct sangoma_hw_config_reg
{
    sangoma_port_obj_t user_obj;
    int (*hwprobe_callback)(void* sangoma_port_obj, int port_id, void *user_obj);
}sangoma_hw_config_reg_t;

Hardware Detection Function

/*!
\fn int sangoma_config_reg (sangoma_hw_config_reg_t *reg)
\brief Register hw callback functions into libsangoma
\param reg callback registration structure
\return File Descriptor: -1 error, 0 success

A very first access to the sangoma operations library.
User application registers hw callback functions.
These functions will be called on every hw port detect.
*/
int _LIBSNG_CALL sangoma_config_reg (sangoma_hw_config_reg_t *reg);

/*!
\fn int sangoma_config_hwprobe(int *detected, int *configured, int operating_mode)
\brief Detect sangoma hardware on a machine
\param detected detected will contain the number of ports detected on machine
\param configured configured will contain the number of ports that were successfully configured via the callback function
\param operating_mode will contain the mode on which SDK application is operating
\return File Descriptor: Non Zero is error, 0 is success

Detect sangoma hardware on a machine
For each port a hw callback function will be called into the user application.
The callback function will be give the sangoma _port_obj_t
     The port obj structure will contain all hw information about the port
     It will also contain fully initialized default configuration for the port based on port type.
     Meaning that user only needs to configure basic set of parameters before starting the port.
     Usually default configuration is enough to start the port successfully.

In callback function user application should:
     Save the port object pointer in users data structure for later use.
     Configure the port obj via sangoma_config_port_cfg_set_option method for each configuration option depending up on the operating_mode.
     Start sangoma hw port via sangoma_config_port_start
     Create freetdm span
     Start freetdm span
*/
int _LIBSNG_CALL sangoma_config_hwprobe(int *detected, int *configured, int operating_mode)

Sangoma Port Object Config and Misc Methods

/*!
\fn int sangoma_config_port_cfg_set_option(sangoma_port_obj_t sangoma_port_obj, char *key, char *value)
\brief Set hw port configuration option via key value pair
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\param key configuration option
\param value configuration option value
\return File Descriptor: -1 error, 0 success

This is a method that operates on sangoma_port_obj.
Set a configuration option via key value ascii pair.
Can be run multiple time on same object to configure each configuration option.

*/
int _LIBSNG_CALL sangoma_config_port_cfg_set_option(sangoma_port_obj_t sangoma_port_obj, char *key, char *value);

/*!
\fn int sangoma_config_port_cfg_get_option(sangoma_port_obj_t sangoma_port_obj, char *key, char *value)
\brief Get hw port configuration option via key value pair
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\param key configuration option
\param value port object current value of for the key
\return File Descriptor: -1 error, 0 success

This is a method that operates on sangoma_port_obj.
Get a configuration option value that is currently configured from port obj.
Can be run multiple time on same object to retrieve configuratin options.
*/
int _LIBSNG_CALL sangoma_config_port_cfg_get_option(sangoma_port_obj_t sangoma_port_obj, char *key, char *value);

/*!
\fn int sangoma_set_default_isup_pure_voice_span_config(sangoma_port_obj_t sangoma_port_obj)
\brief Configure the device driver/hw port for pure voice channels.
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\return File Descriptor: Non Zero is error, 0 is success

This is a method that operates on sangoma_port_obj.
Configure the device driver/hw port for pure voice channels.
The saved configuration will be applied to the port.
At this point the port will try to connect to the line.
*/
int _LIBSNG_CALL sangoma_set_default_isup_pure_voice_span_config(sangoma_port_obj_t sangoma_port_obj);

char* sangoma_config_port_hwinfo_get_model_str(sangoma_port_obj_t sangoma_port_obj);
unsigned int sangoma_config_port_hwinfo_get_model_id(sangoma_port_obj_t sangoma_port_obj);
unsigned int sangoma_config_port_hwinfo_get_pcislot(sangoma_port_obj_t sangoma_port_obj);
unsigned int sangoma_config_port_hwinfo_get_pcibus(sangoma_port_obj_t sangoma_port_obj);
unsigned int sangoma_config_port_hwinfo_get_fimrware_version(sangoma_port_obj_t sangoma_port_obj);
unsigned int sangoma_config_port_get_port_id(sangoma_port_obj_t sangoma_port_obj);

Sangoma HW Port Operation Methods

/*!
\fn int sangoma_config_port_save(sangoma_port_obj_t sangoma_port_obj)
\brief Save current configuration in port obj to driver. Driver restart is needed to apply
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\return File Descriptor: Non Zero is error, 0 is success

This is a method that operates on sangoma_port_obj.
Save current configuration in port obj to driver. Driver restart is needed to apply.
*/
int _LIBSNG_CALL sangoma_config_port_save(sangoma_port_obj_t sangoma_port_obj);

/*!
\fn int sangoma_config_port_start(sangoma_port_obj_t sangoma_port_obj)
\brief Start the device driver/hw port
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\return File Descriptor: Non Zero is error, 0 is success

This is a method that operates on sangoma_port_obj.
Start the device driver/hw port.
The saved configuration will be applied to the port.
At this point the port will try to connect to the line.
LED on boards will become active.
All interrupts are enabled.
*/
int _LIBSNG_CALL sangoma_config_port_start(sangoma_port_obj_t sangoma_port_obj);

/*!
\fn int sangoma_config_port_stop(sangoma_port_obj_t sangoma_port_obj)
\brief Stop the device driver/hw port
\param sangoma_port_obj sangoma hw port object, contains all hw and cfg information
\return File Descriptor: Non Zero is error, 0 is success

This is a method that operates on sangoma_port_obj.
Stop the device driver/hw port.
Driver will unconfigure the hwport. Interrutps are disabled.
*/
int _LIBSNG_CALL sangoma_config_port_stop(sangoma_port_obj_t sangoma_port_obj);

Sangoma FreeTDM Configuration Functions

The Sangoma FreeTDM Operation Interface is located in:

applications/common/libsangoma_freetdm.h

/*!
\fn int sangoma_freetdm_init(sangoma_freetdm_init_t *ftdm_init)
\brief Initialize FreeTDM Framework. Must run before any function.
\param ftdm_init FreeTDM initi config structure
\return File Descriptor: Non Zero is error, 0 is success

Main FreeTDM initializatino function.
Must be the first functino to be called before any other FreeTDM call.

*/
int sangoma_freetdm_init(sangoma_freetdm_init_t *ftdm_init);

 
/*!
  \fn int sangoma_freetdm_destroy(void);
  \brief Stop the FreeTDM Framework. All Spans will be deallocated.
  \param void
  \return File Descriptor: Non Zero is error, 0  is success

  Stop the FreeTDM Framework.
  All spans will be deallocated.
  Usually called before the application exits.
  Must be the first function to be called before any other FreeTDM call.

*/
int sangoma_freetdm_destroy(void);


/*!
  \fn int sangoma_freetdm_create_span(sangoma_port_obj_t port, ftdm_span_t **span, int operating_mode);
  \brief Create FreeTDM Span. User hw port object for span cfg info.
  \param port Sangoma hw prot obj.
  \param span Created span will be stored in this pointer. Span is an opaque object.
  \param operating_mode will contain the mode on which span needs to be operated like ANALOG/ISUP_SIG/ISUP_VOICE/ISDN/MTP2_API_LSL/MTP2_API_HSL
  \return File Descriptor: Non Zero is error, 0  is success

  Create FreeTDM Span in FreeTDM framework.
  The Sangoma port object will be used to extract hw configuration necessary
  to create the span.

  The FreeTDM span opaque object will be stored in the span argument.
  At this point span is only half configured.
  Next step is to call span configuration function.
*/
int sangoma_freetdm_create_span(sangoma_port_obj_t port, ftdm_span_t **span, int operating_mode);


/*!
  \fn int sangoma_freetdm_span_config_and_start(sangoma_port_obj_t port, ftdm_span_t *span, int operating_mode);
  \brief Configure FreeTDM span based on sangoma port object configuration options.
  \param port Sangoma hw prot obj.
  \param span FreeTDM span object
  \param operating_mode will contain the mode on which span needs to be configured and started like ANALOG/ISUP_SIG/ISUP_VOICE/ISDN/MTP2_API_LSL/MTP2_API_HSL
  \return File Descriptor: Non Zero is error, 0  is success

  This function will configure the FreeTDM span using information from sangoma port obj.
  Once the span is fully configured, the span will be started.

  Once the FreeTDM span starts it will
    Initialize and start signaling on port dchan
    Wait for dchan events.
    One signaling event (such as call start) FreeTDM pass the event structure
    to user application via callback function.

  At this point application is able to call FreeTDM Signaling and Media Functions.
*/
int sangoma_freetdm_span_config_and_start(sangoma_port_obj_t port, ftdm_span_t *span, int operating_mode);

Sangoma FreeTDM Signaling and Media I/O Interface Functions

The Sangoma FreeTDM Signaling and Media Interface is located in:

FreeTDM Place Call, Indicate Call, Answer Call

/*! \brief Place an outgoing call with the given caller data in a channel according to the hunting scheme provided and records

the place where it was called. See ftdm_call_place for an easy to use macro
\return FTDM_SUCCESS if the call attempt was successful
FTDM_FAIL if there was an unspecified error
FTDM_EBUSY if the channel was busy
FTDM_BREAK if glare was detected and you must try again
\note Even when FTDM_SUCCESS is returned, the call may still fail later on due to glare, in such case FTDM_SIGEVENT_STOP
will be sent with the hangup cause field set to FTDM_CAUSE_REQUESTED_CHAN_UNAVAIL

*

\note When this function returns FTDM_SUCCESS, the member .fchan from caller_data will be set to the channel used to place the call
and .call_id to the generated call id for that call

*

\note When this function is successful you are guaranteed to receive FTDM_SIGEVENT_DIALING, this event could even be delivered
before your execution thread returns from this function

*/

/*! \brief Place an outgoing call with the given caller data in a channel according to the hunting scheme provided */
#define ftdm_call_place(callerdata, hunting)
#define ftdm_call_place_ex(callerdata, hunting, usrmsg)

/*! \brief Indicate a new condition in an incoming call
*

\note Every indication request will result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered with
the proper status that will inform you if the request was successful or not. The exception is if this
function returns something different to FTDM_SUCCESS, in which case the request failed right away and no
further FTDM_SIGEVENT_INDICATION_COMPLETED will be delivered
Be aware there is no guarantee of whether the completion event will arrive after or before your execution
thread returns from ftdm_channel_call_indicate. This means you could get FTDM_SIGEVENT_INDICATION_COMPLETED
even before your execution thread returns from the ftdm_channel_call_indicate() API

*

\note You cannot send more than one indication at the time. You must wait for the completed event before
calling this function again (unless the return code was different than FTDM_SUCCESS)

*/
#define ftdm_channel_call_indicate(ftdmchan, indication)

/*! \brief Answer call. This can also be accomplished by ftdm_channel_call_indicate with FTDM_CHANNEL_INDICATE_ANSWER, in both

cases you will get a FTDM_SIGEVENT_INDICATION_COMPLETED when the indication is sent (or an error occurs).
Just as with ftdm_channel_call_indicate you won't receive FTDM_SIGEVENT_INDICATION_COMPLETED when this function
returns anything else than FTDM_SUCCESS
\note Although this API may result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered,
there is no guarantee of whether the event will arrive after or before your execution thread returns
from ftdm_channel_call_answer

*/
#define ftdm_channel_call_answer(ftdmchan)

FreeTDM Hangup Call

Hangup Cause Codes

Note that some of the hangup codes only apply to FreeTDM framework internals,
not the use application

/*! \brief Hangup cause codes */
typedef enum {
    FTDM_CAUSE_NONE = 0,
    FTDM_CAUSE_UNALLOCATED = 1,
    FTDM_CAUSE_NO_ROUTE_TRANSIT_NET = 2,
    FTDM_CAUSE_NO_ROUTE_DESTINATION = 3,
    FTDM_CAUSE_SEND_SPECIAL_INFO_TONE = 4,
    FTDM_CAUSE_MISDIALED_TRUNK_PREFIX = 5,
    FTDM_CAUSE_CHANNEL_UNACCEPTABLE = 6,
    FTDM_CAUSE_CALL_AWARDED_DELIVERED = 7,
    FTDM_CAUSE_PREEMPTION = 8,
    FTDM_CAUSE_PREEMPTION_CIRCUIT_RESERVED = 9,
    FTDM_CAUSE_NORMAL_CLEARING = 16,
    FTDM_CAUSE_USER_BUSY = 17,
    FTDM_CAUSE_NO_USER_RESPONSE = 18,
    FTDM_CAUSE_NO_ANSWER = 19,
    FTDM_CAUSE_SUBSCRIBER_ABSENT = 20,
    FTDM_CAUSE_CALL_REJECTED = 21,
    FTDM_CAUSE_NUMBER_CHANGED = 22,
    FTDM_CAUSE_REDIRECTION_TO_NEW_DESTINATION = 23,
    FTDM_CAUSE_EXCHANGE_ROUTING_ERROR = 25,
    FTDM_CAUSE_DESTINATION_OUT_OF_ORDER = 27,
    FTDM_CAUSE_INVALID_NUMBER_FORMAT = 28,
    FTDM_CAUSE_FACILITY_REJECTED = 29,
    FTDM_CAUSE_RESPONSE_TO_STATUS_ENQUIRY = 30,
    FTDM_CAUSE_NORMAL_UNSPECIFIED = 31,
    FTDM_CAUSE_NORMAL_CIRCUIT_CONGESTION = 34,
    FTDM_CAUSE_NETWORK_OUT_OF_ORDER = 38,
    FTDM_CAUSE_PERMANENT_FRAME_MODE_CONNECTION_OOS = 39,
    FTDM_CAUSE_PERMANENT_FRAME_MODE_OPERATIONAL = 40,
    FTDM_CAUSE_NORMAL_TEMPORARY_FAILURE = 41,
    FTDM_CAUSE_SWITCH_CONGESTION = 42,
    FTDM_CAUSE_ACCESS_INFO_DISCARDED = 43,
    FTDM_CAUSE_REQUESTED_CHAN_UNAVAIL = 44,
    FTDM_CAUSE_PRE_EMPTED = 45,
    FTDM_CAUSE_PRECEDENCE_CALL_BLOCKED = 46,
    FTDM_CAUSE_RESOURCE_UNAVAILABLE_UNSPECIFIED = 47,
    FTDM_CAUSE_QOS_NOT_AVAILABLE = 49,
    FTDM_CAUSE_FACILITY_NOT_SUBSCRIBED = 50,
    FTDM_CAUSE_OUTGOING_CALL_BARRED = 53,
    FTDM_CAUSE_INCOMING_CALL_BARRED = 55,
    FTDM_CAUSE_BEARERCAPABILITY_NOTAUTH = 57,
    FTDM_CAUSE_BEARERCAPABILITY_NOTAVAIL = 58,
    FTDM_CAUSE_INCONSISTENCY_IN_INFO = 62,
    FTDM_CAUSE_SERVICE_UNAVAILABLE = 63,
    FTDM_CAUSE_BEARERCAPABILITY_NOTIMPL = 65,
    FTDM_CAUSE_CHAN_NOT_IMPLEMENTED = 66,
    FTDM_CAUSE_FACILITY_NOT_IMPLEMENTED = 69,
    FTDM_CAUSE_ONLY_DIGITAL_INFO_BC_AVAIL = 70,
    FTDM_CAUSE_SERVICE_NOT_IMPLEMENTED = 79,
    FTDM_CAUSE_INVALID_CALL_REFERENCE = 81,
    FTDM_CAUSE_IDENTIFIED_CHAN_NOT_EXIST = 82,
    FTDM_CAUSE_SUSPENDED_CALL_EXISTS_BUT_CALL_ID_DOES_NOT = 83,
    FTDM_CAUSE_CALL_ID_IN_USE = 84,
    FTDM_CAUSE_NO_CALL_SUSPENDED = 85,
    FTDM_CAUSE_CALL_WITH_CALL_ID_CLEARED = 86,
    FTDM_CAUSE_USER_NOT_CUG = 87,
    FTDM_CAUSE_INCOMPATIBLE_DESTINATION = 88,
    FTDM_CAUSE_NON_EXISTENT_CUG = 90,
    FTDM_CAUSE_INVALID_TRANSIT_NETWORK_SELECTION = 91,
    FTDM_CAUSE_INVALID_MSG_UNSPECIFIED = 95,
    FTDM_CAUSE_MANDATORY_IE_MISSING = 96,
    FTDM_CAUSE_MESSAGE_TYPE_NONEXIST = 97,
    FTDM_CAUSE_WRONG_MESSAGE = 98,
    FTDM_CAUSE_IE_NONEXIST = 99,
    FTDM_CAUSE_INVALID_IE_CONTENTS = 100,
    FTDM_CAUSE_WRONG_CALL_STATE = 101,
    FTDM_CAUSE_RECOVERY_ON_TIMER_EXPIRE = 102,
    FTDM_CAUSE_MANDATORY_IE_LENGTH_ERROR = 103,
    FTDM_CAUSE_MSG_WITH_UNRECOGNIZED_PARAM_DISCARDED = 110,
    FTDM_CAUSE_PROTOCOL_ERROR = 111,
    FTDM_CAUSE_INTERWORKING = 127,
    FTDM_CAUSE_SUCCESS = 142,
    FTDM_CAUSE_ORIGINATOR_CANCEL = 487,
    FTDM_CAUSE_CRASH = 500,
    FTDM_CAUSE_SYSTEM_SHUTDOWN = 501,
    FTDM_CAUSE_LOSE_RACE = 502,
    FTDM_CAUSE_MANAGER_REQUEST = 503,
    FTDM_CAUSE_BLIND_TRANSFER = 600,
    FTDM_CAUSE_ATTENDED_TRANSFER = 601,
    FTDM_CAUSE_ALLOTTED_TIMEOUT = 602,
    FTDM_CAUSE_USER_CHALLENGE = 603,
    FTDM_CAUSE_MEDIA_TIMEOUT = 604
} ftdm_call_cause_t

FreeTDM Call Support Functions

FreeTDM Channel Support Functions

/*!

\brief Get the channel type

*

\param ftdmchan The channel to get the type from

*

\retval channel type (FXO, FXS, B-channel, D-channel, etc)

*/
FT_DECLARE(ftdm_chan_type_t) ftdm_channel_get_type(const ftdm_channel_t *ftdmchan);

/*!

\brief Set user private data in the channel

*

\param ftdmchan The channel where the private data will be stored
\param pvt The private pointer to store

*
*/
FT_DECLARE(void) ftdm_channel_set_private(ftdm_channel_t *ftdmchan, void *pvt);

/*!

\brief Get user private data in the channel

*

\param ftdmchan The channel to retrieve the private data
\retval The private data (if any or NULL if no data has been stored)

*
*/
FT_DECLARE(void *) ftdm_channel_get_private(const ftdm_channel_t *ftdmchan);

/*!

\brief Remove the given token from the channel

*

\param ftdmchan The channel where the token is
\param token The token string. If NULL, all tokens in the channel are cleared

*

\retval FTDM_SUCCESS success
\retval FTDM_FAIL failure

*/
FT_DECLARE(ftdm_status_t) ftdm_channel_clear_token(ftdm_channel_t *ftdmchan, const char *token);

/*!

\brief Replace the given token with the new token

*

\param ftdmchan The channel where the token is
\param old_token The token to replace
\param new_token The token to put in place

*/
FT_DECLARE(void) ftdm_channel_replace_token(ftdm_channel_t *ftdmchan, const char *old_token, const char *new_token);

/*!

\brief Add a new token to the channel

*

\param ftdmchan The channel where the token will be added
\param token The token string to add
\param end if 0, the token will be added at the beginning of the token list, to the end otherwise

*

\retval FTDM_SUCCESS success
\retval FTDM_FAIL failure

*/
FT_DECLARE(ftdm_status_t) ftdm_channel_add_token(ftdm_channel_t *ftdmchan, char *token, int end);

/*!

\brief Get the requested token

*

\param ftdmchan The channel where the token is
\param tokenid The id of the token

*

\retval The token character string
\retval NULL token not found

*/
FT_DECLARE(const char *) ftdm_channel_get_token(const ftdm_channel_t *ftdmchan, uint32_t tokenid);

/*!

\brief Get the token count

*

\param ftdmchan The channel to get the token count from

*

\retval The token count

*/
FT_DECLARE(uint32_t) ftdm_channel_get_token_count(const ftdm_channel_t *ftdmchan);

Telephony Cards