freetdm: initial changes to make FreeTDM APIs non-blocking

libs/freetdm/src/include/freetdm.h

@@ -349,11 +349,13 @@ typedef enum {
 	FTDM_SIGEVENT_FACILITY, /*!< In call facility event */
 	FTDM_SIGEVENT_TRACE, /*!<Interpreted trace event */
 	FTDM_SIGEVENT_TRACE_RAW, /*!<Raw trace event */
+	FTDM_SIGEVENT_INDICATION_COMPLETED, /*!< Last requested indication was completed */
 	FTDM_SIGEVENT_INVALID, /*!<Invalid */
 } ftdm_signal_event_t;
 #define SIGNAL_STRINGS "START", "STOP", "RELEASED", "UP", "FLASH", "PROCEED", "RINGING", "PROGRESS", \
 		"PROGRESS_MEDIA", "ALARM_TRAP", "ALARM_CLEAR", \
-		"COLLECTED_DIGIT", "ADD_CALL", "RESTART", "SIGSTATUS_CHANGED", "COLLISION", "FACILITY", "TRACE", "TRACE_RAW", "INVALID"
+		"COLLECTED_DIGIT", "ADD_CALL", "RESTART", "SIGSTATUS_CHANGED", "COLLISION", "FACILITY", \
+		"TRACE", "TRACE_RAW", "INDICATION_COMPLETED", "INVALID"
 
 /*! \brief Move from string to ftdm_signal_event_t and viceversa */
 FTDM_STR2ENUM_P(ftdm_str2ftdm_signal_event, ftdm_signal_event2str, ftdm_signal_event_t)
@@ -434,6 +436,31 @@ typedef struct {
 	char digits[FTDM_DIGITS_LIMIT];
 } ftdm_event_collected_t;
 
