1 /* 2 * Copyright (c) 2007-2014, Anthony Minessale II 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of the original author; nor the names of any contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 25 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 26 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 27 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 28 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 29 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 30 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 31 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 * 33 * Contributors: 34 * 35 * Moises Silva <moy@sangoma.com> 36 * David Yat Sin <dyatsin@sangoma.com> 37 * 38 */ 39 40 #ifndef FREETDM_H 41 #define FREETDM_H 42 43 #include "ftdm_declare.h" 44 #include "ftdm_call_utils.h" 45 46 /*! \brief Max number of channels per physical span */ 47 #define FTDM_MAX_CHANNELS_PHYSICAL_SPAN 32 48 49 /*! \brief Max number of physical spans per logical span */ 50 #define FTDM_MAX_PHYSICAL_SPANS_PER_LOGICAL_SPAN 128 51 52 /*! \brief Max number of channels a logical span can contain */ 53 #define FTDM_MAX_CHANNELS_SPAN FTDM_MAX_CHANNELS_PHYSICAL_SPAN * FTDM_MAX_PHYSICAL_SPANS_PER_LOGICAL_SPAN 54 55 /*! \brief Max number of logical spans */ 56 #define FTDM_MAX_SPANS_INTERFACE 128 57 58 /*! \brief Max number of channels per hunting group */ 59 #define FTDM_MAX_CHANNELS_GROUP 2048 60 61 /*! \brief Max number of groups */ 62 #define FTDM_MAX_GROUPS_INTERFACE FTDM_MAX_SPANS_INTERFACE 63 64 /*! \brief Max number of key=value pairs to be sent as signaling stack parameters */ 65 #define FTDM_MAX_SIG_PARAMETERS 30 66 67 #define FTDM_INVALID_INT_PARM 0xFF 68 69 /*! \brief Thread/Mutex OS abstraction API. */ 70 #include "ftdm_os.h" 71 72 #ifdef __cplusplus 73 extern "C" { 74 #endif 75 76 /*! \brief Limit to span names */ 77 #define FTDM_MAX_NAME_STR_SZ 128 78 79 /*! \brief Limit to channel number strings */ 80 #define FTDM_MAX_NUMBER_STR_SZ 32 81 82 /*! \brief Hangup cause codes */ 83 typedef enum { 84 FTDM_CAUSE_NONE = 0, 85 FTDM_CAUSE_UNALLOCATED = 1, 86 FTDM_CAUSE_NO_ROUTE_TRANSIT_NET = 2, 87 FTDM_CAUSE_NO_ROUTE_DESTINATION = 3, 88 FTDM_CAUSE_SEND_SPECIAL_INFO_TONE = 4, 89 FTDM_CAUSE_MISDIALED_TRUNK_PREFIX = 5, 90 FTDM_CAUSE_CHANNEL_UNACCEPTABLE = 6, 91 FTDM_CAUSE_CALL_AWARDED_DELIVERED = 7, 92 FTDM_CAUSE_PREEMPTION = 8, 93 FTDM_CAUSE_PREEMPTION_CIRCUIT_RESERVED = 9, 94 FTDM_CAUSE_NORMAL_CLEARING = 16, 95 FTDM_CAUSE_USER_BUSY = 17, 96 FTDM_CAUSE_NO_USER_RESPONSE = 18, 97 FTDM_CAUSE_NO_ANSWER = 19, 98 FTDM_CAUSE_SUBSCRIBER_ABSENT = 20, 99 FTDM_CAUSE_CALL_REJECTED = 21, 100 FTDM_CAUSE_NUMBER_CHANGED = 22, 101 FTDM_CAUSE_REDIRECTION_TO_NEW_DESTINATION = 23, 102 FTDM_CAUSE_EXCHANGE_ROUTING_ERROR = 25, 103 FTDM_CAUSE_DESTINATION_OUT_OF_ORDER = 27, 104 FTDM_CAUSE_INVALID_NUMBER_FORMAT = 28, 105 FTDM_CAUSE_FACILITY_REJECTED = 29, 106 FTDM_CAUSE_RESPONSE_TO_STATUS_ENQUIRY = 30, 107 FTDM_CAUSE_NORMAL_UNSPECIFIED = 31, 108 FTDM_CAUSE_NORMAL_CIRCUIT_CONGESTION = 34, 109 FTDM_CAUSE_NETWORK_OUT_OF_ORDER = 38, 110 FTDM_CAUSE_PERMANENT_FRAME_MODE_CONNECTION_OOS = 39, 111 FTDM_CAUSE_PERMANENT_FRAME_MODE_OPERATIONAL = 40, 112 FTDM_CAUSE_NORMAL_TEMPORARY_FAILURE = 41, 113 FTDM_CAUSE_SWITCH_CONGESTION = 42, 114 FTDM_CAUSE_ACCESS_INFO_DISCARDED = 43, 115 FTDM_CAUSE_REQUESTED_CHAN_UNAVAIL = 44, 116 FTDM_CAUSE_PRE_EMPTED = 45, 117 FTDM_CAUSE_PRECEDENCE_CALL_BLOCKED = 46, 118 FTDM_CAUSE_RESOURCE_UNAVAILABLE_UNSPECIFIED = 47, 119 FTDM_CAUSE_QOS_NOT_AVAILABLE = 49, 120 FTDM_CAUSE_FACILITY_NOT_SUBSCRIBED = 50, 121 FTDM_CAUSE_OUTGOING_CALL_BARRED = 53, 122 FTDM_CAUSE_INCOMING_CALL_BARRED = 55, 123 FTDM_CAUSE_BEARERCAPABILITY_NOTAUTH = 57, 124 FTDM_CAUSE_BEARERCAPABILITY_NOTAVAIL = 58, 125 FTDM_CAUSE_INCONSISTENCY_IN_INFO = 62, 126 FTDM_CAUSE_SERVICE_UNAVAILABLE = 63, 127 FTDM_CAUSE_BEARERCAPABILITY_NOTIMPL = 65, 128 FTDM_CAUSE_CHAN_NOT_IMPLEMENTED = 66, 129 FTDM_CAUSE_FACILITY_NOT_IMPLEMENTED = 69, 130 FTDM_CAUSE_ONLY_DIGITAL_INFO_BC_AVAIL = 70, 131 FTDM_CAUSE_SERVICE_NOT_IMPLEMENTED = 79, 132 FTDM_CAUSE_INVALID_CALL_REFERENCE = 81, 133 FTDM_CAUSE_IDENTIFIED_CHAN_NOT_EXIST = 82, 134 FTDM_CAUSE_SUSPENDED_CALL_EXISTS_BUT_CALL_ID_DOES_NOT = 83, 135 FTDM_CAUSE_CALL_ID_IN_USE = 84, 136 FTDM_CAUSE_NO_CALL_SUSPENDED = 85, 137 FTDM_CAUSE_CALL_WITH_CALL_ID_CLEARED = 86, 138 FTDM_CAUSE_USER_NOT_CUG = 87, 139 FTDM_CAUSE_INCOMPATIBLE_DESTINATION = 88, 140 FTDM_CAUSE_NON_EXISTENT_CUG = 90, 141 FTDM_CAUSE_INVALID_TRANSIT_NETWORK_SELECTION = 91, 142 FTDM_CAUSE_INVALID_MSG_UNSPECIFIED = 95, 143 FTDM_CAUSE_MANDATORY_IE_MISSING = 96, 144 FTDM_CAUSE_MESSAGE_TYPE_NONEXIST = 97, 145 FTDM_CAUSE_WRONG_MESSAGE = 98, 146 FTDM_CAUSE_IE_NONEXIST = 99, 147 FTDM_CAUSE_INVALID_IE_CONTENTS = 100, 148 FTDM_CAUSE_WRONG_CALL_STATE = 101, 149 FTDM_CAUSE_RECOVERY_ON_TIMER_EXPIRE = 102, 150 FTDM_CAUSE_MANDATORY_IE_LENGTH_ERROR = 103, 151 FTDM_CAUSE_MSG_WITH_UNRECOGNIZED_PARAM_DISCARDED = 110, 152 FTDM_CAUSE_PROTOCOL_ERROR = 111, 153 FTDM_CAUSE_INTERWORKING = 127, 154 FTDM_CAUSE_SUCCESS = 142, 155 FTDM_CAUSE_ORIGINATOR_CANCEL = 487, 156 FTDM_CAUSE_CRASH = 500, 157 FTDM_CAUSE_SYSTEM_SHUTDOWN = 501, 158 FTDM_CAUSE_LOSE_RACE = 502, 159 FTDM_CAUSE_MANAGER_REQUEST = 503, 160 FTDM_CAUSE_BLIND_TRANSFER = 600, 161 FTDM_CAUSE_ATTENDED_TRANSFER = 601, 162 FTDM_CAUSE_ALLOTTED_TIMEOUT = 602, 163 FTDM_CAUSE_USER_CHALLENGE = 603, 164 FTDM_CAUSE_MEDIA_TIMEOUT = 604 165 } ftdm_call_cause_t; 166 167 /*! \brief Hunting direction (when hunting for free channels) */ 168 typedef enum { 169 FTDM_HUNT_TOP_DOWN, 170 FTDM_HUNT_BOTTOM_UP, 171 FTDM_HUNT_RR_DOWN, 172 FTDM_HUNT_RR_UP, 173 } ftdm_hunt_direction_t; 174 175 /*! \brief Legacy Hunting direction (Top down and Bottom up were reversed), keep for source backwards compatibility of freetdm user applications 176 * \deprecated 177 * \see ftdm_hunt_direction_t 178 */ 179 typedef enum { 180 FTDM_BOTTOM_UP, 181 FTDM_TOP_DOWN, 182 FTDM_RR_UP, 183 FTDM_RR_DOWN, 184 } ftdm_direction_t; 185 186 /*! \brief I/O channel type */ 187 typedef enum { 188 FTDM_CHAN_TYPE_B, /*!< Bearer channel */ 189 FTDM_CHAN_TYPE_DQ921, /*!< DQ921 channel (D-channel) */ 190 FTDM_CHAN_TYPE_DQ931, /*!< DQ931 channel */ 191 FTDM_CHAN_TYPE_FXS, /*!< FXS analog channel */ 192 FTDM_CHAN_TYPE_FXO, /*!< FXO analog channel */ 193 FTDM_CHAN_TYPE_EM, /*!< E & M channel */ 194 FTDM_CHAN_TYPE_CAS, /*!< CAS channel */ 195 FTDM_CHAN_TYPE_COUNT /*!< Count of channel types */ 196 } ftdm_chan_type_t; 197 #define CHAN_TYPE_STRINGS "B", "DQ921", "DQ931", "FXS", "FXO", "EM", "CAS", "INVALID" 198 /*! \brief transform from channel type to string and from string to channel type 199 * ftdm_str2ftdm_chan_type transforms a channel string (ie: "FXO" to FTDM_CHAN_TYPE_FXO) 200 * ftdm_chan_type2str transforms a channel type to string (ie: FTDM_CHAN_TYPE_B to "B") 201 */ 202 FTDM_STR2ENUM_P(ftdm_str2ftdm_chan_type, ftdm_chan_type2str, ftdm_chan_type_t) 203 204 /*! \brief Test if a channel is a voice channel */ 205 #define FTDM_IS_VOICE_CHANNEL(fchan) ((fchan)->type != FTDM_CHAN_TYPE_DQ921 && (fchan)->type != FTDM_CHAN_TYPE_DQ931) 206 207 /*! \brief Test if a channel is a D-channel */ 208 #define FTDM_IS_DCHAN(fchan) ((fchan)->type == FTDM_CHAN_TYPE_DQ921 || (fchan)->type == FTDM_CHAN_TYPE_DQ931) 209 210 /*! \brief Test if a channel is digital channel */ 211 #define FTDM_IS_DIGITAL_CHANNEL(fchan) ((fchan)->span->trunk_type == FTDM_TRUNK_E1 || \ 212 (fchan)->span->trunk_type == FTDM_TRUNK_T1 || \ 213 (fchan)->span->trunk_type == FTDM_TRUNK_J1 || \ 214 (fchan)->span->trunk_type == FTDM_TRUNK_BRI || \ 215 (fchan)->span->trunk_type == FTDM_TRUNK_BRI_PTMP) 216 217 /*! \brief Test if a span is digital */ 218 #define FTDM_SPAN_IS_DIGITAL(span) \ 219 ((span)->trunk_type == FTDM_TRUNK_E1 || \ 220 (span)->trunk_type == FTDM_TRUNK_T1 || \ 221 (span)->trunk_type == FTDM_TRUNK_J1 || \ 222 (span)->trunk_type == FTDM_TRUNK_GSM || \ 223 (span)->trunk_type == FTDM_TRUNK_BRI || \ 224 (span)->trunk_type == FTDM_TRUNK_BRI_PTMP) 225 226 227 /*! \brief Logging function prototype to be used for all FreeTDM logs 228 * you should use ftdm_global_set_logger to set your own logger 229 */ 230 typedef void (*ftdm_logger_t)(const char *file, const char *func, int line, int level, const char *fmt, ...) __ftdm_check_printf(5, 6); 231 232 /*! \brief Data queue operation functions 233 * you can use ftdm_global_set_queue_handler if you want to override the default implementation (not recommended) 234 */ 235 typedef ftdm_status_t (*ftdm_queue_create_func_t)(ftdm_queue_t **queue, ftdm_size_t capacity); 236 typedef ftdm_status_t (*ftdm_queue_enqueue_func_t)(ftdm_queue_t *queue, void *obj); 237 typedef void *(*ftdm_queue_dequeue_func_t)(ftdm_queue_t *queue); 238 typedef ftdm_status_t (*ftdm_queue_wait_func_t)(ftdm_queue_t *queue, int ms); 239 typedef ftdm_status_t (*ftdm_queue_get_interrupt_func_t)(ftdm_queue_t *queue, ftdm_interrupt_t **interrupt); 240 typedef ftdm_status_t (*ftdm_queue_destroy_func_t)(ftdm_queue_t **queue); 241 242 typedef struct ftdm_queue_handler { 243 ftdm_queue_create_func_t create; 244 ftdm_queue_enqueue_func_t enqueue; 245 ftdm_queue_dequeue_func_t dequeue; 246 ftdm_queue_wait_func_t wait; 247 ftdm_queue_get_interrupt_func_t get_interrupt; 248 ftdm_queue_destroy_func_t destroy; 249 } ftdm_queue_handler_t; 250 251 /*! \brief Type Of Number (TON) */ 252 typedef enum { 253 FTDM_TON_UNKNOWN = 0, 254 FTDM_TON_INTERNATIONAL, 255 FTDM_TON_NATIONAL, 256 FTDM_TON_NETWORK_SPECIFIC, 257 FTDM_TON_SUBSCRIBER_NUMBER, 258 FTDM_TON_ABBREVIATED_NUMBER, 259 FTDM_TON_RESERVED, 260 FTDM_TON_INVALID 261 } ftdm_ton_t; 262 #define TON_STRINGS "unknown", "international", "national", "network-specific", "subscriber-number", "abbreviated-number", "reserved", "invalid" 263 FTDM_STR2ENUM_P(ftdm_str2ftdm_ton, ftdm_ton2str, ftdm_ton_t) 264 265 /*! Numbering Plan Identification (NPI) */ 266 typedef enum { 267 FTDM_NPI_UNKNOWN = 0, 268 FTDM_NPI_ISDN, 269 FTDM_NPI_DATA, 270 FTDM_NPI_TELEX, 271 FTDM_NPI_NATIONAL, 272 FTDM_NPI_PRIVATE, 273 FTDM_NPI_RESERVED, 274 FTDM_NPI_INVALID 275 } ftdm_npi_t; 276 #define NPI_STRINGS "unknown", "ISDN", "data", "telex", "national", "private", "reserved", "invalid" 277 FTDM_STR2ENUM_P(ftdm_str2ftdm_npi, ftdm_npi2str, ftdm_npi_t) 278 279 /*! Presentation Ind */ 280 typedef enum { 281 FTDM_PRES_ALLOWED, 282 FTDM_PRES_RESTRICTED, 283 FTDM_PRES_NOT_AVAILABLE, 284 FTDM_PRES_RESERVED, 285 FTDM_PRES_INVALID 286 } ftdm_presentation_t; 287 #define PRESENTATION_STRINGS "presentation-allowed", "presentation-restricted", "number-not-available", "reserved", "Invalid" 288 FTDM_STR2ENUM_P(ftdm_str2ftdm_presentation, ftdm_presentation2str, ftdm_presentation_t) 289 290 /*! Screening Ind */ 291 typedef enum { 292 FTDM_SCREENING_NOT_SCREENED, 293 FTDM_SCREENING_VERIFIED_PASSED, 294 FTDM_SCREENING_VERIFIED_FAILED, 295 FTDM_SCREENING_NETWORK_PROVIDED, 296 FTDM_SCREENING_INVALID 297 } ftdm_screening_t; 298 #define SCREENING_STRINGS "user-provided-not-screened", "user-provided-verified-and-passed", "user-provided-verified-and-failed", "network-provided", "invalid" 299 FTDM_STR2ENUM_P(ftdm_str2ftdm_screening, ftdm_screening2str, ftdm_screening_t) 300 301 /*! \brief bearer capability */ 302 typedef enum { 303 FTDM_BEARER_CAP_SPEECH = 0x00, /* Speech */ 304 FTDM_BEARER_CAP_UNRESTRICTED, /* Unrestricted Digital */ 305 FTDM_BEARER_CAP_RESTRICTED, /* Restricted Digital */ 306 FTDM_BEARER_CAP_3_1KHZ_AUDIO, /* 3.1 Khz Audio */ 307 FTDM_BEARER_CAP_7KHZ_AUDIO, /* 7 Khz Audio or Unrestricted digital w tones */ 308 FTDM_BEARER_CAP_15KHZ_AUDIO, /* 15 Khz Audio */ 309 FTDM_BEARER_CAP_VIDEO, /* Video */ 310 FTDM_BEARER_CAP_INVALID 311 } ftdm_bearer_cap_t; 312 #define BEARER_CAP_STRINGS "speech", "unrestricted-digital-information", "restricted-digital-information", "3.1-Khz-audio", "7-Khz-audio", "15-Khz-audio", "video", "invalid" 313 FTDM_STR2ENUM_P(ftdm_str2ftdm_bearer_cap, ftdm_bearer_cap2str, ftdm_bearer_cap_t) 314 315 /*! \brief user information layer 1 protocol */ 316 typedef enum { 317 FTDM_USER_LAYER1_PROT_V110 = 0x01, 318 FTDM_USER_LAYER1_PROT_ULAW = 0x02, 319 FTDM_USER_LAYER1_PROT_ALAW = 0x03, 320 FTDM_USER_LAYER1_PROT_INVALID 321 } ftdm_user_layer1_prot_t; 322 #define USER_LAYER1_PROT_STRINGS "V.110", "ulaw", "alaw", "Invalid" 323 FTDM_STR2ENUM_P(ftdm_str2ftdm_usr_layer1_prot, ftdm_user_layer1_prot2str, ftdm_user_layer1_prot_t) 324 325 /*! Calling Party Category */ 326 typedef enum { 327 FTDM_CPC_UNKNOWN, 328 FTDM_CPC_OPERATOR, 329 FTDM_CPC_OPERATOR_FRENCH, 330 FTDM_CPC_OPERATOR_ENGLISH, 331 FTDM_CPC_OPERATOR_GERMAN, 332 FTDM_CPC_OPERATOR_RUSSIAN, 333 FTDM_CPC_OPERATOR_SPANISH, 334 FTDM_CPC_ORDINARY, 335 FTDM_CPC_PRIORITY, 336 FTDM_CPC_DATA, 337 FTDM_CPC_TEST, 338 FTDM_CPC_PAYPHONE, 339 FTDM_CPC_INVALID 340 } ftdm_calling_party_category_t; 341 #define CALLING_PARTY_CATEGORY_STRINGS "unknown", "operator", "operator-french", "operator-english", "operator-german", "operator-russian", "operator-spanish", "ordinary", "priority", "data-call", "test-call", "payphone", "invalid" 342 FTDM_STR2ENUM_P(ftdm_str2ftdm_calling_party_category, ftdm_calling_party_category2str, ftdm_calling_party_category_t) 343 344 /*! Network responses to transfer requests */ 345 typedef enum { 346 FTDM_TRANSFER_RESPONSE_OK, /* Call is being transferred */ 347 FTDM_TRANSFER_RESPONSE_CP_DROP_OFF, /* Calling Party drop off */ 348 FTDM_TRANSFER_RESPONSE_LIMITS_EXCEEDED, /* Cannot redirect, limits exceeded */ 349 FTDM_TRANSFER_RESPONSE_INVALID_NUM, /* Network did not receive or recognize dialed number */ 350 FTDM_TRANSFER_RESPONSE_INVALID_COMMAND, /* Network received an invalid command */ 351 FTDM_TRANSFER_RESPONSE_TIMEOUT, /* We did not receive a response from Network */ 352 FTDM_TRANSFER_RESPONSE_INVALID, 353 } ftdm_transfer_response_t; 354 #define TRANSFER_RESPONSE_STRINGS "transfer-ok", "cp-drop-off", "limits-exceeded", "invalid-num", "invalid-command", "timeout", "invalid" 355 FTDM_STR2ENUM_P(ftdm_str2ftdm_transfer_response, ftdm_transfer_response2str, ftdm_transfer_response_t) 356 357 /*! \brief Digit limit used in DNIS/ANI */ 358 #define FTDM_DIGITS_LIMIT 64 359 360 #define FTDM_SILENCE_VALUE(fchan) (fchan)->native_codec == FTDM_CODEC_ULAW ? 255 : (fchan)->native_codec == FTDM_CODEC_ALAW ? 0xD5 : 0x00 361 362 /*! \brief Number abstraction */ 363 typedef struct { 364 char digits[FTDM_DIGITS_LIMIT]; 365 uint8_t type; 366 uint8_t plan; 367 } ftdm_number_t; 368 369 typedef struct { 370 char from[FTDM_MAX_NUMBER_STR_SZ]; 371 char body[FTDM_MAX_NAME_STR_SZ]; 372 } ftdm_sms_data_t; 373 374 /*! \brief Caller information */ 375 typedef struct ftdm_caller_data { 376 char cid_date[8]; /*!< Caller ID date */ 377 char cid_name[80]; /*!< Caller ID name */ 378 ftdm_number_t cid_num; /*!< Caller ID number */ 379 ftdm_number_t ani; /*!< ANI (Automatic Number Identification) */ 380 ftdm_number_t dnis; /*!< DNIS (Dialed Number Identification Service) */ 381 ftdm_number_t rdnis; /*!< RDNIS (Redirected Dialed Number Identification Service) */ 382 ftdm_number_t loc; /*!< LOC (Location Reference Code) */ 383 char aniII[FTDM_DIGITS_LIMIT]; /*! ANI II */ 384 uint8_t screen; /*!< Screening */ 385 uint8_t pres; /*!< Presentation*/ 386 char collected[FTDM_DIGITS_LIMIT]; /*!< Collected digits so far */ 387 int hangup_cause; /*!< Hangup cause */ 388 /* these 2 are undocumented right now, only used by boost: */ 389 /* bearer capability */ 390 ftdm_bearer_cap_t bearer_capability; 391 /* user information layer 1 protocol */ 392 ftdm_user_layer1_prot_t bearer_layer1; 393 ftdm_calling_party_category_t cpc; /*!< Calling party category */ 394 uint32_t call_reference; 395 396 ftdm_channel_t *fchan; /*!< FreeTDM channel associated (can be NULL) */ 397 398 /* 399 * We need call_id inside caller_data for the user to be able to retrieve 400 * the call_id when ftdm_channel_call_place is called. This is the only time 401 * that the user can use caller_data.call_id to obtain the call_id. The user 402 * should use the call_id from sigmsg otherwise 403 */ 404 uint32_t call_id; /*!< Unique call ID for this call */ 405 406 void *priv; /*!< Private data for the FreeTDM user */ 407 } ftdm_caller_data_t; 408 409 /*! \brief Hunting mode */ 410 typedef enum { 411 FTDM_HUNT_SPAN, /*!< Hunt channels in a given span */ 412 FTDM_HUNT_GROUP, /*!< Hunt channels in a given group */ 413 FTDM_HUNT_CHAN, /*!< Hunt for a specific channel */ 414 } ftdm_hunt_mode_t; 415 416 /*! \brief Structure used for FTDM_HUNT_SPAN mode */ 417 typedef struct { 418 uint32_t span_id; 419 ftdm_hunt_direction_t direction; 420 } ftdm_span_hunt_t; 421 422 /*! \brief Structure used for FTDM_HUNT_GROUP mode */ 423 typedef struct { 424 uint32_t group_id; 425 ftdm_hunt_direction_t direction; 426 } ftdm_group_hunt_t; 427 428 /*! \brief Structure used for FTDM_HUNT_CHAN mode */ 429 typedef struct { 430 uint32_t span_id; 431 uint32_t chan_id; 432 } ftdm_chan_hunt_t; 433 434 /*! \brief Function called before placing the call in the hunted channel 435 * The user can have a last saying in whether to proceed or abort 436 * the call attempt. Be aware that this callback will be called with 437 * the channel lock and you must not do any blocking operations during 438 * its execution. 439 * \param fchan The channel that will be used to place the call 440 * \param caller_data The caller data provided to ftdm_call_place 441 * \return FTDM_SUCCESS to proceed or FTDM_BREAK to abort the hunting 442 */ 443 typedef ftdm_status_t (*ftdm_hunt_result_cb_t)(ftdm_channel_t *fchan, ftdm_caller_data_t *caller_data); 444 445 /*! \brief Channel Hunting provided to ftdm_call_place() */ 446 typedef struct { 447 ftdm_hunt_mode_t mode; 448 union { 449 ftdm_span_hunt_t span; 450 ftdm_group_hunt_t group; 451 ftdm_chan_hunt_t chan; 452 } mode_data; 453 ftdm_hunt_result_cb_t result_cb; 454 } ftdm_hunting_scheme_t; 455 456 457 /*! \brief Tone type */ 458 typedef enum { 459 FTDM_TONE_DTMF = (1 << 0) 460 } ftdm_tone_type_t; 461 462 /*! \brief Signaling messages sent by the stacks */ 463 typedef enum { 464 FTDM_SIGEVENT_START,/*!< Incoming call (ie: incoming SETUP msg or Ring) */ 465 FTDM_SIGEVENT_STOP, /*!< Hangup */ 466 FTDM_SIGEVENT_RELEASED, /*!< Channel is completely released and available */ 467 FTDM_SIGEVENT_UP, /*!< Outgoing call has been answered */ 468 FTDM_SIGEVENT_FLASH, /*!< Flash event (typically on-hook/off-hook for analog devices) */ 469 FTDM_SIGEVENT_PROCEED, /*!< Outgoing call got an initial positive response from the other end */ 470 FTDM_SIGEVENT_RINGING, /*!< Remote side is in ringing state */ 471 FTDM_SIGEVENT_PROGRESS, /*!< Outgoing call is making progress */ 472 FTDM_SIGEVENT_PROGRESS_MEDIA, /*!< Outgoing call is making progress and there is media available */ 473 FTDM_SIGEVENT_ALARM_TRAP, /*!< Hardware alarm ON */ 474 FTDM_SIGEVENT_ALARM_CLEAR, /*!< Hardware alarm OFF */ 475 FTDM_SIGEVENT_COLLECTED_DIGIT, /*!< Digit collected (in signalings where digits are collected one by one) */ 476 FTDM_SIGEVENT_ADD_CALL, /*!< New call should be added to the channel */ 477 FTDM_SIGEVENT_RESTART, /*!< Restart has been requested. Typically you hangup your call resources here */ 478 FTDM_SIGEVENT_SIGSTATUS_CHANGED, /*!< Signaling protocol status changed (ie: D-chan up), see new status in raw_data ftdm_sigmsg_t member */ 479 FTDM_SIGEVENT_FACILITY, /*!< In call facility event */ 480 FTDM_SIGEVENT_TRACE, /*!<Interpreted trace event */ 481 FTDM_SIGEVENT_TRACE_RAW, /*!<Raw trace event */ 482 FTDM_SIGEVENT_INDICATION_COMPLETED, /*!< Last requested indication was completed */ 483 FTDM_SIGEVENT_DIALING, /*!< Outgoing call just started */ 484 FTDM_SIGEVENT_TRANSFER_COMPLETED, /*!< Transfer request is completed */ 485 FTDM_SIGEVENT_SMS, 486 FTDM_SIGEVENT_INVALID, /*!<Invalid */ 487 } ftdm_signal_event_t; 488 #define SIGNAL_STRINGS "START", "STOP", "RELEASED", "UP", "FLASH", "PROCEED", "RINGING", "PROGRESS", \ 489 "PROGRESS_MEDIA", "ALARM_TRAP", "ALARM_CLEAR", \ 490 "COLLECTED_DIGIT", "ADD_CALL", "RESTART", "SIGSTATUS_CHANGED", "FACILITY", \ 491 "TRACE", "TRACE_RAW", "INDICATION_COMPLETED", "DIALING", "TRANSFER_COMPLETED", "SMS", "INVALID" 492 /*! \brief Move from string to ftdm_signal_event_t and viceversa */ 493 FTDM_STR2ENUM_P(ftdm_str2ftdm_signal_event, ftdm_signal_event2str, ftdm_signal_event_t) 494 495 /*! \brief Span trunk types */ 496 typedef enum { 497 FTDM_TRUNK_E1, 498 FTDM_TRUNK_T1, 499 FTDM_TRUNK_J1, 500 FTDM_TRUNK_BRI, 501 FTDM_TRUNK_BRI_PTMP, 502 FTDM_TRUNK_FXO, 503 FTDM_TRUNK_FXS, 504 FTDM_TRUNK_EM, 505 FTDM_TRUNK_GSM, 506 FTDM_TRUNK_NONE 507 } ftdm_trunk_type_t; 508 #define TRUNK_TYPE_STRINGS "E1", "T1", "J1", "BRI", "BRI_PTMP", "FXO", "FXS", "EM", "GSM", "NONE" 509 510 /*! \brief Move from string to ftdm_trunk_type_t and viceversa */ 511 FTDM_STR2ENUM_P(ftdm_str2ftdm_trunk_type, ftdm_trunk_type2str, ftdm_trunk_type_t) 512 513 /*! \brief Span trunk modes */ 514 typedef enum { 515 FTDM_TRUNK_MODE_CPE, 516 FTDM_TRUNK_MODE_NET, 517 FTDM_TRUNK_MODE_INVALID 518 } ftdm_trunk_mode_t; 519 #define TRUNK_MODE_STRINGS "CPE", "NET", "INVALID" 520 521 /*! \brief Move from string to ftdm_trunk_mode_t and viceversa */ 522 FTDM_STR2ENUM_P(ftdm_str2ftdm_trunk_mode, ftdm_trunk_mode2str, ftdm_trunk_mode_t) 523 524 525 /*! \brief Basic channel configuration provided to ftdm_configure_span_channels */ 526 typedef struct ftdm_channel_config { 527 char name[FTDM_MAX_NAME_STR_SZ]; 528 char number[FTDM_MAX_NUMBER_STR_SZ]; 529 char group_name[FTDM_MAX_NAME_STR_SZ]; 530 ftdm_chan_type_t type; 531 float rxgain; 532 float txgain; 533 uint8_t debugdtmf; 534 uint8_t dtmf_on_start; 535 uint32_t dtmfdetect_ms; 536 uint32_t dtmf_time_on; 537 uint32_t dtmf_time_off; 538 uint8_t iostats; 539 } ftdm_channel_config_t; 540 541 /*! 542 \brief Signaling status on a given span or specific channel on protocols that support it 543 \note see docs/sigstatus.txt for more extensive documentation on signaling status 544 */ 545 typedef enum { 546 /* The signaling link is down (no d-chans up in the span/group, MFC-R2 bit pattern unidentified) */ 547 FTDM_SIG_STATE_DOWN, 548 /* The signaling link is suspended (MFC-R2 bit pattern blocked, ss7 blocked?) */ 549 FTDM_SIG_STATE_SUSPENDED, 550 /* The signaling link is ready and calls can be placed (ie: d-chan up) */ 551 FTDM_SIG_STATE_UP, 552 /* Invalid status */ 553 FTDM_SIG_STATE_INVALID 554 } ftdm_signaling_status_t; 555 #define SIGSTATUS_STRINGS "DOWN", "SUSPENDED", "UP", "INVALID" 556 557 /*! \brief Move from string to ftdm_signaling_status_t and viceversa */ 558 FTDM_STR2ENUM_P(ftdm_str2ftdm_signaling_status, ftdm_signaling_status2str, ftdm_signaling_status_t) 559 560 561 typedef struct { 562 ftdm_signaling_status_t status; 563 } ftdm_event_sigstatus_t; 564 565 typedef enum { 566 /* This is an received frame */ 567 FTDM_TRACE_DIR_INCOMING, 568 /* This is a transmitted frame */ 569 FTDM_TRACE_DIR_OUTGOING, 570 /* Invalid */ 571 FTDM_TRACE_DIR_INVALID, 572 } ftdm_trace_dir_t; 573 #define TRACE_DIR_STRINGS "INCOMING", "OUTGOING", "INVALID" 574 575 /*! \brief Move string to ftdm_trace_dir_t and viceversa */ 576 FTDM_STR2ENUM_P(ftdm_str2ftdm_trace_dir, ftdm_trace_dir2str, ftdm_trace_dir_t) 577 578 typedef enum { 579 FTDM_TRACE_TYPE_Q931, 580 FTDM_TRACE_TYPE_Q921, 581 FTDM_TRACE_TYPE_INVALID, 582 } ftdm_trace_type_t; 583 #define TRACE_TYPE_STRINGS "Q931", "Q921", "INVALID" 584 585 /*! \brief Move string to ftdm_trace_type_t and viceversa */ 586 FTDM_STR2ENUM_P(ftdm_str2ftdm_trace_type, ftdm_trace_type2str, ftdm_trace_type_t) 587 588 typedef struct { 589 /* Direction - incoming or outgoing */ 590 ftdm_trace_dir_t dir; 591 ftdm_trace_type_t type; 592 } ftdm_event_trace_t; 593 594 typedef struct { 595 /* Digits collected */ 596 char digits[FTDM_DIGITS_LIMIT]; 597 } ftdm_event_collected_t; 598 599 /*! \brief FreeTDM supported indications. 600 * This is used during incoming calls when you want to request the signaling stack 601 * to notify about indications occurring locally. See ftdm_channel_call_indicate for more info */ 602 typedef enum { 603 FTDM_CHANNEL_INDICATE_NONE, 604 FTDM_CHANNEL_INDICATE_RINGING, 605 FTDM_CHANNEL_INDICATE_PROCEED, 606 FTDM_CHANNEL_INDICATE_PROGRESS, 607 FTDM_CHANNEL_INDICATE_PROGRESS_MEDIA, 608 FTDM_CHANNEL_INDICATE_BUSY, 609 /* Using this indication is equivalent to call ftdm_channel_call_answer API */ 610 FTDM_CHANNEL_INDICATE_ANSWER, 611 FTDM_CHANNEL_INDICATE_FACILITY, 612 FTDM_CHANNEL_INDICATE_TRANSFER, 613 FTDM_CHANNEL_INDICATE_INVALID, 614 } ftdm_channel_indication_t; 615 #define INDICATION_STRINGS "NONE", "RINGING", "PROCEED", "PROGRESS", "PROGRESS_MEDIA", "BUSY", "ANSWER", "FACILITY", "TRANSFER", "INVALID" 616 617 /*! \brief Move from string to ftdm_channel_indication_t and viceversa */ 618 FTDM_STR2ENUM_P(ftdm_str2ftdm_channel_indication, ftdm_channel_indication2str, ftdm_channel_indication_t) 619 620 typedef struct { 621 /* The indication that was completed */ 622 ftdm_channel_indication_t indication; 623 /* Completion status of the indication */ 624 ftdm_status_t status; 625 } ftdm_event_indication_completed_t; 626 627 typedef struct { 628 ftdm_transfer_response_t response; 629 } ftdm_event_transfer_completed_t; 630 631 typedef void * ftdm_variable_container_t; 632 633 typedef struct { 634 ftdm_size_t len; 635 void *data; 636 } ftdm_raw_data_t; 637 638 /*! \brief Generic signaling message received from the stack */ 639 struct ftdm_sigmsg { 640 ftdm_signal_event_t event_id; /*!< The type of message */ 641 ftdm_channel_t *channel; /*!< Related channel */ 642 uint32_t chan_id; /*!< easy access to chan id */ 643 uint32_t span_id; /*!< easy access to span_id */ 644 uint32_t call_id; /*!< unique call id for this call */ 645 void *call_priv; /*!< Private data for the FreeTDM user from ftdm_caller_data->priv */ 646 ftdm_variable_container_t variables; 647 union { 648 ftdm_event_sigstatus_t sigstatus; /*!< valid if event_id is FTDM_SIGEVENT_SIGSTATUS_CHANGED */ 649 ftdm_event_trace_t trace; /*!< valid if event_id is FTDM_SIGEVENT_TRACE or FTDM_SIGEVENT_TRACE_RAW */ 650 ftdm_event_collected_t collected; /*!< valid if event_id is FTDM_SIGEVENT_COLLECTED_DIGIT */ 651 ftdm_event_indication_completed_t indication_completed; /*!< valid if the event_id is FTDM_SIGEVENT_INDICATION_COMPLETED */ 652 ftdm_event_transfer_completed_t transfer_completed; 653 } ev_data; 654 ftdm_raw_data_t raw; 655 }; 656 657 /*! \brief Generic user message sent to the stack */ 658 struct ftdm_usrmsg { 659 ftdm_variable_container_t variables; 660 ftdm_raw_data_t raw; 661 }; 662 663 /*! \brief Crash policy 664 * Useful for debugging only, default policy is never, if you wish to crash on asserts then use ftdm_global_set_crash_policy */ 665 typedef enum { 666 FTDM_CRASH_NEVER = 0, 667 FTDM_CRASH_ON_ASSERT 668 } ftdm_crash_policy_t; 669 670 /*! \brief Signaling configuration parameter for the stacks (variable=value pair) */ 671 typedef struct ftdm_conf_parameter { 672 const char *var; 673 const char *val; 674 void *ptr; 675 } ftdm_conf_parameter_t; 676 677 /*! \brief Opaque general purpose iterator */ 678 typedef struct ftdm_iterator ftdm_iterator_t; 679 680 /*! \brief Channel commands that can be executed through ftdm_channel_command() */ 681 typedef enum { 682 FTDM_COMMAND_NOOP = 0, 683 FTDM_COMMAND_SET_INTERVAL = 1, 684 FTDM_COMMAND_GET_INTERVAL = 2, 685 FTDM_COMMAND_SET_CODEC = 3, 686 FTDM_COMMAND_GET_CODEC = 4, 687 FTDM_COMMAND_SET_NATIVE_CODEC = 5, 688 FTDM_COMMAND_GET_NATIVE_CODEC = 6, 689 FTDM_COMMAND_ENABLE_DTMF_DETECT = 7, 690 FTDM_COMMAND_DISABLE_DTMF_DETECT = 8, 691 FTDM_COMMAND_SEND_DTMF = 9, 692 FTDM_COMMAND_SET_DTMF_ON_PERIOD = 10, 693 FTDM_COMMAND_GET_DTMF_ON_PERIOD = 11, 694 FTDM_COMMAND_SET_DTMF_OFF_PERIOD = 12, 695 FTDM_COMMAND_GET_DTMF_OFF_PERIOD = 13, 696 FTDM_COMMAND_GENERATE_RING_ON = 14, 697 FTDM_COMMAND_GENERATE_RING_OFF = 15, 698 FTDM_COMMAND_OFFHOOK = 16, 699 FTDM_COMMAND_ONHOOK = 17, 700 FTDM_COMMAND_FLASH = 18, 701 FTDM_COMMAND_WINK = 19, 702 FTDM_COMMAND_ENABLE_PROGRESS_DETECT = 20, 703 FTDM_COMMAND_DISABLE_PROGRESS_DETECT = 21, 704 705 /*!< Start tracing input and output from channel to the given file */ 706 FTDM_COMMAND_TRACE_INPUT = 22, 707 FTDM_COMMAND_TRACE_OUTPUT = 23, 708 709 /*!< Stop both Input and Output trace, closing the files */ 710 FTDM_COMMAND_TRACE_END_ALL = 24, 711 712 /*!< Enable DTMF debugging */ 713 FTDM_COMMAND_ENABLE_DEBUG_DTMF = 25, 714 715 /*!< Disable DTMF debugging (if not disabled explicitly, it is disabled automatically when calls hangup) */ 716 FTDM_COMMAND_DISABLE_DEBUG_DTMF = 26, 717 718 /*!< Start dumping all input to a circular buffer. The size of the circular buffer can be specified, default used otherwise */ 719 FTDM_COMMAND_ENABLE_INPUT_DUMP = 27, 720 721 /*!< Stop dumping all input to a circular buffer. */ 722 FTDM_COMMAND_DISABLE_INPUT_DUMP = 28, 723 724 /*!< Start dumping all output to a circular buffer. The size of the circular buffer can be specified, default used otherwise */ 725 FTDM_COMMAND_ENABLE_OUTPUT_DUMP = 29, 726 727 /*!< Stop dumping all output to a circular buffer. */ 728 FTDM_COMMAND_DISABLE_OUTPUT_DUMP = 30, 729 730 /*!< Dump the current input circular buffer to the specified FILE* structure */ 731 FTDM_COMMAND_DUMP_INPUT = 31, 732 733 /*!< Dump the current output circular buffer to the specified FILE* structure */ 734 FTDM_COMMAND_DUMP_OUTPUT = 32, 735 736 FTDM_COMMAND_ENABLE_CALLERID_DETECT = 33, 737 FTDM_COMMAND_DISABLE_CALLERID_DETECT = 34, 738 FTDM_COMMAND_ENABLE_ECHOCANCEL = 35, 739 FTDM_COMMAND_DISABLE_ECHOCANCEL = 36, 740 FTDM_COMMAND_ENABLE_ECHOTRAIN = 37, 741 FTDM_COMMAND_DISABLE_ECHOTRAIN = 38, 742 FTDM_COMMAND_SET_CAS_BITS = 39, 743 FTDM_COMMAND_GET_CAS_BITS = 40, 744 FTDM_COMMAND_SET_RX_GAIN = 41, 745 FTDM_COMMAND_GET_RX_GAIN = 42, 746 FTDM_COMMAND_SET_TX_GAIN = 43, 747 FTDM_COMMAND_GET_TX_GAIN = 44, 748 FTDM_COMMAND_FLUSH_TX_BUFFERS = 45, 749 FTDM_COMMAND_FLUSH_RX_BUFFERS = 46, 750 FTDM_COMMAND_FLUSH_BUFFERS = 47, 751 752 /*!< Flush IO statistics */ 753 FTDM_COMMAND_FLUSH_IOSTATS = 48, 754 755 FTDM_COMMAND_SET_PRE_BUFFER_SIZE = 49, 756 FTDM_COMMAND_SET_LINK_STATUS = 50, 757 FTDM_COMMAND_GET_LINK_STATUS = 51, 758 FTDM_COMMAND_ENABLE_LOOP = 52, 759 FTDM_COMMAND_DISABLE_LOOP = 53, 760 FTDM_COMMAND_SET_RX_QUEUE_SIZE = 54, 761 FTDM_COMMAND_SET_TX_QUEUE_SIZE = 55, 762 FTDM_COMMAND_SET_POLARITY = 56, 763 FTDM_COMMAND_START_MF_PLAYBACK = 57, 764 FTDM_COMMAND_STOP_MF_PLAYBACK = 58, 765 766 /*!< Get a copy of the current IO stats */ 767 FTDM_COMMAND_GET_IOSTATS = 59, 768 /*!< Enable/disable IO stats in the channel */ 769 FTDM_COMMAND_SWITCH_IOSTATS = 60, 770 771 /*!< Enable/disable DTMF removal */ 772 FTDM_COMMAND_ENABLE_DTMF_REMOVAL = 61, 773 FTDM_COMMAND_DISABLE_DTMF_REMOVAL = 62, 774 775 FTDM_COMMAND_COUNT, 776 } ftdm_command_t; 777 778 typedef enum { 779 FTDM_POLARITY_FORWARD = 0, 780 FTDM_POLARITY_REVERSE = 1 781 } ftdm_polarity_t; 782 783 /*! \brief Custom memory handler hooks. Not recommended to use unless you need memory allocation customizations */ 784 typedef void *(*ftdm_malloc_func_t)(void *pool, ftdm_size_t len); 785 typedef void *(*ftdm_calloc_func_t)(void *pool, ftdm_size_t elements, ftdm_size_t len); 786 typedef void *(*ftdm_realloc_func_t)(void *pool, void *buff, ftdm_size_t len); 787 typedef void (*ftdm_free_func_t)(void *pool, void *ptr); 788 struct ftdm_memory_handler { 789 void *pool; 790 ftdm_malloc_func_t malloc; 791 ftdm_calloc_func_t calloc; 792 ftdm_realloc_func_t realloc; 793 ftdm_free_func_t free; 794 }; 795 796 /*! \brief FreeTDM I/O layer interface argument macros 797 * You don't need these unless your implementing an I/O interface module (most users don't) */ 798 #define FIO_CHANNEL_REQUEST_ARGS (ftdm_span_t *span, uint32_t chan_id, ftdm_hunt_direction_t direction, ftdm_caller_data_t *caller_data, ftdm_channel_t **ftdmchan) 799 #define FIO_CHANNEL_OUTGOING_CALL_ARGS (ftdm_channel_t *ftdmchan) 800 #define FIO_CHANNEL_INDICATE_ARGS (ftdm_channel_t *ftdmchan, ftdm_channel_indication_t indication) 801 #define FIO_CHANNEL_SET_SIG_STATUS_ARGS (ftdm_channel_t *ftdmchan, ftdm_signaling_status_t status) 802 #define FIO_CHANNEL_GET_SIG_STATUS_ARGS (ftdm_channel_t *ftdmchan, ftdm_signaling_status_t *status) 803 #define FIO_SPAN_SET_SIG_STATUS_ARGS (ftdm_span_t *span, ftdm_signaling_status_t status) 804 #define FIO_SPAN_GET_SIG_STATUS_ARGS (ftdm_span_t *span, ftdm_signaling_status_t *status) 805 #define FIO_SPAN_POLL_EVENT_ARGS (ftdm_span_t *span, uint32_t ms, short *poll_events) 806 #define FIO_SPAN_NEXT_EVENT_ARGS (ftdm_span_t *span, ftdm_event_t **event) 807 #define FIO_CHANNEL_NEXT_EVENT_ARGS (ftdm_channel_t *ftdmchan, ftdm_event_t **event) 808 #define FIO_SIGNAL_CB_ARGS (ftdm_sigmsg_t *sigmsg) 809 #define FIO_EVENT_CB_ARGS (ftdm_channel_t *ftdmchan, ftdm_event_t *event) 810 #define FIO_CONFIGURE_SPAN_ARGS (ftdm_span_t *span, const char *str, ftdm_chan_type_t type, char *name, char *number) 811 #define FIO_CONFIGURE_ARGS (const char *category, const char *var, const char *val, int lineno) 812 #define FIO_OPEN_ARGS (ftdm_channel_t *ftdmchan) 813 #define FIO_CLOSE_ARGS (ftdm_channel_t *ftdmchan) 814 #define FIO_CHANNEL_DESTROY_ARGS (ftdm_channel_t *ftdmchan) 815 #define FIO_SPAN_DESTROY_ARGS (ftdm_span_t *span) 816 #define FIO_COMMAND_ARGS (ftdm_channel_t *ftdmchan, ftdm_command_t command, void *obj) 817 #define FIO_WAIT_ARGS (ftdm_channel_t *ftdmchan, ftdm_wait_flag_t *flags, int32_t to) 818 #define FIO_GET_ALARMS_ARGS (ftdm_channel_t *ftdmchan) 819 #define FIO_READ_ARGS (ftdm_channel_t *ftdmchan, void *data, ftdm_size_t *datalen) 820 #define FIO_WRITE_ARGS (ftdm_channel_t *ftdmchan, void *data, ftdm_size_t *datalen) 821 #define FIO_IO_LOAD_ARGS (ftdm_io_interface_t **fio) 822 #define FIO_IO_UNLOAD_ARGS (void) 823 #define FIO_SIG_LOAD_ARGS (void) 824 #define FIO_SIG_CONFIGURE_ARGS (ftdm_span_t *span, fio_signal_cb_t sig_cb, va_list ap) 825 #define FIO_CONFIGURE_SPAN_SIGNALING_ARGS (ftdm_span_t *span, fio_signal_cb_t sig_cb, ftdm_conf_parameter_t *ftdm_parameters) 826 #define FIO_SIG_UNLOAD_ARGS (void) 827 #define FIO_API_ARGS (ftdm_stream_handle_t *stream, const char *data) 828 #define FIO_SPAN_START_ARGS (ftdm_span_t *span) 829 #define FIO_SPAN_STOP_ARGS (ftdm_span_t *span) 830 831 /*! \brief FreeTDM I/O layer interface function typedefs 832 * You don't need these unless your implementing an I/O interface module (most users don't) */ 833 typedef ftdm_status_t (*fio_channel_request_t) FIO_CHANNEL_REQUEST_ARGS ; 834 typedef ftdm_status_t (*fio_channel_outgoing_call_t) FIO_CHANNEL_OUTGOING_CALL_ARGS ; 835 typedef ftdm_status_t (*fio_channel_indicate_t) FIO_CHANNEL_INDICATE_ARGS; 836 typedef ftdm_status_t (*fio_channel_set_sig_status_t) FIO_CHANNEL_SET_SIG_STATUS_ARGS; 837 typedef ftdm_status_t (*fio_channel_get_sig_status_t) FIO_CHANNEL_GET_SIG_STATUS_ARGS; 838 typedef ftdm_status_t (*fio_span_set_sig_status_t) FIO_SPAN_SET_SIG_STATUS_ARGS; 839 typedef ftdm_status_t (*fio_span_get_sig_status_t) FIO_SPAN_GET_SIG_STATUS_ARGS; 840 typedef ftdm_status_t (*fio_span_poll_event_t) FIO_SPAN_POLL_EVENT_ARGS ; 841 typedef ftdm_status_t (*fio_span_next_event_t) FIO_SPAN_NEXT_EVENT_ARGS ; 842 typedef ftdm_status_t (*fio_channel_next_event_t) FIO_CHANNEL_NEXT_EVENT_ARGS ; 843 844 /*! \brief Callback for signal delivery (FTDM_SIGEVENT_START and friends) 845 * \note This callback is provided by the user during ftdm_configure_span_signaling 846 * 847 * \note You must NOT do any blocking during this callback since this function is 848 * most likely called in an internal signaling thread that can potentially be 849 * shared for all the channels in a span and blocking will delay processing 850 * (sometimes even audio processing) for other channels 851 * 852 * \note Although some simple FreeTDM APIs can work (ie: ftdm_span_get_id etc), the 853 * use of any FreeTDM call API (ie ftdm_channel_call_answer) is discouraged 854 */ 855 typedef ftdm_status_t (*fio_signal_cb_t) FIO_SIGNAL_CB_ARGS ; 856 857 typedef ftdm_status_t (*fio_event_cb_t) FIO_EVENT_CB_ARGS ; 858 typedef ftdm_status_t (*fio_configure_span_t) FIO_CONFIGURE_SPAN_ARGS ; 859 typedef ftdm_status_t (*fio_configure_t) FIO_CONFIGURE_ARGS ; 860 typedef ftdm_status_t (*fio_open_t) FIO_OPEN_ARGS ; 861 typedef ftdm_status_t (*fio_close_t) FIO_CLOSE_ARGS ; 862 typedef ftdm_status_t (*fio_channel_destroy_t) FIO_CHANNEL_DESTROY_ARGS ; 863 typedef ftdm_status_t (*fio_span_destroy_t) FIO_SPAN_DESTROY_ARGS ; 864 typedef ftdm_status_t (*fio_get_alarms_t) FIO_GET_ALARMS_ARGS ; 865 typedef ftdm_status_t (*fio_command_t) FIO_COMMAND_ARGS ; 866 typedef ftdm_status_t (*fio_wait_t) FIO_WAIT_ARGS ; 867 typedef ftdm_status_t (*fio_read_t) FIO_READ_ARGS ; 868 typedef ftdm_status_t (*fio_write_t) FIO_WRITE_ARGS ; 869 typedef ftdm_status_t (*fio_io_load_t) FIO_IO_LOAD_ARGS ; 870 typedef ftdm_status_t (*fio_sig_load_t) FIO_SIG_LOAD_ARGS ; 871 typedef ftdm_status_t (*fio_sig_configure_t) FIO_SIG_CONFIGURE_ARGS ; 872 typedef ftdm_status_t (*fio_configure_span_signaling_t) FIO_CONFIGURE_SPAN_SIGNALING_ARGS ; 873 typedef ftdm_status_t (*fio_io_unload_t) FIO_IO_UNLOAD_ARGS ; 874 typedef ftdm_status_t (*fio_sig_unload_t) FIO_SIG_UNLOAD_ARGS ; 875 typedef ftdm_status_t (*fio_api_t) FIO_API_ARGS ; 876 typedef ftdm_status_t (*fio_span_start_t) FIO_SPAN_START_ARGS ; 877 typedef ftdm_status_t (*fio_span_stop_t) FIO_SPAN_STOP_ARGS ; 878 879 880 /*! \brief FreeTDM I/O layer interface function prototype wrapper macros 881 * You don't need these unless your implementing an I/O interface module (most users don't) */ 882 #define FIO_CHANNEL_REQUEST_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_REQUEST_ARGS 883 #define FIO_CHANNEL_OUTGOING_CALL_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_OUTGOING_CALL_ARGS 884 #define FIO_CHANNEL_INDICATE_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_INDICATE_ARGS 885 #define FIO_CHANNEL_SET_SIG_STATUS_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_SET_SIG_STATUS_ARGS 886 #define FIO_CHANNEL_GET_SIG_STATUS_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_GET_SIG_STATUS_ARGS 887 #define FIO_SPAN_SET_SIG_STATUS_FUNCTION(name) ftdm_status_t name FIO_SPAN_SET_SIG_STATUS_ARGS 888 #define FIO_SPAN_GET_SIG_STATUS_FUNCTION(name) ftdm_status_t name FIO_SPAN_GET_SIG_STATUS_ARGS 889 #define FIO_SPAN_POLL_EVENT_FUNCTION(name) ftdm_status_t name FIO_SPAN_POLL_EVENT_ARGS 890 #define FIO_SPAN_NEXT_EVENT_FUNCTION(name) ftdm_status_t name FIO_SPAN_NEXT_EVENT_ARGS 891 #define FIO_CHANNEL_NEXT_EVENT_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_NEXT_EVENT_ARGS 892 #define FIO_SIGNAL_CB_FUNCTION(name) ftdm_status_t name FIO_SIGNAL_CB_ARGS 893 #define FIO_EVENT_CB_FUNCTION(name) ftdm_status_t name FIO_EVENT_CB_ARGS 894 #define FIO_CONFIGURE_SPAN_FUNCTION(name) ftdm_status_t name FIO_CONFIGURE_SPAN_ARGS 895 #define FIO_CONFIGURE_FUNCTION(name) ftdm_status_t name FIO_CONFIGURE_ARGS 896 #define FIO_OPEN_FUNCTION(name) ftdm_status_t name FIO_OPEN_ARGS 897 #define FIO_CLOSE_FUNCTION(name) ftdm_status_t name FIO_CLOSE_ARGS 898 #define FIO_CHANNEL_DESTROY_FUNCTION(name) ftdm_status_t name FIO_CHANNEL_DESTROY_ARGS 899 #define FIO_SPAN_DESTROY_FUNCTION(name) ftdm_status_t name FIO_SPAN_DESTROY_ARGS 900 #define FIO_GET_ALARMS_FUNCTION(name) ftdm_status_t name FIO_GET_ALARMS_ARGS 901 #define FIO_COMMAND_FUNCTION(name) ftdm_status_t name FIO_COMMAND_ARGS 902 #define FIO_WAIT_FUNCTION(name) ftdm_status_t name FIO_WAIT_ARGS 903 #define FIO_READ_FUNCTION(name) ftdm_status_t name FIO_READ_ARGS 904 #define FIO_WRITE_FUNCTION(name) ftdm_status_t name FIO_WRITE_ARGS 905 #define FIO_IO_LOAD_FUNCTION(name) ftdm_status_t name FIO_IO_LOAD_ARGS 906 #define FIO_SIG_LOAD_FUNCTION(name) ftdm_status_t name FIO_SIG_LOAD_ARGS 907 #define FIO_SIG_CONFIGURE_FUNCTION(name) ftdm_status_t name FIO_SIG_CONFIGURE_ARGS 908 #define FIO_CONFIGURE_SPAN_SIGNALING_FUNCTION(name) ftdm_status_t name FIO_CONFIGURE_SPAN_SIGNALING_ARGS 909 #define FIO_IO_UNLOAD_FUNCTION(name) ftdm_status_t name FIO_IO_UNLOAD_ARGS 910 #define FIO_SIG_UNLOAD_FUNCTION(name) ftdm_status_t name FIO_SIG_UNLOAD_ARGS 911 #define FIO_API_FUNCTION(name) ftdm_status_t name FIO_API_ARGS 912 #define FIO_SPAN_START_FUNCTION(name) ftdm_status_t name FIO_SPAN_START_ARGS 913 #define FIO_SPAN_STOP_FUNCTION(name) ftdm_status_t name FIO_SPAN_STOP_ARGS 914 915 /*! \brief FreeTDM I/O layer function prototype wrapper macros 916 * You don't need these unless your implementing an I/O interface module (most users don't) */ 917 struct ftdm_io_interface { 918 const char *name; /*!< I/O module name */ 919 fio_configure_span_t configure_span; /*!< Configure span I/O */ 920 fio_configure_t configure; /*!< Configure the module */ 921 fio_open_t open; /*!< Open I/O channel */ 922 fio_close_t close; /*!< Close I/O channel */ 923 fio_channel_destroy_t channel_destroy; /*!< Destroy I/O channel */ 924 fio_span_destroy_t span_destroy; /*!< Destroy span I/O */ 925 fio_get_alarms_t get_alarms; /*!< Get hardware alarms */ 926 fio_command_t command; /*!< Execute an I/O command on the channel */ 927 fio_wait_t wait; /*!< Wait for events on the channel */ 928 fio_read_t read; /*!< Read data from the channel */ 929 fio_write_t write; /*!< Write data to the channel */ 930 fio_span_poll_event_t poll_event; /*!< Poll for events on the whole span */ 931 fio_span_next_event_t next_event; /*!< Retrieve an event from the span */ 932 fio_channel_next_event_t channel_next_event; /*!< Retrieve an event from channel */ 933 fio_api_t api; /*!< Execute a text command */ 934 fio_span_start_t span_start; /*!< Start span I/O */ 935 fio_span_stop_t span_stop; /*!< Stop span I/O */ 936 }; 937 938 /*! \brief FreeTDM supported I/O codecs */ 939 typedef enum { 940 FTDM_CODEC_ULAW = 0, 941 FTDM_CODEC_ALAW = 8, 942 FTDM_CODEC_SLIN = 10, 943 FTDM_CODEC_NONE = (1 << 30) 944 } ftdm_codec_t; 945 946 /*! \brief FreeTDM supported hardware alarms. */ 947 typedef enum { 948 FTDM_ALARM_NONE = 0, 949 FTDM_ALARM_RED = (1 << 0), 950 FTDM_ALARM_YELLOW = (1 << 1), 951 FTDM_ALARM_RAI = (1 << 2), 952 FTDM_ALARM_BLUE = (1 << 3), 953 FTDM_ALARM_AIS = (1 << 4), 954 FTDM_ALARM_GENERAL = (1 << 30) 955 } ftdm_alarm_flag_t; 956 957 /*! \brief MF generation direction flags 958 * \note Used in bitwise OR with channel ID as argument to MF_PLAYBACK I/O command, so value must be higher that 255 959 * \see FTDM_COMMAND_START_MF_PLAYBACK 960 * */ 961 962 typedef enum { 963 FTDM_MF_DIRECTION_FORWARD = (1 << 8), 964 FTDM_MF_DIRECTION_BACKWARD = (1 << 9) 965 } ftdm_mf_direction_flag_t; 966 967 /*! \brief IO Error statistics */ 968 typedef enum { 969 FTDM_IOSTATS_ERROR_CRC = (1 << 0), 970 FTDM_IOSTATS_ERROR_FRAME = (1 << 1), 971 FTDM_IOSTATS_ERROR_ABORT = (1 << 2), 972 FTDM_IOSTATS_ERROR_FIFO = (1 << 3), 973 FTDM_IOSTATS_ERROR_DMA = (1 << 4), 974 FTDM_IOSTATS_ERROR_QUEUE_THRES = (1 << 5), /* Queue reached high threshold */ 975 FTDM_IOSTATS_ERROR_QUEUE_FULL = (1 << 6), /* Queue is full */ 976 } ftdm_iostats_error_type_t; 977 978 /*! \brief IO statistics */ 979 typedef struct { 980 struct { 981 uint64_t packets; 982 uint32_t errors; 983 uint16_t flags; 984 uint8_t queue_size; /*!< max queue size configured */ 985 uint8_t queue_len; /*!< Current number of elements in queue */ 986 } rx; 987 988 struct { 989 uint64_t idle_packets; 990 uint64_t packets; 991 uint32_t errors; 992 uint16_t flags; 993 uint8_t queue_size; /*!< max queue size configured */ 994 uint8_t queue_len; /*!< Current number of elements in queue */ 995 } tx; 996 } ftdm_channel_iostats_t; 997 998 /*! \brief Override the default queue handler */ 999 FT_DECLARE(ftdm_status_t) ftdm_global_set_queue_handler(ftdm_queue_handler_t *handler); 1000 1001 /*! \brief Return the availability rate for a channel 1002 * \param ftdmchan Channel to get the availability from 1003 * 1004 * \retval > 0 if availability is supported 1005 * \retval -1 if availability is not supported 1006 */ 1007 FT_DECLARE(int) ftdm_channel_get_availability(ftdm_channel_t *ftdmchan); 1008 1009 /*! \brief Answer call. This can also be accomplished by ftdm_channel_call_indicate with FTDM_CHANNEL_INDICATE_ANSWER, in both 1010 * cases you will get a FTDM_SIGEVENT_INDICATION_COMPLETED when the indication is sent (or an error occurs). 1011 * Just as with ftdm_channel_call_indicate you won't receive FTDM_SIGEVENT_INDICATION_COMPLETED when this function 1012 * returns anything else than FTDM_SUCCESS 1013 * \note Although this API may result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered, 1014 * there is no guarantee of whether the event will arrive after or before your execution thread returns 1015 * from ftdm_channel_call_answer 1016 */ 1017 #define ftdm_channel_call_answer(ftdmchan) _ftdm_channel_call_answer(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1018 #define ftdm_channel_call_answer_ex(ftdmchan, usrmsg) _ftdm_channel_call_answer(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (usrmsg)) 1019 1020 /*! \brief Answer call recording the source code point where the it was called (see ftdm_channel_call_answer for an easy to use macro) */ 1021 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_answer(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1022 1023 /*! \brief Place an outgoing call in the given channel 1024 * \deprecated This macro is deprecated since leaves the door open to glare issues, use ftdm_call_place instead 1025 */ 1026 #define ftdm_channel_call_place(ftdmchan) _ftdm_channel_call_place(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1027 #define ftdm_channel_call_place_ex(ftdmchan, usrmsg) _ftdm_channel_call_place_ex(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (usrmsg)) 1028 1029 /*! \brief Place an outgoing call recording the source code point where it was called (see ftdm_channel_call_place for an easy to use macro) 1030 * \deprecated This function is deprecated since leaves the door open to glare issues, use ftdm_call_place instead 1031 */ 1032 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_place(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1033 1034 /*! \brief Place an outgoing call with the given caller data in a channel according to the hunting scheme provided */ 1035 #define ftdm_call_place(callerdata, hunting) _ftdm_call_place(__FILE__, __FTDM_FUNC__, __LINE__, (callerdata), (hunting), NULL) 1036 #define ftdm_call_place_ex(callerdata, hunting, usrmsg) _ftdm_call_place(__FILE__, __FTDM_FUNC__, __LINE__, (callerdata), (hunting), (usrmsg)) 1037 1038 /*! \brief Place an outgoing call with the given caller data in a channel according to the hunting scheme provided and records 1039 * the place where it was called. See ftdm_call_place for an easy to use macro 1040 * \return FTDM_SUCCESS if the call attempt was successful 1041 * FTDM_FAIL if there was an unspecified error 1042 * FTDM_EBUSY if the channel was busy 1043 * FTDM_BREAK if glare was detected and you must try again 1044 * \note Even when FTDM_SUCCESS is returned, the call may still fail later on due to glare, in such case FTDM_SIGEVENT_STOP 1045 * will be sent with the hangup cause field set to FTDM_CAUSE_REQUESTED_CHAN_UNAVAIL 1046 * 1047 * \note When this function returns FTDM_SUCCESS, the member .fchan from caller_data will be set to the channel used to place the call 1048 * and .call_id to the generated call id for that call 1049 * 1050 * \note When this function is successful you are guaranteed to receive FTDM_SIGEVENT_DIALING, this event could even be delivered 1051 * before your execution thread returns from this function 1052 */ 1053 FT_DECLARE(ftdm_status_t) _ftdm_call_place(const char *file, const char *func, int line, ftdm_caller_data_t *caller_data, ftdm_hunting_scheme_t *hunting, ftdm_usrmsg_t *usrmsg); 1054 1055 /*! \brief Indicate a new condition in an incoming call 1056 * 1057 * \note Every indication request will result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered with 1058 * the proper status that will inform you if the request was successful or not. The exception is if this 1059 * function returns something different to FTDM_SUCCESS, in which case the request failed right away and no 1060 * further FTDM_SIGEVENT_INDICATION_COMPLETED will be delivered 1061 * Be aware there is no guarantee of whether the completion event will arrive after or before your execution 1062 * thread returns from ftdm_channel_call_indicate. This means you could get FTDM_SIGEVENT_INDICATION_COMPLETED 1063 * even before your execution thread returns from the ftdm_channel_call_indicate() API 1064 * 1065 * \note You cannot send more than one indication at the time. You must wait for the completed event before 1066 * calling this function again (unless the return code was different than FTDM_SUCCESS) 1067 */ 1068 #define ftdm_channel_call_indicate(ftdmchan, indication) _ftdm_channel_call_indicate(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (indication), NULL) 1069 #define ftdm_channel_call_indicate_ex(ftdmchan, indication, usrmsg) _ftdm_channel_call_indicate(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (indication), (usrmsg)) 1070 1071 /*! \brief Indicate a new condition in an incoming call recording the source code point where it was called (see ftdm_channel_call_indicate for an easy to use macro) */ 1072 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_indicate(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_channel_indication_t indication, ftdm_usrmsg_t *usrmsg); 1073 1074 /*! \brief Hangup the call without cause */ 1075 #define ftdm_channel_call_hangup(ftdmchan) _ftdm_channel_call_hangup(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1076 #define ftdm_channel_call_hangup_ex(ftdmchan, usrmsg) _ftdm_channel_call_hangup(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (usrmsg)) 1077 1078 /*! \brief Hangup the call without cause recording the source code point where it was called (see ftdm_channel_call_hangup for an easy to use macro)*/ 1079 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_hangup(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1080 1081 /*! \brief Hangup the call with cause */ 1082 #define ftdm_channel_call_hangup_with_cause(ftdmchan, cause) _ftdm_channel_call_hangup_with_cause(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (cause), NULL) 1083 #define ftdm_channel_call_hangup_with_cause_ex(ftdmchan, cause, usrmsg) _ftdm_channel_call_hangup_with_cause(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (cause), (usrmsg)) 1084 1085 /*! \brief Hangup the call with cause recording the source code point where it was called (see ftdm_channel_call_hangup_with_cause for an easy to use macro) */ 1086 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_hangup_with_cause(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_call_cause_t, ftdm_usrmsg_t *usrmsg); 1087 1088 /*! \brief Transfer call. This can also be accomplished by ftdm_channel_call_indicate with FTDM_CHANNEL_INDICATE_TRANSFER, in both 1089 * cases you will get a FTDM_SIGEVENT_INDICATION_COMPLETED when the indication is sent (or an error occurs). 1090 * Just as with ftdm_channel_call_indicate you won't receive FTDM_SIGEVENT_INDICATION_COMPLETED when this function 1091 * returns anything else than FTDM_SUCCESS 1092 * \note Although this API may result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered, 1093 * there is no guarantee of whether the event will arrive after or before your execution thread returns 1094 * from ftdm_channel_call_transfer 1095 */ 1096 #define ftdm_channel_call_transfer(ftdmchan, arg) _ftdm_channel_call_transfer(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (arg), NULL) 1097 #define ftdm_channel_call_transfer_ex(ftdmchan, arg, usrmsg) _ftdm_channel_call_transfer(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (arg), (usrmsg)) 1098 1099 /*! \brief Answer call recording the source code point where the it was called (see ftdm_channel_call_tranasfer for an easy to use macro) */ 1100 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_transfer(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, const char* arg, ftdm_usrmsg_t *usrmsg); 1101 1102 /*! \brief Reset the channel */ 1103 #define ftdm_channel_reset(ftdmchan) _ftdm_channel_reset(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1104 #define ftdm_channel_reset_ex(ftdmchan, usrmsg) _ftdm_channel_reset(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), usrmsg) 1105 1106 /*! \brief Reset the channel (see _ftdm_channel_reset for an easy to use macro) 1107 * \note if there was a call on this channel, call will be cleared without any notifications to the user 1108 */ 1109 FT_DECLARE(ftdm_status_t) _ftdm_channel_reset(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1110 1111 /*! \brief Put a call on hold (if supported by the signaling stack) */ 1112 #define ftdm_channel_call_hold(ftdmchan) _ftdm_channel_call_hold(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1113 #define ftdm_channel_call_hold_ex(ftdmchan, usrmsg) _ftdm_channel_call_hold(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (usrmsg)) 1114 1115 /*! \brief Put a call on hold recording the source code point where it was called (see ftdm_channel_call_hold for an easy to use macro) */ 1116 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_hold(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1117 1118 /*! \brief Unhold a call */ 1119 #define ftdm_channel_call_unhold(ftdmchan) _ftdm_channel_call_unhold(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), NULL) 1120 #define ftdm_channel_call_unhold_ex(ftdmchan, usrmsg) _ftdm_channel_call_unhold(__FILE__, __FTDM_FUNC__, __LINE__, (ftdmchan), (usrmsg)) 1121 1122 /*! \brief Unhold a call recording the source code point where it was called (see ftdm_channel_call_unhold for an easy to use macro) */ 1123 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_unhold(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan, ftdm_usrmsg_t *usrmsg); 1124 1125 /*! \brief Check if the call is answered already */ 1126 FT_DECLARE(ftdm_bool_t) ftdm_channel_call_check_answered(const ftdm_channel_t *ftdmchan); 1127 1128 /*! \brief Check if the call is busy */ 1129 FT_DECLARE(ftdm_bool_t) ftdm_channel_call_check_busy(const ftdm_channel_t *ftdmchan); 1130 1131 /*! \brief Check if the call is hangup */ 1132 FT_DECLARE(ftdm_bool_t) ftdm_channel_call_check_hangup(const ftdm_channel_t *ftdmchan); 1133 1134 /*! \brief Check if the call is done (final state for a call, just after hangup) */ 1135 FT_DECLARE(ftdm_bool_t) ftdm_channel_call_check_done(const ftdm_channel_t *ftdmchan); 1136 1137 /*! \brief Check if the call is in hold */ 1138 FT_DECLARE(ftdm_bool_t) ftdm_channel_call_check_hold(const ftdm_channel_t *ftdmchan); 1139 1140 /*! \brief Set channel signaling status (ie: put specific circuit down) only if supported by the signaling */ 1141 FT_DECLARE(ftdm_status_t) ftdm_channel_set_sig_status(ftdm_channel_t *ftdmchan, ftdm_signaling_status_t status); 1142 1143 /*! \brief Get channel signaling status (ie: whether protocol layer is up or down) */ 1144 FT_DECLARE(ftdm_status_t) ftdm_channel_get_sig_status(ftdm_channel_t *ftdmchan, ftdm_signaling_status_t *status); 1145 1146 /*! \brief Set span signaling status (ie: put the whole span protocol layer down) only if supported by the signaling */ 1147 FT_DECLARE(ftdm_status_t) ftdm_span_set_sig_status(ftdm_span_t *span, ftdm_signaling_status_t status); 1148 1149 /*! \brief Get span signaling status (ie: whether protocol layer is up or down) */ 1150 FT_DECLARE(ftdm_status_t) ftdm_span_get_sig_status(ftdm_span_t *span, ftdm_signaling_status_t *status); 1151 1152 1153 /*! 1154 * \brief Set user private data in the channel 1155 * 1156 * \param ftdmchan The channel where the private data will be stored 1157 * \param pvt The private pointer to store 1158 * 1159 */ 1160 FT_DECLARE(void) ftdm_channel_set_private(ftdm_channel_t *ftdmchan, void *pvt); 1161 1162 /*! 1163 * \brief Get user private data in the channel 1164 * 1165 * \param ftdmchan The channel to retrieve the private data 1166 * \retval The private data (if any or NULL if no data has been stored) 1167 * 1168 */ 1169 FT_DECLARE(void *) ftdm_channel_get_private(const ftdm_channel_t *ftdmchan); 1170 1171 /*! 1172 * \brief Remove the given token from the channel 1173 * 1174 * \param ftdmchan The channel where the token is 1175 * \param token The token string. If NULL, all tokens in the channel are cleared 1176 * 1177 * \retval FTDM_SUCCESS success 1178 * \retval FTDM_FAIL failure 1179 */ 1180 FT_DECLARE(ftdm_status_t) ftdm_channel_clear_token(ftdm_channel_t *ftdmchan, const char *token); 1181 1182 /*! 1183 * \brief Replace the given token with the new token 1184 * 1185 * \param ftdmchan The channel where the token is 1186 * \param old_token The token to replace 1187 * \param new_token The token to put in place 1188 */ 1189 FT_DECLARE(void) ftdm_channel_replace_token(ftdm_channel_t *ftdmchan, const char *old_token, const char *new_token); 1190 1191 /*! 1192 * \brief Add a new token to the channel 1193 * 1194 * \param ftdmchan The channel where the token will be added 1195 * \param token The token string to add 1196 * \param end if 0, the token will be added at the beginning of the token list, to the end otherwise 1197 * 1198 * \retval FTDM_SUCCESS success 1199 * \retval FTDM_FAIL failure 1200 */ 1201 FT_DECLARE(ftdm_status_t) ftdm_channel_add_token(ftdm_channel_t *ftdmchan, char *token, int end); 1202 1203 /*! 1204 * \brief Get the requested token 1205 * 1206 * \param ftdmchan The channel where the token is 1207 * \param tokenid The id of the token 1208 * 1209 * \retval The token character string 1210 * \retval NULL token not found 1211 */ 1212 FT_DECLARE(const char *) ftdm_channel_get_token(const ftdm_channel_t *ftdmchan, uint32_t tokenid); 1213 1214 /*! 1215 * \brief Get the token count 1216 * 1217 * \param ftdmchan The channel to get the token count from 1218 * 1219 * \retval The token count 1220 */ 1221 FT_DECLARE(uint32_t) ftdm_channel_get_token_count(const ftdm_channel_t *ftdmchan); 1222 1223 /*! 1224 * \brief Get the I/O read/write interval 1225 * 1226 * \param ftdmchan The channel to get the interval from 1227 * 1228 * \retval The interval in milliseconds 1229 */ 1230 FT_DECLARE(uint32_t) ftdm_channel_get_io_interval(const ftdm_channel_t *ftdmchan); 1231 1232 /*! 1233 * \brief Get the I/O read/write packet length per interval 1234 * 1235 * \param ftdmchan The channel to get the packet length from 1236 * 1237 * \retval The packet length interval in bytes 1238 */ 1239 FT_DECLARE(uint32_t) ftdm_channel_get_io_packet_len(const ftdm_channel_t *ftdmchan); 1240 1241 /*! 1242 * \brief Get the I/O read/write codec 1243 * 1244 * \param ftdmchan The channel to get the codec from 1245 * 1246 * \retval The codec type 1247 */ 1248 FT_DECLARE(ftdm_codec_t) ftdm_channel_get_codec(const ftdm_channel_t *ftdmchan); 1249 1250 /*! 1251 * \brief Get the last error string for the channel 1252 * 1253 * \deprecated This API will disappear in the future and not every 1254 * FreeTDM API set the last error value 1255 * 1256 * \param ftdmchan The channel to get the error from 1257 * 1258 * \retval The error string (not thread-safe, the string is per channel, not per thread) 1259 */ 1260 FT_DECLARE(const char *) ftdm_channel_get_last_error(const ftdm_channel_t *ftdmchan); 1261 1262 /*! 1263 * \brief Get the current alarm bitmask for the channel 1264 * 1265 * \param ftdmchan The channel to get the alarm bitmask from 1266 * \param alarmbits The alarm bitmask pointer to store the current alarms (you are responsible for allocation/deallocation) 1267 * 1268 * \retval FTDM_SUCCESS success 1269 * \retval FTDM_FAIL failure 1270 */ 1271 FT_DECLARE(ftdm_status_t) ftdm_channel_get_alarms(ftdm_channel_t *ftdmchan, ftdm_alarm_flag_t *alarmbits); 1272 1273 /*! 1274 * \brief Get the channel type 1275 * 1276 * \param ftdmchan The channel to get the type from 1277 * 1278 * \retval channel type (FXO, FXS, B-channel, D-channel, etc) 1279 */ 1280 FT_DECLARE(ftdm_chan_type_t) ftdm_channel_get_type(const ftdm_channel_t *ftdmchan); 1281 1282 /*! 1283 * \brief Dequeue DTMF from the given channel 1284 * \note To transmit DTMF use ftdm_channel_command with command FTDM_COMMAND_SEND_DTMF 1285 * 1286 * \param ftdmchan The channel to dequeue DTMF from 1287 * \param dtmf DTMF buffer to store the dtmf (you are responsible for its allocation and deallocation) 1288 * \param len The size of the provided DTMF buffer 1289 * 1290 * \retval The size of the dequeued DTMF (it might be zero if there is no DTMF in the queue) 1291 */ 1292 FT_DECLARE(ftdm_size_t) ftdm_channel_dequeue_dtmf(ftdm_channel_t *ftdmchan, char *dtmf, ftdm_size_t len); 1293 1294 /*! 1295 * \brief Flush the DTMF queue 1296 * 1297 * \param ftdmchan The channel to flush the dtmf queue of 1298 */ 1299 FT_DECLARE(void) ftdm_channel_flush_dtmf(ftdm_channel_t *ftdmchan); 1300 1301 /*! 1302 * \brief Wait for an event in the span 1303 * 1304 * \param span The span to wait events for 1305 * \param ms Milliseconds timeout 1306 * \param poll_events Array of events to poll for, for each channel on the span 1307 * 1308 * \retval FTDM_SUCCESS success (at least one event available) 1309 * \retval FTDM_TIMEOUT Timed out waiting for events 1310 * \retval FTDM_FAIL failure 1311 */ 1312 FT_DECLARE(ftdm_status_t) ftdm_span_poll_event(ftdm_span_t *span, uint32_t ms, short *poll_events); 1313 1314 /*! 1315 * \brief Find a span by its id 1316 * 1317 * \param id The span id 1318 * \param span Pointer to store the span if found 1319 * 1320 * \retval FTDM_SUCCESS success (span is valid) 1321 * \retval FTDM_FAIL failure (span is not valid) 1322 */ 1323 FT_DECLARE(ftdm_status_t) ftdm_span_find(uint32_t id, ftdm_span_t **span); 1324 1325 /*! 1326 * \brief Get the last error string for the given span 1327 * 1328 * \deprecated This API will disappear in the future and not every 1329 * FreeTDM API set the last error value 1330 * 1331 * \param span The span to get the last error from 1332 * 1333 * \retval character string for the last error 1334 */ 1335 FT_DECLARE(const char *) ftdm_span_get_last_error(const ftdm_span_t *span); 1336 1337 /*! 1338 * \brief Create a new span (not needed if you are using freetdm.conf) 1339 * 1340 * \param iotype The I/O interface type this span will use. 1341 * This depends on the available I/O modules 1342 * ftmod_wanpipe = "wanpipe" (Sangoma) 1343 * ftmod_zt = "zt" (DAHDI or Zaptel) 1344 * ftmod_pika "pika" (this one is most likely broken) 1345 * \param name Name for the span 1346 * \param span Pointer to store the create span 1347 * 1348 * \retval FTDM_SUCCESS success (the span was created) 1349 * \retval FTDM_FAIL failure (span was not created) 1350 */ 1351 FT_DECLARE(ftdm_status_t) ftdm_span_create(const char *iotype, const char *name, ftdm_span_t **span); 1352 1353 /*! 1354 * \brief Add a new channel to a span 1355 * 1356 * \param span Where to add the new channel 1357 * \param sockfd The socket device associated to the channel (ie: sangoma device, dahdi device etc) 1358 * \param type Channel type 1359 * \param chan Pointer to store the newly allocated channel 1360 * 1361 * \retval FTDM_SUCCESS success (the channel was created) 1362 * \retval FTDM_FAIL failure (span was not created) 1363 */ 1364 FT_DECLARE(ftdm_status_t) ftdm_span_add_channel(ftdm_span_t *span, ftdm_socket_t sockfd, ftdm_chan_type_t type, ftdm_channel_t **chan); 1365 1366 /*! \brief Add the channel to a hunt group */ 1367 FT_DECLARE(ftdm_status_t) ftdm_channel_add_to_group(const char* name, ftdm_channel_t* ftdmchan); 1368 1369 /*! \brief Remove the channel from a hunt group */ 1370 FT_DECLARE(ftdm_status_t) ftdm_channel_remove_from_group(ftdm_group_t* group, ftdm_channel_t* ftdmchan); 1371 1372 /*! 1373 * \brief Retrieves an event from the span 1374 * 1375 * \note 1376 * This function is non-reentrant and not thread-safe. 1377 * The event returned may be modified if the function is called again 1378 * from a different thread or even the same. It is recommended to 1379 * handle events from the same span in a single thread. 1380 * 1381 * \param ftdmchan The channel to retrieve the event from 1382 * \param event Pointer to store the pointer to the event 1383 * 1384 * \retval FTDM_SUCCESS success (at least one event available) 1385 * \retval FTDM_FAIL failure 1386 */ 1387 FT_DECLARE(ftdm_status_t) ftdm_channel_read_event(ftdm_channel_t *ftdmchan, ftdm_event_t **event); 1388 1389 /*! \brief Find a hunt group by id */ 1390 FT_DECLARE(ftdm_status_t) ftdm_group_find(uint32_t id, ftdm_group_t **group); 1391 1392 /*! \brief Find a hunt group by name */ 1393 FT_DECLARE(ftdm_status_t) ftdm_group_find_by_name(const char *name, ftdm_group_t **group); 1394 1395 /*! \brief Create a group with the given name */ 1396 FT_DECLARE(ftdm_status_t) ftdm_group_create(ftdm_group_t **group, const char *name); 1397 1398 /*! \brief Get the number of channels in use on a span */ 1399 FT_DECLARE(ftdm_status_t) ftdm_span_channel_use_count(ftdm_span_t *span, uint32_t *count); 1400 1401 /*! \brief Get the number of channels in use on a group */ 1402 FT_DECLARE(ftdm_status_t) ftdm_group_channel_use_count(ftdm_group_t *group, uint32_t *count); 1403 1404 /*! \brief Get the id of a group */ 1405 FT_DECLARE(uint32_t) ftdm_group_get_id(const ftdm_group_t *group); 1406 1407 /*! 1408 * \brief Open a channel specifying the span id and chan id (required before placing a call on the channel) 1409 * 1410 * \warning Try using ftdm_call_place instead if you plan to place a call after opening the channel 1411 * 1412 * \note You must call ftdm_channel_close() or ftdm_channel_call_hangup() to release the channel afterwards 1413 * Only use ftdm_channel_close if there is no call (incoming or outgoing) in the channel 1414 * 1415 * \param span_id The span id the channel belongs to 1416 * \param chan_id Logical channel id of the channel you want to open 1417 * \param ftdmchan Pointer to store the channel once is open 1418 * 1419 * \retval FTDM_SUCCESS success (the channel was found and is available) 1420 * \retval FTDM_FAIL failure (channel was not found or not available) 1421 */ 1422 FT_DECLARE(ftdm_status_t) ftdm_channel_open(uint32_t span_id, uint32_t chan_id, ftdm_channel_t **ftdmchan); 1423 1424 /*! 1425 * \brief Open a channel specifying the span id and physical chan id (required before placing a call on the channel) 1426 * 1427 * \warning Try using ftdm_call_place instead if you plan to place a call after opening the channel 1428 * 1429 * \note You must call ftdm_channel_close() or ftdm_channel_call_hangup() to release the channel afterwards 1430 * Only use ftdm_channel_close if there is no call (incoming or outgoing) in the channel 1431 * 1432 * \param span_id The span id the channel belongs to 1433 * \param chan_id Physical channel id of the channel you want to open 1434 * \param ftdmchan Pointer to store the channel once is open 1435 * 1436 * \retval FTDM_SUCCESS success (the channel was found and is available) 1437 * \retval FTDM_FAIL failure (channel was not found or not available) 1438 */ 1439 FT_DECLARE(ftdm_status_t) ftdm_channel_open_ph(uint32_t span_id, uint32_t chan_id, ftdm_channel_t **ftdmchan); 1440 1441 /*! 1442 * \brief Hunts and opens a channel specifying the span id only 1443 * 1444 * \warning Try using ftdm_call_place instead if you plan to place a call after opening the channel 1445 * 1446 * \note You must call ftdm_channel_close() or ftdm_channel_call_hangup() to release the channel afterwards 1447 * Only use ftdm_channel_close if there is no call (incoming or outgoing) in the channel 1448 * 1449 * \param span_id The span id to hunt for a channel 1450 * \param direction The hunting direction 1451 * \param caller_data The calling party information 1452 * \param ftdmchan The channel pointer to store the available channel 1453 * 1454 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1455 * \retval FTDM_FAIL failure (no suitable channel was found available) 1456 */ 1457 FT_DECLARE(ftdm_status_t) ftdm_channel_open_by_span(uint32_t span_id, ftdm_hunt_direction_t direction, ftdm_caller_data_t *caller_data, ftdm_channel_t **ftdmchan); 1458 1459 /*! 1460 * \brief Hunts and opens a channel specifying group id 1461 * 1462 * \warning Try using ftdm_call_place instead if you plan to place a call after opening the channel 1463 * 1464 * \note You must call ftdm_channel_close() or ftdm_channel_call_hangup() to release the channel afterwards 1465 * Only use ftdm_channel_close if there is no call (incoming or outgoing) in the channel 1466 * 1467 * \param group_id The group id to hunt for a channel 1468 * \param direction The hunting direction 1469 * \param caller_data The calling party information 1470 * \param ftdmchan The channel pointer to store the available channel 1471 * 1472 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1473 * \retval FTDM_FAIL failure (no suitable channel was found available) 1474 */ 1475 FT_DECLARE(ftdm_status_t) ftdm_channel_open_by_group(uint32_t group_id, ftdm_hunt_direction_t direction, ftdm_caller_data_t *caller_data, ftdm_channel_t **ftdmchan); 1476 1477 /*! 1478 * \brief Close a previously open channel 1479 * 1480 * \warning FreeTDM is more and more a signaling API rather than just a plane IO API, unless you are using 1481 * FreeTDM as a pure IO API without its signaling modules, you should not use this function 1482 * 1483 * \note If you placed a call in this channel use ftdm_channel_call_hangup(), you MUST NOT call this function, 1484 * the signaling stack will close the channel when the call is done. 1485 * 1486 * \param ftdmchan pointer to the channel to close 1487 * 1488 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1489 * \retval FTDM_FAIL failure (no suitable channel was found available) 1490 */ 1491 FT_DECLARE(ftdm_status_t) ftdm_channel_close(ftdm_channel_t **ftdmchan); 1492 1493 /*! 1494 * \brief Execute a command in a channel (same semantics as the ioctl() unix system call) 1495 * 1496 * \param ftdmchan The channel to execute the command 1497 * \param command The command to execute 1498 * \param arg The argument for the command 1499 * 1500 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1501 * \retval FTDM_FAIL failure (no suitable channel was found available) 1502 */ 1503 FT_DECLARE(ftdm_status_t) ftdm_channel_command(ftdm_channel_t *ftdmchan, ftdm_command_t command, void *arg); 1504 1505 /*! 1506 * \brief Wait for I/O events in a channel 1507 * 1508 * \param ftdmchan The channel to wait I/O for 1509 * \param flags The wait I/O flags 1510 * \param timeout The timeout in milliseconds 1511 * 1512 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1513 * \retval FTDM_FAIL failure (no suitable channel was found available) 1514 */ 1515 FT_DECLARE(ftdm_status_t) ftdm_channel_wait(ftdm_channel_t *ftdmchan, ftdm_wait_flag_t *flags, int32_t timeout); 1516 1517 /*! 1518 * \brief Read data from a channel 1519 * 1520 * \param ftdmchan The channel to read data from 1521 * \param data The pointer to the buffer to store the read data 1522 * \param datalen The size in bytes of the provided buffer 1523 * 1524 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1525 * \retval FTDM_FAIL failure (no suitable channel was found available) 1526 */ 1527 FT_DECLARE(ftdm_status_t) ftdm_channel_read(ftdm_channel_t *ftdmchan, void *data, ftdm_size_t *datalen); 1528 1529 /*! 1530 * \brief Write data to a channel 1531 * 1532 * \note The difference between data and datasize is subtle but important. 1533 * 1534 * datalen is a pointer to the size of the actual data that you want to write. This pointer 1535 * will be updated with the number of bytes actually written. 1536 * 1537 * datasize on the other hand is the size of the entire buffer provided in data, whether 1538 * all of that buffer is in use or not is a different matter. The difference becomes 1539 * important only if you are using FreeTDM doing transcoding, for example, providing 1540 * a ulaw frame of 160 bytes but where the I/O device accepts input in signed linear, 1541 * the data to write will be 320 bytes, therefore datasize is expected to be at least 1542 * 320 where datalen would be just 160. 1543 * 1544 * \param ftdmchan The channel to write data to 1545 * \param data The pointer to the buffer to write 1546 * \param datasize The maximum number of bytes in data that can be used (in case transcoding is necessary) 1547 * \param datalen The size of the actual data 1548 * 1549 * \retval FTDM_SUCCESS success (a suitable channel was found available) 1550 * \retval FTDM_FAIL failure (no suitable channel was found available) 1551 */ 1552 FT_DECLARE(ftdm_status_t) ftdm_channel_write(ftdm_channel_t *ftdmchan, void *data, ftdm_size_t datasize, ftdm_size_t *datalen); 1553 1554 /*! \brief Get a custom variable from the sigmsg 1555 * \note The variable pointer returned is only valid while the before the event is processed and it'll be destroyed once the event is processed. */ 1556 FT_DECLARE(const char *) ftdm_sigmsg_get_var(ftdm_sigmsg_t *sigmsg, const char *var_name); 1557 1558 /*! \brief Get an iterator to iterate over the sigmsg variables 1559 * \param sigmsg The message structure containing the variables 1560 * \param iter Optional iterator. You can reuse an old iterator (not previously freed) to avoid the extra allocation of a new iterator. 1561 * \note The iterator pointer returned is only valid while the channel is open and it'll be destroyed when the channel is closed. 1562 * This iterator is completely non-thread safe, if you are adding variables or removing variables while iterating 1563 * results are unpredictable 1564 */ 1565 FT_DECLARE(ftdm_iterator_t *) ftdm_sigmsg_get_var_iterator(const ftdm_sigmsg_t *sigmsg, ftdm_iterator_t *iter); 1566 1567 /*! \brief Get raw data from sigmsg 1568 * \param sigmsg The message structure containing the variables 1569 * \param data data will point to available data pointer if available 1570 * \param datalen datalen will be set to length of data available 1571 * \retval FTDM_SUCCESS data is available 1572 * \retval FTDM_FAIL no data available 1573 * \note data is only valid within the duration of the callback, to receive a data pointer that does not get 1574 * \note destroyed when callback returns, see ftdm_sigmsg_get_raw_data_detached 1575 */ 1576 FT_DECLARE(ftdm_status_t) ftdm_sigmsg_get_raw_data(ftdm_sigmsg_t *sigmsg, void **data, ftdm_size_t *datalen); 1577 1578 /*! \brief Get raw data from event 1579 * \param sigmsg The message structure containing the variables 1580 * \param data data will point to available data pointer if available 1581 * \param datalen datalen will be set to length of data available 1582 * \retval FTDM_SUCCESS data is available 1583 * \retval FTDM_FAIL no data available 1584 * \note Once this function returns, User owns data, and is responsible to free data using ftdm_safe_free(); 1585 */ 1586 FT_DECLARE(ftdm_status_t) ftdm_sigmsg_get_raw_data_detached(ftdm_sigmsg_t *sigmsg, void **data, ftdm_size_t *datalen); 1587 1588 /*! \brief Add a custom variable to the user message 1589 * \note This variables may be used by signaling modules to override signaling parameters 1590 * \todo Document which signaling variables are available 1591 * */ 1592 FT_DECLARE(ftdm_status_t) ftdm_usrmsg_add_var(ftdm_usrmsg_t *usrmsg, const char *var_name, const char *value); 1593 1594 /*! \brief Attach raw data to usrmsg 1595 * \param usrmsg The message structure containing the variables 1596 * \param data pointer to data 1597 * \param datalen datalen length of data 1598 * \retval FTDM_SUCCESS success, data was successfully saved 1599 * \retval FTDM_FAIL failed, event already had data attached to it. 1600 * \note data must have been allocated using ftdm_calloc, FreeTDM will free data once the usrmsg is processed. 1601 */ 1602 FT_DECLARE(ftdm_status_t) ftdm_usrmsg_set_raw_data(ftdm_usrmsg_t *usrmsg, void *data, ftdm_size_t datalen); 1603 1604 /*! \brief Get iterator current value (depends on the iterator type) 1605 * \note Channel iterators return a pointer to ftdm_channel_t 1606 * Span iterators return a pointer to ftdm_span_t 1607 * Variable iterators return a pointer to the variable name (not the variable value) 1608 */ 1609 FT_DECLARE(void *) ftdm_iterator_current(ftdm_iterator_t *iter); 1610 1611 /*! \brief Get variable name and value for the current iterator position */ 1612 FT_DECLARE(ftdm_status_t) ftdm_get_current_var(ftdm_iterator_t *iter, const char **var_name, const char **var_val); 1613 1614 /*! \brief Advance iterator */ 1615 FT_DECLARE(ftdm_iterator_t *) ftdm_iterator_next(ftdm_iterator_t *iter); 1616 1617 /*! \brief Free iterator 1618 * \note You must free an iterator after using it unless you plan to reuse it 1619 */ 1620 FT_DECLARE(ftdm_status_t) ftdm_iterator_free(ftdm_iterator_t *iter); 1621 1622 /*! \brief Get the span pointer associated to the channel */ 1623 FT_DECLARE(ftdm_span_t *) ftdm_channel_get_span(const ftdm_channel_t *ftdmchan); 1624 1625 /*! \brief Get the span pointer associated to the channel */ 1626 FT_DECLARE(uint32_t) ftdm_channel_get_span_id(const ftdm_channel_t *ftdmchan); 1627 1628 /*! \brief Get the physical span id associated to the channel */ 1629 FT_DECLARE(uint32_t) ftdm_channel_get_ph_span_id(const ftdm_channel_t *ftdmchan); 1630 1631 /*! \brief Get the span name associated to the channel */ 1632 FT_DECLARE(const char *) ftdm_channel_get_span_name(const ftdm_channel_t *ftdmchan); 1633 1634 /*! \brief Get the id associated to the channel */ 1635 FT_DECLARE(uint32_t) ftdm_channel_get_id(const ftdm_channel_t *ftdmchan); 1636 1637 /*! \brief Get the name associated to the channel */ 1638 FT_DECLARE(const char *) ftdm_channel_get_name(const ftdm_channel_t *ftdmchan); 1639 1640 /*! \brief Get the number associated to the channel */ 1641 FT_DECLARE(const char *) ftdm_channel_get_number(const ftdm_channel_t *ftdmchan); 1642 1643 /*! \brief Get the number physical id associated to the channel */ 1644 FT_DECLARE(uint32_t) ftdm_channel_get_ph_id(const ftdm_channel_t *ftdmchan); 1645 1646 /*! 1647 * \brief Configure span with a signaling type 1648 * 1649 * \deprecated use ftdm_configure_span_signaling instead 1650 * 1651 * \note This function does the same as ftdm_configure_span_signaling 1652 * 1653 * \param span The span to configure 1654 * \param type The signaling type ("boost", "isdn" and others, this depends on the available signaling modules) 1655 * \param sig_cb The callback that the signaling stack will use to notify about events 1656 * \param ... variable argument list with "var", value sequence, the variable and values are signaling type dependant 1657 * the last argument must be FTDM_TAG_END 1658 * 1659 * \retval FTDM_SUCCESS success 1660 * \retval FTDM_FAIL failure 1661 */ 1662 FT_DECLARE(ftdm_status_t) ftdm_configure_span(ftdm_span_t *span, const char *type, fio_signal_cb_t sig_cb, ...); 1663 #define FTDM_TAG_END NULL 1664 1665 1666 /*! 1667 * \brief Configure span with a signaling type 1668 * 1669 * \param span The span to configure 1670 * \param type The signaling type ("boost", "isdn" and others, this depends on the available signaling modules) 1671 * \param sig_cb The callback that the signaling stack will use to notify about events 1672 * \param parameters The array if signaling-specific parameters (the last member of the array MUST have its var member set to NULL, ie: .var = NULL) 1673 * 1674 * \retval FTDM_SUCCESS success 1675 * \retval FTDM_FAIL failure 1676 */ 1677 FT_DECLARE(ftdm_status_t) ftdm_configure_span_signaling(ftdm_span_t *span, const char *type, fio_signal_cb_t sig_cb, ftdm_conf_parameter_t *parameters); 1678 1679 /*! 1680 * \brief Register callback to listen for incoming events 1681 * \note This function should only be used when there is no signalling module 1682 * \param span The span to register to 1683 * \param sig_cb The callback that the signaling stack will use to notify about events 1684 * 1685 * \retval FTDM_SUCCESS success 1686 * \retval FTDM_FAIL failure 1687 */ 1688 FT_DECLARE(ftdm_status_t) ftdm_span_register_signal_cb(ftdm_span_t *span, fio_signal_cb_t sig_cb); 1689 1690 /*! 1691 * \brief Start the span signaling (must call ftdm_configure_span_signaling first) 1692 * 1693 * \note Even before this function returns you may receive signaling events! 1694 * Never block in the signaling callback since it might be called in a thread 1695 * that handles more than 1 call and therefore you would be blocking all the 1696 * calls handled by that thread! 1697 * 1698 * \param span The span to start 1699 * 1700 * \retval FTDM_SUCCESS success 1701 * \retval FTDM_FAIL failure 1702 */ 1703 FT_DECLARE(ftdm_status_t) ftdm_span_start(ftdm_span_t *span); 1704 1705 /*! 1706 * \brief Stop the span signaling (must call ftdm_span_start first) 1707 * \note certain signalings (boost signaling) does not support granular span start/stop 1708 * so it is recommended to always configure all spans and then starting them all and finally 1709 * stop them all (or call ftdm_global_destroy which takes care of stopping and destroying the spans at once). 1710 * 1711 * \param span The span to stop 1712 * 1713 * \retval FTDM_SUCCESS success 1714 * \retval FTDM_FAIL failure 1715 */ 1716 FT_DECLARE(ftdm_status_t) ftdm_span_stop(ftdm_span_t *span); 1717 1718 /*! 1719 * \brief Register a custom I/O interface with the FreeTDM core 1720 * 1721 * \param io_interface the Interface to register 1722 * 1723 * \retval FTDM_SUCCESS success 1724 * \retval FTDM_FAIL failure 1725 */ 1726 FT_DECLARE(ftdm_status_t) ftdm_global_add_io_interface(ftdm_io_interface_t *io_interface); 1727 1728 /** 1729 * Get I/O interface by name 1730 * 1731 * \param iotype Name of interface 1732 * \param autoload Try to load missing plugins 1733 * \retval I/O interface handle on success 1734 * \retval NULL on failure 1735 */ 1736 FT_DECLARE(ftdm_io_interface_t *) ftdm_global_get_io_interface(const char *iotype, ftdm_bool_t autoload); 1737 1738 /*! \brief Find a span by name */ 1739 FT_DECLARE(ftdm_status_t) ftdm_span_find_by_name(const char *name, ftdm_span_t **span); 1740 1741 /*! \brief Get the span id */ 1742 FT_DECLARE(uint32_t) ftdm_span_get_id(const ftdm_span_t *span); 1743 1744 /*! \brief Get the span name */ 1745 FT_DECLARE(const char *) ftdm_span_get_name(const ftdm_span_t *span); 1746 1747 /*! \brief Get iterator for the span channels 1748 * \param span The span containing the channels 1749 * \param iter Optional iterator. You can reuse an old iterator (not previously freed) to avoid the extra allocation of a new iterator. 1750 */ 1751 FT_DECLARE(ftdm_iterator_t *) ftdm_span_get_chan_iterator(const ftdm_span_t *span, ftdm_iterator_t *iter); 1752 1753 /*! \brief Get iterator for spans 1754 * \param iter Optional iterator. You can reuse an old iterator (not previously freed) to avoid the extra allocation of a new iterator. 1755 */ 1756 FT_DECLARE(ftdm_iterator_t *) ftdm_get_span_iterator(ftdm_iterator_t *iter); 1757 1758 /*! 1759 * \brief Execute a text command. The text command output will be returned and must be free'd 1760 * 1761 * \param cmd The command to execute 1762 * 1763 * \retval FTDM_SUCCESS success 1764 * \retval FTDM_FAIL failure 1765 */ 1766 FT_DECLARE(char *) ftdm_api_execute(const char *cmd); 1767 1768 /*! 1769 * \brief Create a configuration node 1770 * 1771 * \param name The name of the configuration node 1772 * \param node The node pointer to store the new node 1773 * \param parent The parent node if any, or NULL if no parent 1774 * 1775 * \return FTDM_SUCCESS success 1776 * \return FTDM_FAIL failure 1777 */ 1778 FT_DECLARE(ftdm_status_t) ftdm_conf_node_create(const char *name, ftdm_conf_node_t **node, ftdm_conf_node_t *parent); 1779 1780 /*! 1781 * \brief Adds a new parameter to the specified configuration node 1782 * 1783 * \param node The configuration node to add the param-val pair to 1784 * \param param The parameter name 1785 * \param val The parameter value 1786 * 1787 * \return FTDM_SUCCESS success 1788 * \return FTDM_FAIL failure 1789 */ 1790 FT_DECLARE(ftdm_status_t) ftdm_conf_node_add_param(ftdm_conf_node_t *node, const char *param, const char *val); 1791 1792 /*! 1793 * \brief Destroy the memory allocated for a configuration node (and all of its descendance) 1794 * 1795 * \param node The node to destroy 1796 * 1797 * \return FTDM_SUCCESS success 1798 * \return FTDM_FAIL failure 1799 */ 1800 FT_DECLARE(ftdm_status_t) ftdm_conf_node_destroy(ftdm_conf_node_t *node); 1801 1802 /*! 1803 * \brief Create and configure channels in the given span 1804 * 1805 * \param span The span container 1806 * \param str The channel range null terminated string. "1-10", "24" etc 1807 * \param chan_config The basic channel configuration for each channel within the range 1808 * \param configured Pointer where the number of channels configured will be stored 1809 * 1810 * \return FTDM_SUCCESS success 1811 * \return FTDM_FAIL failure 1812 */ 1813 FT_DECLARE(ftdm_status_t) ftdm_configure_span_channels(ftdm_span_t *span, const char *str, ftdm_channel_config_t *chan_config, unsigned *configured); 1814 1815 /*! 1816 * \brief Set the trunk type for a span 1817 * This must be called before configuring any channels within the span 1818 * 1819 * \param span The span 1820 * \param type The trunk type 1821 * 1822 */ 1823 FT_DECLARE(void) ftdm_span_set_trunk_type(ftdm_span_t *span, ftdm_trunk_type_t type); 1824 1825 /*! 1826 * \brief Get the trunk type for a span 1827 * 1828 * \param span The span 1829 * 1830 * \return The span trunk type 1831 */ 1832 FT_DECLARE(ftdm_trunk_type_t) ftdm_span_get_trunk_type(const ftdm_span_t *span); 1833 1834 /*! \brief For display debugging purposes you can display this string which describes the trunk type of a span */ 1835 FT_DECLARE(const char *) ftdm_span_get_trunk_type_str(const ftdm_span_t *span); 1836 1837 /*! 1838 * Set the trunk mode for a span 1839 * \note This must be called before configuring any channels within the span! 1840 * \param[in] span The span 1841 * \param[in] type The trunk mode 1842 */ 1843 FT_DECLARE(void) ftdm_span_set_trunk_mode(ftdm_span_t *span, ftdm_trunk_mode_t mode); 1844 1845 /*! 1846 * Get the trunk mode for a span 1847 * \param[in] span The span 1848 * \return Span trunk mode 1849 */ 1850 FT_DECLARE(ftdm_trunk_mode_t) ftdm_span_get_trunk_mode(const ftdm_span_t *span); 1851 1852 /*! 1853 * Get the trunk mode of a span in textual form 1854 * \param[in] span The span 1855 * \return Span mode name as a string 1856 */ 1857 FT_DECLARE(const char *) ftdm_span_get_trunk_mode_str(const ftdm_span_t *span); 1858 1859 /*! 1860 * \brief Return the channel identified by the provided logical id 1861 * 1862 * \param span The span where the channel belongs 1863 * \param chanid The logical channel id within the span 1864 * 1865 * \return The channel pointer if found, NULL otherwise 1866 */ 1867 FT_DECLARE(ftdm_channel_t *) ftdm_span_get_channel(const ftdm_span_t *span, uint32_t chanid); 1868 1869 /*! 1870 * \brief Return the channel identified by the provided physical id 1871 * 1872 * \param span The span where the channel belongs 1873 * \param chanid The physical channel id within the span 1874 * 1875 * \return The channel pointer if found, NULL otherwise 1876 */ 1877 FT_DECLARE(ftdm_channel_t *) ftdm_span_get_channel_ph(const ftdm_span_t *span, uint32_t chanid); 1878 1879 /*! \brief Return the channel count number for the given span */ 1880 FT_DECLARE(uint32_t) ftdm_span_get_chan_count(const ftdm_span_t *span); 1881 1882 /*! \brief Set the caller data for a channel. Be sure to call this before ftdm_channel_call_place() */ 1883 FT_DECLARE(ftdm_status_t) ftdm_channel_set_caller_data(ftdm_channel_t *ftdmchan, ftdm_caller_data_t *caller_data); 1884 1885 /*! \brief Get the caller data for a channel, typically you need this when receiving FTDM_SIGEVENT_START */ 1886 FT_DECLARE(ftdm_caller_data_t *) ftdm_channel_get_caller_data(ftdm_channel_t *channel); 1887 1888 /*! \brief Get current state of a channel */ 1889 FT_DECLARE(int) ftdm_channel_get_state(const ftdm_channel_t *ftdmchan); 1890 1891 /*! \brief Get last state of a channel */ 1892 FT_DECLARE(int) ftdm_channel_get_last_state(const ftdm_channel_t *ftdmchan); 1893 1894 /*! \brief For display debugging purposes you can display this string which describes the current channel internal state */ 1895 FT_DECLARE(const char *) ftdm_channel_get_state_str(const ftdm_channel_t *channel); 1896 1897 /*! \brief For display debugging purposes you can display this string which describes the last channel internal state */ 1898 FT_DECLARE(const char *) ftdm_channel_get_last_state_str(const ftdm_channel_t *channel); 1899 1900 /*! \brief For display debugging purposes you can display this string which describes the history of the channel 1901 * \param channel The channel to get the history from 1902 * \return History string for the channel. You must free the string with ftdm_free 1903 */ 1904 FT_DECLARE(char *) ftdm_channel_get_history_str(const ftdm_channel_t *channel); 1905 1906 /*! \brief Enable/disable blocking mode in the channels for this span */ 1907 FT_DECLARE(ftdm_status_t) ftdm_span_set_blocking_mode(const ftdm_span_t *span, ftdm_bool_t enabled); 1908 1909 /*! \brief Initialize the library */ 1910 FT_DECLARE(ftdm_status_t) ftdm_global_init(void); 1911 1912 /*! \brief Create spans and channels reading the freetdm.conf file */ 1913 FT_DECLARE(ftdm_status_t) ftdm_global_configuration(void); 1914 1915 /*! \brief Shutdown the library */ 1916 FT_DECLARE(ftdm_status_t) ftdm_global_destroy(void); 1917 1918 /*! \brief Set memory handler for the library */ 1919 FT_DECLARE(ftdm_status_t) ftdm_global_set_memory_handler(ftdm_memory_handler_t *handler); 1920 1921 /*! \brief Set the crash policy for the library */ 1922 FT_DECLARE(void) ftdm_global_set_crash_policy(ftdm_crash_policy_t policy); 1923 1924 /*! \brief Set the logger handler for the library */ 1925 FT_DECLARE(void) ftdm_global_set_logger(ftdm_logger_t logger); 1926 1927 /*! \brief Set the default logger level */ 1928 FT_DECLARE(void) ftdm_global_set_default_logger(int level); 1929 1930 /*! \brief Set the directory to look for modules */ 1931 FT_DECLARE(void) ftdm_global_set_mod_directory(const char *path); 1932 1933 /*! \brief Set the directory to look for configs */ 1934 FT_DECLARE(void) ftdm_global_set_config_directory(const char *path); 1935 1936 /*! \brief Check if the FTDM library is initialized and running */ 1937 FT_DECLARE(ftdm_bool_t) ftdm_running(void); 1938 1939 /** 1940 * Generate a stack trace and invoke a callback function for each entry 1941 * \param[in] callback Callback function, that is invoked for each stack symbol 1942 * \param[in] priv (User-)Private data passed to the callback 1943 * \retval 1944 * FTDM_SUCCESS On success 1945 * FTDM_NOTIMPL Backtraces are not available 1946 * FTDM_EINVAL Invalid arguments (callback was NULL) 1947 */ 1948 FT_DECLARE(ftdm_status_t) ftdm_backtrace_walk(void (* callback)(const int tid, const void *addr, const char *symbol, void *priv), void *priv); 1949 1950 /** 1951 * Convenience function to print a backtrace for a span. 1952 * \note The backtrace is generated with FTDM_LOG_DEBUG log level. 1953 * \param[in] span Span object 1954 * \retval 1955 * FTDM_SUCCESS On success 1956 * FTDM_NOTIMPL Backtraces are not available 1957 * FTDM_EINVAL Invalid arguments (e.g. span was NULL) 1958 */ 1959 FT_DECLARE(ftdm_status_t) ftdm_backtrace_span(ftdm_span_t *span); 1960 1961 /** 1962 * Convenience function to print a backtrace for a channel. 1963 * \note The backtrace is generated with FTDM_LOG_DEBUG log level. 1964 * \param[in] chan Channel object 1965 * \retval 1966 * FTDM_SUCCESS On success 1967 * FTDM_NOTIMPL Backtraces are not available 1968 * FTDM_EINVAL Invalid arguments (e.g. chan was NULL) 1969 */ 1970 FT_DECLARE(ftdm_status_t) ftdm_backtrace_chan(ftdm_channel_t *chan); 1971 1972 1973 FT_DECLARE_DATA extern ftdm_logger_t ftdm_log; 1974 1975 /*! \brief Basic transcoding function prototype */ 1976 #define FIO_CODEC_ARGS (void *data, ftdm_size_t max, ftdm_size_t *datalen) 1977 #define FIO_CODEC_FUNCTION(name) FT_DECLARE_NONSTD(ftdm_status_t) name FIO_CODEC_ARGS 1978 typedef ftdm_status_t (*fio_codec_t) FIO_CODEC_ARGS ; 1979 1980 /*! \brief Basic transcoding functions */ 1981 FIO_CODEC_FUNCTION(fio_slin2ulaw); 1982 FIO_CODEC_FUNCTION(fio_ulaw2slin); 1983 FIO_CODEC_FUNCTION(fio_slin2alaw); 1984 FIO_CODEC_FUNCTION(fio_alaw2slin); 1985 FIO_CODEC_FUNCTION(fio_ulaw2alaw); 1986 FIO_CODEC_FUNCTION(fio_alaw2ulaw); 1987 1988 #define FTDM_PRE __FILE__, __func__, __LINE__ 1989 #define FTDM_LOG_LEVEL_DEBUG 7 1990 #define FTDM_LOG_LEVEL_INFO 6 1991 #define FTDM_LOG_LEVEL_NOTICE 5 1992 #define FTDM_LOG_LEVEL_WARNING 4 1993 #define FTDM_LOG_LEVEL_ERROR 3 1994 #define FTDM_LOG_LEVEL_CRIT 2 1995 #define FTDM_LOG_LEVEL_ALERT 1 1996 #define FTDM_LOG_LEVEL_EMERG 0 1997 1998 /*! \brief Log levels */ 1999 #define FTDM_LOG_DEBUG FTDM_PRE, FTDM_LOG_LEVEL_DEBUG 2000 #define FTDM_LOG_INFO FTDM_PRE, FTDM_LOG_LEVEL_INFO 2001 #define FTDM_LOG_NOTICE FTDM_PRE, FTDM_LOG_LEVEL_NOTICE 2002 #define FTDM_LOG_WARNING FTDM_PRE, FTDM_LOG_LEVEL_WARNING 2003 #define FTDM_LOG_ERROR FTDM_PRE, FTDM_LOG_LEVEL_ERROR 2004 #define FTDM_LOG_CRIT FTDM_PRE, FTDM_LOG_LEVEL_CRIT 2005 #define FTDM_LOG_ALERT FTDM_PRE, FTDM_LOG_LEVEL_ALERT 2006 #define FTDM_LOG_EMERG FTDM_PRE, FTDM_LOG_LEVEL_EMERG 2007 2008 #ifdef __cplusplus 2009 } /* extern C */ 2010 #endif 2011 2012 #endif 2013 2014 /* For Emacs: 2015 * Local Variables: 2016 * mode:c 2017 * indent-tabs-mode:t 2018 * tab-width:4 2019 * c-basic-offset:4 2020 * End: 2021 * For VIM: 2022 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet: 2023 */ 2024