+/*! \brief FreeTDM supported indications.
+ * This is used during incoming calls when you want to request the signaling stack
+ * to notify about indications occurring locally. See ftdm_channel_call_indicate for more info */
+typedef enum {
+	FTDM_CHANNEL_INDICATE_RINGING,
+	FTDM_CHANNEL_INDICATE_PROCEED,
+	FTDM_CHANNEL_INDICATE_PROGRESS,
+	FTDM_CHANNEL_INDICATE_PROGRESS_MEDIA,
+	FTDM_CHANNEL_INDICATE_BUSY,
+	/* Using this indication is equivalent to call ftdm_channel_call_answer API */
+	FTDM_CHANNEL_INDICATE_ANSWER,
+	FTDM_CHANNEL_INDICATE_INVALID,
+} ftdm_channel_indication_t;
+#define INDICATION_STRINGS "RINGING", "PROCEED", "PROGRESS", "PROGRESS_MEDIA", "BUSY", "ANSWER", "INVALID"
+
+/*! \brief Move from string to ftdm_channel_indication_t and viceversa */
+FTDM_STR2ENUM_P(ftdm_str2channel_indication, ftdm_channel_indication2str, ftdm_channel_indication_t)
+
+typedef struct {
+	/* The indication that was completed */
+	ftdm_channel_indication_t indication;
+	/* Completion status of the indication */
+	ftdm_status_t status;
+} ftdm_event_indication_completed_t;
+
 /*! \brief Generic signaling message */
 struct ftdm_sigmsg {
 	ftdm_signal_event_t event_id; /*!< The type of message */
@@ -444,7 +471,8 @@ struct ftdm_sigmsg {
 	union {
 		ftdm_event_sigstatus_t sigstatus; /*!< valid if event_id is FTDM_SIGEVENT_SIGSTATUS_CHANGED */
 		ftdm_event_trace_t logevent;	/*!< valid if event_id is FTDM_SIGEVENT_TRACE or FTDM_SIGEVENT_TRACE_RAW */
-		ftdm_event_collected_t collected; /*!< valif if event_id is FTDM_SIGEVENT_COLLECTED_DIGIT */
+		ftdm_event_collected_t collected; /*!< valid if event_id is FTDM_SIGEVENT_COLLECTED_DIGIT */
+		ftdm_event_indication_completed_t indication_completed; /*!< valid if the event_id is FTDM_SIGEVENT_INDICATION_COMPLETED */
 	} ev_data;
 	struct {
 		uint8_t autofree; /*!< Whether the freetdm core will free it after message delivery */
@@ -708,17 +736,6 @@ typedef enum {
 	FTDM_CODEC_NONE = (1 << 30)
 } ftdm_codec_t;
 
-/*! \brief FreeTDM supported indications.
- * This is used during incoming calls when you want to request the signaling stack
- * to notify about indications occurring locally */
-typedef enum {
-	FTDM_CHANNEL_INDICATE_RINGING,
-	FTDM_CHANNEL_INDICATE_PROCEED,
-	FTDM_CHANNEL_INDICATE_PROGRESS,
-	FTDM_CHANNEL_INDICATE_PROGRESS_MEDIA,
-	FTDM_CHANNEL_INDICATE_BUSY,
-} ftdm_channel_indication_t;
-
 /*! \brief FreeTDM supported hardware alarms. */
 typedef enum {
 	FTDM_ALARM_NONE    = 0,
@@ -741,7 +758,12 @@ FT_DECLARE(ftdm_status_t) ftdm_global_set_queue_handler(ftdm_queue_handler_t *ha
  */
 FT_DECLARE(int) ftdm_channel_get_availability(ftdm_channel_t *ftdmchan);
 
-/*! \brief Answer call */
+/*! \brief Answer call. This can also be accomplished by ftdm_channel_call_indicate with FTDM_CHANNEL_INDICATE_ANSWER, in both
+ *         cases you will get a FTDM_SIGEVENT_INDICATION_COMPLETED when the indication is sent (or an error occurs) 
+ *  \note Although this API will result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered,
+ *        there is no guarantee of whether the event will arrive after or before your execution thread returns
+ *        from ftdm_channel_call_answer 
+ */
 #define ftdm_channel_call_answer(ftdmchan) _ftdm_channel_call_answer(__FILE__, __FUNCTION__, __LINE__, (ftdmchan))
 
 /*! \brief Answer call recording the source code point where the it was called (see ftdm_channel_call_answer for an easy to use macro) */
@@ -753,7 +775,13 @@ FT_DECLARE(ftdm_status_t) _ftdm_channel_call_answer(const char *file, const char
 /*! \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) */
 FT_DECLARE(ftdm_status_t) _ftdm_channel_call_place(const char *file, const char *func, int line, ftdm_channel_t *ftdmchan);
 
-/*! \brief Indicate a new condition in an incoming call */
+/*! \brief Indicate a new condition in an incoming call 
+ *  \note Every indication request will result in FTDM_SIGEVENT_INDICATION_COMPLETED event being delivered with
+ *        the proper status that will inform you if the request was successful or not.
+ *        Be aware there is no guarantee of whether the event will arrive after or before your execution thread returns
+ *        from ftdm_channel_call_indicate. This means you could get FTDM_SIGEVENT_INDICATION_COMPLETED even before
+ *        your execution thread returns from the ftdm_channel_call_indicate() API
+ */
 #define ftdm_channel_call_indicate(ftdmchan, indication) _ftdm_channel_call_indicate(__FILE__, __FUNCTION__, __LINE__, (ftdmchan), (indication))
 
 /*! \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) */
@@ -1494,9 +1522,14 @@ FT_DECLARE(const char *) ftdm_channel_get_last_state_str(const ftdm_channel_t *c
  */
 FT_DECLARE(char *) ftdm_channel_get_history_str(const ftdm_channel_t *channel);
 
-/*! \brief Initialize channel state for an outgoing call */
+/*! \brief Initialize channel state for an outgoing call
+ *  \note This API will eventually be deprecated, is only needed if you use boost signaling 
+ */
 FT_DECLARE(ftdm_status_t) ftdm_channel_init(ftdm_channel_t *ftdmchan);
 
+/*! \brief Enable/disable blocking mode in the channels for this span */
+FT_DECLARE(ftdm_status_t) ftdm_span_set_blocking_mode(const ftdm_span_t *span, ftdm_bool_t enabled);
+
 /*! \brief Initialize the library */
 FT_DECLARE(ftdm_status_t) ftdm_global_init(void);