From c8a998d73efd37f633f1036eb67233aff956143a Mon Sep 17 00:00:00 2001 From: Michael Collins Date: Mon, 8 Jun 2009 20:01:29 +0000 Subject: [PATCH] Add Doxygen comments. Thanks Francois. git-svn-id: http://svn.openzap.org/svn/openzap/trunk@741 a93c3328-9c30-0410-af19-c9cd2b2d52af --- .../src/ozmod/ozmod_analog/ozmod_analog.c | 61 ++++- .../ozmod/ozmod_analog_em/ozmod_analog_em.c | 50 +++- .../openzap/src/ozmod/ozmod_isdn/ozmod_isdn.c | 166 +++++++++++- .../src/ozmod/ozmod_libpri/ozmod_libpri.c | 239 ++++++++++++++++-- .../openzap/src/ozmod/ozmod_pika/ozmod_pika.c | 113 ++++++++- .../ozmod/ozmod_ss7_boost/ozmod_ss7_boost.c | 154 ++++++++++- .../src/ozmod/ozmod_wanpipe/ozmod_wanpipe.c | 138 +++++++++- libs/openzap/src/ozmod/ozmod_zt/ozmod_zt.c | 126 ++++++++- 8 files changed, 989 insertions(+), 58 deletions(-) diff --git a/libs/openzap/src/ozmod/ozmod_analog/ozmod_analog.c b/libs/openzap/src/ozmod/ozmod_analog/ozmod_analog.c index 2677085aa8..9dcd8d64fd 100644 --- a/libs/openzap/src/ozmod/ozmod_analog/ozmod_analog.c +++ b/libs/openzap/src/ozmod/ozmod_analog/ozmod_analog.c @@ -40,6 +40,13 @@ struct tm * localtime_r(const time_t *clock, struct tm *result); static void *zap_analog_channel_run(zap_thread_t *me, void *obj); +/** + * \brief Starts an FXO channel thread (outgoing call) + * \param zchan Channel to initiate call on + * \return Success or failure + * + * Initialises state, starts tone progress detection and runs the channel in a new a thread. + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_fxo_outgoing_call) { if (!zap_test_flag(zchan, ZAP_CHANNEL_OFFHOOK) && !zap_test_flag(zchan, ZAP_CHANNEL_INTHREAD)) { @@ -57,6 +64,13 @@ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_fxo_outgoing_call) return ZAP_FAIL; } +/** + * \brief Starts an FXS channel thread (outgoing call) + * \param zchan Channel to initiate call on + * \return Success or failure + * + * Indicates call waiting if channel is already in use, otherwise runs the channel in a new thread. + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_fxs_outgoing_call) { @@ -70,7 +84,11 @@ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_fxs_outgoing_call) return ZAP_SUCCESS; } - +/** + * \brief Starts an analog span thread (monitor) + * \param span Span to monitor + * \return Success or failure + */ static zap_status_t zap_analog_start(zap_span_t *span) { zap_analog_data_t *analog_data = span->signal_data; @@ -78,6 +96,13 @@ static zap_status_t zap_analog_start(zap_span_t *span) return zap_thread_create_detached(zap_analog_run, span); } +/** + * \brief Initialises an analog span from configuration variables + * \param span Span to configure + * \param sig_cb Callback function for event signals + * \param ap List of configuration variables + * \return Success or failure + */ static ZIO_SIG_CONFIGURE_FUNCTION(zap_analog_configure_span) //zap_status_t zap_analog_configure_span(zap_span_t *span, char *tonemap, uint32_t digit_timeout, uint32_t max_dialstr, zio_signal_cb_t sig_cb) { @@ -162,6 +187,12 @@ static ZIO_SIG_CONFIGURE_FUNCTION(zap_analog_configure_span) } +/** + * \brief Retrieves tone generation output to be sent + * \param ts Teletone generator + * \param map Tone map + * \return -1 on error, 0 on success + */ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map_t *map) { zap_buffer_t *dt_buffer = ts->user_data; @@ -175,6 +206,10 @@ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map return 0; } +/** + * \brief Sends caller id on an analog channel (FSK coded) + * \param zchan Channel to send caller id on + */ static void send_caller_id(zap_channel_t *zchan) { zap_fsk_data_state_t fsk_data; @@ -220,6 +255,11 @@ static void send_caller_id(zap_channel_t *zchan) zap_channel_send_fsk_data(zchan, &fsk_data, -14); } +/** + * \brief Main thread function for analog channel (outgoing call) + * \param me Current thread + * \param obj Channel to run in this thread + */ static void *zap_analog_channel_run(zap_thread_t *me, void *obj) { zap_channel_t *zchan = (zap_channel_t *) obj; @@ -729,6 +769,12 @@ static void *zap_analog_channel_run(zap_thread_t *me, void *obj) return NULL; } +/** + * \brief Processes openzap event + * \param span Span on which the event was fired + * \param event Event to be treated + * \return Success or failure + */ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *event) { zap_sigmsg_t sig; @@ -867,6 +913,11 @@ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *even return ZAP_SUCCESS; } +/** + * \brief Main thread function for analog span (monitor) + * \param me Current thread + * \param obj Span to run in this thread + */ static void *zap_analog_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -914,12 +965,18 @@ static void *zap_analog_run(zap_thread_t *me, void *obj) return NULL; } - +/** + * \brief Openzap analog signaling module initialisation + * \return Success + */ static ZIO_SIG_LOAD_FUNCTION(zap_analog_init) { return ZAP_SUCCESS; } +/** + * \brief Openzap analog signaling module definition + */ zap_module_t zap_module = { "analog", NULL, diff --git a/libs/openzap/src/ozmod/ozmod_analog_em/ozmod_analog_em.c b/libs/openzap/src/ozmod/ozmod_analog_em/ozmod_analog_em.c index 5e8649bf4c..72da381500 100644 --- a/libs/openzap/src/ozmod/ozmod_analog_em/ozmod_analog_em.c +++ b/libs/openzap/src/ozmod/ozmod_analog_em/ozmod_analog_em.c @@ -45,6 +45,13 @@ struct tm * localtime_r(const time_t *clock, struct tm *result); static void *zap_analog_em_channel_run(zap_thread_t *me, void *obj); +/** + * \brief Starts an EM channel thread (outgoing call) + * \param zchan Channel to initiate call on + * \return Success or failure + * + * Initialises state, starts tone progress detection and runs the channel in a new a thread. + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_em_outgoing_call) { if (!zap_test_flag(zchan, ZAP_CHANNEL_OFFHOOK) && !zap_test_flag(zchan, ZAP_CHANNEL_INTHREAD)) { @@ -63,7 +70,11 @@ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(analog_em_outgoing_call) return ZAP_FAIL; } - +/** + * \brief Starts an EM span thread (monitor) + * \param span Span to monitor + * \return Success or failure + */ static zap_status_t zap_analog_em_start(zap_span_t *span) { zap_analog_em_data_t *analog_data = span->signal_data; @@ -71,6 +82,13 @@ static zap_status_t zap_analog_em_start(zap_span_t *span) return zap_thread_create_detached(zap_analog_em_run, span); } +/** + * \brief Initialises an EM span from configuration variables + * \param span Span to configure + * \param sig_cb Callback function for event signals + * \param ap List of configuration variables + * \return Success or failure + */ static ZIO_SIG_CONFIGURE_FUNCTION(zap_analog_em_configure_span) //zap_status_t zap_analog_em_configure_span(zap_span_t *span, char *tonemap, uint32_t digit_timeout, uint32_t max_dialstr, zio_signal_cb_t sig_cb) { @@ -136,6 +154,12 @@ static ZIO_SIG_CONFIGURE_FUNCTION(zap_analog_em_configure_span) } +/** + * \brief Retrieves tone generation output to be sent + * \param ts Teletone generator + * \param map Tone map + * \return -1 on error, 0 on success + */ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map_t *map) { zap_buffer_t *dt_buffer = ts->user_data; @@ -149,6 +173,11 @@ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map return 0; } +/** + * \brief Main thread function for EM channel (outgoing call) + * \param me Current thread + * \param obj Channel to run in this thread + */ static void *zap_analog_em_channel_run(zap_thread_t *me, void *obj) { zap_channel_t *zchan = (zap_channel_t *) obj; @@ -532,6 +561,12 @@ static void *zap_analog_em_channel_run(zap_thread_t *me, void *obj) return NULL; } +/** + * \brief Processes EM events coming from zaptel/dahdi + * \param span Span on which the event was fired + * \param event Event to be treated + * \return Success or failure + */ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *event) { zap_sigmsg_t sig; @@ -587,6 +622,11 @@ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *even return ZAP_SUCCESS; } +/** + * \brief Main thread function for EM span (monitor) + * \param me Current thread + * \param obj Span to run in this thread + */ static void *zap_analog_em_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -634,12 +674,18 @@ static void *zap_analog_em_run(zap_thread_t *me, void *obj) return NULL; } - +/** + * \brief Openzap analog EM module initialisation + * \return Success + */ static ZIO_SIG_LOAD_FUNCTION(zap_analog_em_init) { return ZAP_SUCCESS; } +/** + * \brief Openzap analog EM module definition + */ zap_module_t zap_module = { "analog_em", NULL, diff --git a/libs/openzap/src/ozmod/ozmod_isdn/ozmod_isdn.c b/libs/openzap/src/ozmod/ozmod_isdn/ozmod_isdn.c index f1b4e93aae..213def357e 100644 --- a/libs/openzap/src/ozmod/ozmod_isdn/ozmod_isdn.c +++ b/libs/openzap/src/ozmod/ozmod_isdn/ozmod_isdn.c @@ -106,6 +106,10 @@ L3UCHAR sendFrame[SNAPLEN]= { 3,0,0,0 }; +/** + * \brief Opens a pcap file for capture + * \return Success or failure + */ static zap_status_t openPcapFile(void) { if(!pcaphandle) @@ -141,6 +145,10 @@ static zap_status_t openPcapFile(void) return ZAP_SUCCESS; } +/** + * \brief Closes a pcap file + * \return Success + */ static zap_status_t closePcapFile(void) { if (pcapfile) { @@ -162,6 +170,10 @@ static zap_status_t closePcapFile(void) return ZAP_SUCCESS; } +/** + * \brief Writes a Q931 packet to a pcap file + * \return Success or failure + */ static zap_status_t writeQ931PacketToPcap(L3UCHAR* q931buf, L3USHORT q931size, L3ULONG span_id, L3USHORT direction) { L3UCHAR *frame = NULL; @@ -242,6 +254,11 @@ static zap_status_t writeQ931PacketToPcap(L3UCHAR* q931buf, L3USHORT q931size, L } #endif + +/** + * \brief Unloads pcap IO + * \return Success or failure + */ static ZIO_IO_UNLOAD_FUNCTION(close_pcap) { #ifdef HAVE_LIBPCAP @@ -254,12 +271,20 @@ static ZIO_IO_UNLOAD_FUNCTION(close_pcap) /*Q931ToPcap functions DONE*/ /*-------------------------------------------------------------------------*/ - +/** + * \brief Gets current time + * \return Current time (in ms) + */ static L2ULONG zap_time_now(void) { return (L2ULONG)zap_current_time_in_ms(); } +/** + * \brief Initialises an ISDN channel (outgoing call) + * \param zchan Channel to initiate call on + * \return Success or failure + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(isdn_outgoing_call) { zap_status_t status = ZAP_SUCCESS; @@ -268,6 +293,15 @@ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(isdn_outgoing_call) return status; } +/** + * \brief Requests an ISDN channel on a span (outgoing call) + * \param span Span where to get a channel + * \param chan_id Specific channel to get (0 for any) + * \param direction Call direction (inbound, outbound) + * \param caller_data Caller information + * \param zchan Channel to initialise + * \return Success or failure + */ static ZIO_CHANNEL_REQUEST_FUNCTION(isdn_channel_request) { Q931mes_Generic *gen = (Q931mes_Generic *) caller_data->raw_data; @@ -489,12 +523,27 @@ static ZIO_CHANNEL_REQUEST_FUNCTION(isdn_channel_request) } +/** + * \brief Handler for Q931 error + * \param pvt Private structure (span?) + * \param id Error number + * \param p1 ?? + * \param p2 ?? + * \return 0 + */ static L3INT zap_isdn_931_err(void *pvt, L3INT id, L3INT p1, L3INT p2) { zap_log(ZAP_LOG_ERROR, "ERROR: [%s] [%d] [%d]\n", q931_error_to_name(id), p1, p2); return 0; } +/** + * \brief Handler for Q931 event message + * \param pvt Span to handle + * \param msg Message string + * \param mlen Message string length + * \return 0 + */ static L3INT zap_isdn_931_34(void *pvt, L2UCHAR *msg, L2INT mlen) { zap_span_t *span = (zap_span_t *) pvt; @@ -973,6 +1022,15 @@ static L3INT zap_isdn_931_34(void *pvt, L2UCHAR *msg, L2INT mlen) return 0; } +/** + * \brief Handler for Q921 read event + * \param pvt Span were message is coming from + * \param ind Q921 indication + * \param tei Terminal Endpoint Identifier + * \param msg Message string + * \param mlen Message string length + * \return 0 on success, 1 on failure + */ static int zap_isdn_921_23(void *pvt, Q921DLMsg_t ind, L2UCHAR tei, L2UCHAR *msg, L2INT mlen) { int ret, offset = (ind == Q921_DL_DATA) ? 4 : 3; @@ -1004,6 +1062,13 @@ static int zap_isdn_921_23(void *pvt, Q921DLMsg_t ind, L2UCHAR tei, L2UCHAR *msg return ((ret >= 0) ? 1 : 0); } +/** + * \brief Handler for Q921 write event + * \param pvt Span were message is coming from + * \param msg Message string + * \param mlen Message string length + * \return 0 on success, -1 on failure + */ static int zap_isdn_921_21(void *pvt, L2UCHAR *msg, L2INT mlen) { zap_span_t *span = (zap_span_t *) pvt; @@ -1022,6 +1087,10 @@ static int zap_isdn_921_21(void *pvt, L2UCHAR *msg, L2INT mlen) return zap_channel_write(isdn_data->dchan, msg, len, &len) == ZAP_SUCCESS ? 0 : -1; } +/** + * \brief Handler for channel state change + * \param zchan Channel to handle + */ static __inline__ void state_advance(zap_channel_t *zchan) { Q931mes_Generic *gen = (Q931mes_Generic *) zchan->caller_data.raw_data; @@ -1352,6 +1421,10 @@ static __inline__ void state_advance(zap_channel_t *zchan) } } +/** + * \brief Checks current state on a span + * \param span Span to check status on + */ static __inline__ void check_state(zap_span_t *span) { if (zap_test_flag(span, ZAP_SPAN_STATE_CHANGE)) { @@ -1369,7 +1442,12 @@ static __inline__ void check_state(zap_span_t *span) } } - +/** + * \brief Processes Openzap event on a span + * \param span Span to process event on + * \param event Event to process + * \return Success or failure + */ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *event) { zap_sigmsg_t sig; @@ -1422,7 +1500,10 @@ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *even return ZAP_SUCCESS; } - +/** + * \brief Checks for events on a span + * \param span Span to check for events + */ static __inline__ void check_events(zap_span_t *span) { zap_status_t status; @@ -1453,7 +1534,12 @@ static __inline__ void check_events(zap_span_t *span) } } - +/** + * \brief Retrieves tone generation output to be sent + * \param ts Teletone generator + * \param map Tone map + * \return -1 on error, 0 on success + */ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map_t *map) { zap_buffer_t *dt_buffer = ts->user_data; @@ -1467,6 +1553,11 @@ static int teletone_handler(teletone_generation_session_t *ts, teletone_tone_map return 0; } +/** + * \brief Main thread function for tone generation on a span + * \param me Current thread + * \param obj Span to generate tones on + */ static void *zap_isdn_tones_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -1658,6 +1749,11 @@ done: return NULL; } +/** + * \brief Main thread function for an ISDN span + * \param me Current thread + * \param obj Span to monitor + */ static void *zap_isdn_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -1745,6 +1841,10 @@ static void *zap_isdn_run(zap_thread_t *me, void *obj) return NULL; } +/** + * \brief Openzap ISDN signaling module initialisation + * \return Success + */ static ZIO_SIG_LOAD_FUNCTION(zap_isdn_init) { Q931Initialize(); @@ -1755,6 +1855,15 @@ static ZIO_SIG_LOAD_FUNCTION(zap_isdn_init) return ZAP_SUCCESS; } +/** + * \brief Receives a Q931 indication message + * \param pvt Span were message is coming from + * \param ind Q931 indication + * \param tei Terminal Endpoint Identifier + * \param msg Message string + * \param mlen Message string length + * \return 0 on success + */ static int q931_rx_32(void *pvt, Q921DLMsg_t ind, L3UCHAR tei, L3UCHAR *msg, L3INT mlen) { int offset = 4; @@ -1786,6 +1895,14 @@ static int q931_rx_32(void *pvt, Q921DLMsg_t ind, L3UCHAR tei, L3UCHAR *msg, L3I return Q921Rx32(pvt, ind, tei, msg, mlen); } +/** + * \brief Logs Q921 message + * \param pvt Span were message is coming from + * \param level Q921 log level + * \param msg Message string + * \param size Message string length + * \return 0 + */ static int zap_isdn_q921_log(void *pvt, Q921LogLevel_t level, char *msg, L2INT size) { zap_span_t *span = (zap_span_t *) pvt; @@ -1794,6 +1911,14 @@ static int zap_isdn_q921_log(void *pvt, Q921LogLevel_t level, char *msg, L2INT s return 0; } +/** + * \brief Logs Q931 message + * \param pvt Span were message is coming from + * \param level Q931 log level + * \param msg Message string + * \param size Message string length + * \return 0 + */ static L3INT zap_isdn_q931_log(void *pvt, Q931LogLevel_t level, char *msg, L3INT size) { zap_span_t *span = (zap_span_t *) pvt; @@ -1801,7 +1926,9 @@ static L3INT zap_isdn_q931_log(void *pvt, Q931LogLevel_t level, char *msg, L3INT zap_log("Span", "Q.931", span->span_id, (int)level, "%s", msg); return 0; } - +/** + * \brief ISDN state map + */ static zap_state_map_t isdn_state_map = { { { @@ -1914,6 +2041,13 @@ static zap_state_map_t isdn_state_map = { } }; +/** + * \brief Stops an ISDN span + * \param span Span to halt + * \return Success + * + * Sets a stop flag and waits for the threads to end + */ static zap_status_t zap_isdn_stop(zap_span_t *span) { zap_isdn_data_t *isdn_data = span->signal_data; @@ -1936,6 +2070,13 @@ static zap_status_t zap_isdn_stop(zap_span_t *span) } +/** + * \brief Starts an ISDN span + * \param span Span to halt + * \return Success or failure + * + * Launches a thread to monitor the span and a thread to generate tones on the span + */ static zap_status_t zap_isdn_start(zap_span_t *span) { zap_status_t ret; @@ -1958,6 +2099,11 @@ static zap_status_t zap_isdn_start(zap_span_t *span) return ret; } +/** + * \brief Parses an option string to flags + * \param in String to parse for configuration options + * \return Flags + */ static uint32_t parse_opts(const char *in) { uint32_t flags = 0; @@ -1981,6 +2127,13 @@ static uint32_t parse_opts(const char *in) return flags; } +/** + * \brief Initialises an ISDN span from configuration variables + * \param span Span to configure + * \param sig_cb Callback function for event signals + * \param ap List of configuration variables + * \return Success or failure + */ static ZIO_SIG_CONFIGURE_FUNCTION(zap_isdn_configure_span) { uint32_t i, x = 0; @@ -2191,6 +2344,9 @@ static ZIO_SIG_CONFIGURE_FUNCTION(zap_isdn_configure_span) return ZAP_SUCCESS; } +/** + * \brief Openzap ISDN signaling module definition + */ zap_module_t zap_module = { "isdn", NULL, diff --git a/libs/openzap/src/ozmod/ozmod_libpri/ozmod_libpri.c b/libs/openzap/src/ozmod/ozmod_libpri/ozmod_libpri.c index 013884da81..5b07494ef6 100644 --- a/libs/openzap/src/ozmod/ozmod_libpri/ozmod_libpri.c +++ b/libs/openzap/src/ozmod/ozmod_libpri/ozmod_libpri.c @@ -34,11 +34,20 @@ #include "openzap.h" #include "ozmod_libpri.h" +/** + * \brief Unloads libpri IO module + * \return Success + */ static ZIO_IO_UNLOAD_FUNCTION(zap_libpri_unload) { return ZAP_SUCCESS; } +/** + * \brief Starts a libpri channel (outgoing call) + * \param zchan Channel to initiate call on + * \return Success or failure + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(isdn_outgoing_call) { zap_status_t status = ZAP_SUCCESS; @@ -47,15 +56,32 @@ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(isdn_outgoing_call) return status; } +/** + * \brief Requests an libpri channel on a span (outgoing call) + * \param span Span where to get a channel (unused) + * \param chan_id Specific channel to get (0 for any) (unused) + * \param direction Call direction (unused) + * \param caller_data Caller information (unused) + * \param zchan Channel to initialise (unused) + * \return Failure + */ static ZIO_CHANNEL_REQUEST_FUNCTION(isdn_channel_request) { return ZAP_FAIL; - } #ifdef WIN32 +/** + * \brief Logs a libpri error + * \param s Error string + */ static void s_pri_error(char *s) #else +/** + * \brief Logs a libpri error + * \param pri libpri structure (unused) + * \param s Error string + */ static void s_pri_error(struct pri *pri, char *s) #endif { @@ -63,14 +89,28 @@ static void s_pri_error(struct pri *pri, char *s) } #ifdef WIN32 +/** + * \brief Logs a libpri message + * \param s Message string + */ static void s_pri_message(char *s) #else +/** + * \brief Logs a libpri message + * \param pri libpri structure (unused) + * \param s Message string + */ static void s_pri_message(struct pri *pri, char *s) #endif { zap_log(ZAP_LOG_DEBUG, "%s", s); } +/** + * \brief Parses an option string to flags + * \param in String to parse for configuration options + * \return Flags + */ static uint32_t parse_opts(const char *in) { uint32_t flags = 0; @@ -94,7 +134,11 @@ static uint32_t parse_opts(const char *in) return flags; } - +/** + * \brief Parses a debug string to flags + * \param in Debug string to parse for + * \return Flags + */ static int parse_debug(const char *in) { int flags = 0; @@ -154,6 +198,12 @@ static zap_io_interface_t zap_libpri_interface; static zap_status_t zap_libpri_start(zap_span_t *span); +/** + * \brief API function to kill or debug a libpri span + * \param stream API stream handler + * \param data String containing argurments + * \return Flags + */ static ZIO_API_FUNCTION(zap_libpri_api) { char *mycmd = NULL, *argv[10] = { 0 }; @@ -218,7 +268,11 @@ static ZIO_API_FUNCTION(zap_libpri_api) return ZAP_SUCCESS; } - +/** + * \brief Loads libpri IO module + * \param zio Openzap IO interface + * \return Success + */ static ZIO_IO_LOAD_FUNCTION(zap_libpri_io_init) { assert(zio != NULL); @@ -232,6 +286,11 @@ static ZIO_IO_LOAD_FUNCTION(zap_libpri_io_init) return ZAP_SUCCESS; } +/** + * \brief Loads libpri signaling module + * \param zio Openzap IO interface + * \return Success + */ static ZIO_SIG_LOAD_FUNCTION(zap_libpri_init) { pri_set_error(s_pri_error); @@ -239,7 +298,9 @@ static ZIO_SIG_LOAD_FUNCTION(zap_libpri_init) return ZAP_SUCCESS; } - +/** + * \brief libpri state map + */ static zap_state_map_t isdn_state_map = { { { @@ -352,10 +413,10 @@ static zap_state_map_t isdn_state_map = { } }; - - - - +/** + * \brief Handler for channel state change + * \param zchan Channel to handle + */ static __inline__ void state_advance(zap_channel_t *zchan) { //Q931mes_Generic *gen = (Q931mes_Generic *) zchan->caller_data.raw_data; @@ -531,6 +592,10 @@ static __inline__ void state_advance(zap_channel_t *zchan) return; } +/** + * \brief Checks current state on a span + * \param span Span to check status on + */ static __inline__ void check_state(zap_span_t *span) { if (zap_test_flag(span, ZAP_SPAN_STATE_CHANGE)) { @@ -548,8 +613,13 @@ static __inline__ void check_state(zap_span_t *span) } } - - +/** + * \brief Handler for libpri information event (incoming call?) + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_info(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { @@ -561,6 +631,13 @@ static int on_info(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event return 0; } +/** + * \brief Handler for libpri hangup event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_hangup(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -583,6 +660,13 @@ static int on_hangup(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_even return 0; } +/** + * \brief Handler for libpri answer event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_answer(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -601,7 +685,13 @@ static int on_answer(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_even return 0; } - +/** + * \brief Handler for libpri proceed event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_proceed(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -620,7 +710,13 @@ static int on_proceed(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_eve return 0; } - +/** + * \brief Handler for libpri ringing event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_ringing(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -639,7 +735,13 @@ static int on_ringing(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_eve return 0; } - +/** + * \brief Handler for libpri ring event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 on success + */ static int on_ring(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -691,7 +793,12 @@ static int on_ring(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event return ret; } - +/** + * \brief Processes openzap event + * \param span Span on which the event was fired + * \param event Event to be treated + * \return Success or failure + */ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *event) { zap_sigmsg_t sig; @@ -744,8 +851,10 @@ static __inline__ zap_status_t process_event(zap_span_t *span, zap_event_t *even return ZAP_SUCCESS; } - - +/** + * \brief Checks for events on a span + * \param span Span to check for events + */ static __inline__ void check_events(zap_span_t *span) { zap_status_t status; @@ -776,6 +885,11 @@ static __inline__ void check_events(zap_span_t *span) } } +/** + * \brief Checks flags on a pri span + * \param spri Pri wrapper structure (libpri, span, dchan) + * \return 0 on success, -1 on error + */ static int check_flags(lpwrap_pri_t *spri) { zap_span_t *span = spri->private_info; @@ -791,6 +905,13 @@ static int check_flags(lpwrap_pri_t *spri) return 0; } +/** + * \brief Handler for libpri restart event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_restart(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { zap_span_t *span = spri->private_info; @@ -813,6 +934,13 @@ static int on_restart(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_eve return 0; } +/** + * \brief Handler for libpri dchan up event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_dchan_up(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { @@ -824,6 +952,13 @@ static int on_dchan_up(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_ev return 0; } +/** + * \brief Handler for libpri dchan down event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_dchan_down(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { @@ -835,6 +970,13 @@ static int on_dchan_down(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_ return 0; } +/** + * \brief Handler for any libpri event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_anything(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { @@ -842,8 +984,13 @@ static int on_anything(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_ev return 0; } - - +/** + * \brief Handler for libpri io fail event + * \param spri Pri wrapper structure (libpri, span, dchan) + * \param event_type Event type (unused) + * \param pevent Event + * \return 0 + */ static int on_io_fail(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_event *pevent) { @@ -851,7 +998,11 @@ static int on_io_fail(lpwrap_pri_t *spri, lpwrap_pri_event_t event_type, pri_eve return 0; } - +/** + * \brief Main thread function for libpri span (monitor) + * \param me Current thread + * \param obj Span to run in this thread + */ static void *zap_libpri_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -939,7 +1090,13 @@ static void *zap_libpri_run(zap_thread_t *me, void *obj) return NULL; } - +/** + * \brief Stops a libpri span + * \param span Span to halt + * \return Success + * + * Sets a stop flag and waits for the thread to end + */ static zap_status_t zap_libpri_stop(zap_span_t *span) { zap_libpri_data_t *isdn_data = span->signal_data; @@ -959,6 +1116,13 @@ static zap_status_t zap_libpri_stop(zap_span_t *span) return ZAP_SUCCESS; } +/** + * \brief Starts a libpri span + * \param span Span to halt + * \return Success or failure + * + * Launches a thread to monitor the span + */ static zap_status_t zap_libpri_start(zap_span_t *span) { zap_status_t ret; @@ -981,7 +1145,11 @@ static zap_status_t zap_libpri_start(zap_span_t *span) return ret; } - +/** + * \brief Converts a node string to node value + * \param node Node string to convert + * \return -1 on failure, node value on success + */ static int str2node(char *node) { if (!strcasecmp(node, "cpe") || !strcasecmp(node, "user")) @@ -991,6 +1159,11 @@ static int str2node(char *node) return -1; } +/** + * \brief Converts a switch string to switch value + * \param swtype Swtype string to convert + * \return Switch value + */ static int str2switch(char *swtype) { if (!strcasecmp(swtype, "ni1")) @@ -1012,7 +1185,11 @@ static int str2switch(char *swtype) return PRI_SWITCH_DMS100; } - +/** + * \brief Converts a L1 string to L1 value + * \param l1 L1 string to convert + * \return L1 value + */ static int str2l1(char *l1) { if (!strcasecmp(l1, "alaw")) @@ -1021,6 +1198,11 @@ static int str2l1(char *l1) return PRI_LAYER_1_ULAW; } +/** + * \brief Converts a DP string to DP value + * \param dp DP string to convert + * \return DP value + */ static int str2dp(char *dp) { if (!strcasecmp(dp, "international")) @@ -1037,6 +1219,13 @@ static int str2dp(char *dp) return PRI_UNKNOWN; } +/** + * \brief Initialises a libpri span from configuration variables + * \param span Span to configure + * \param sig_cb Callback function for event signals + * \param ap List of configuration variables + * \return Success or failure + */ static ZIO_SIG_CONFIGURE_FUNCTION(zap_libpri_configure_span) { uint32_t i, x = 0; @@ -1146,6 +1335,9 @@ static ZIO_SIG_CONFIGURE_FUNCTION(zap_libpri_configure_span) return ZAP_SUCCESS; } +/** + * \brief Openzap libpri signaling and IO module definition + */ zap_module_t zap_module = { "libpri", zap_libpri_io_init, @@ -1156,9 +1348,6 @@ zap_module_t zap_module = { }; - - - /* For Emacs: * Local Variables: * mode:c diff --git a/libs/openzap/src/ozmod/ozmod_pika/ozmod_pika.c b/libs/openzap/src/ozmod/ozmod_pika/ozmod_pika.c index 5de8ac3974..26f72d7f7c 100644 --- a/libs/openzap/src/ozmod/ozmod_pika/ozmod_pika.c +++ b/libs/openzap/src/ozmod/ozmod_pika/ozmod_pika.c @@ -147,6 +147,14 @@ static const char *pika_board_type_string(PK_UINT type) return "unknown"; } +/** + * \brief Process configuration variable for a pika profile + * \param category Pika profile name + * \param var Variable name + * \param val Variable value + * \param lineno Line number from configuration file (unused) + * \return Success + */ static ZIO_CONFIGURE_FUNCTION(pika_configure) { pika_channel_profile_t *profile = NULL; @@ -255,6 +263,10 @@ static ZIO_CONFIGURE_FUNCTION(pika_configure) return ZAP_SUCCESS; } +/** + * \brief Pika event handler + * \param event Pika event + */ PK_VOID PK_CALLBACK media_out_callback(PKH_TPikaEvent *event) { PK_STATUS pk_status; @@ -296,7 +308,19 @@ PK_VOID PK_CALLBACK media_out_callback(PKH_TPikaEvent *event) } - +/** + * \brief Initialises a range of pika channels + * \param span Openzap span + * \param boardno Pika board number + * \param spanno Pika span number + * \param start Initial pika channel number + * \param end Final pika channel number + * \param type Openzap channel type + * \param name Openzap span name + * \param number Openzap span number + * \param profile Pika channel profile + * \return number of spans configured + */ static unsigned pika_open_range(zap_span_t *span, unsigned boardno, unsigned spanno, unsigned start, unsigned end, zap_chan_type_t type, char *name, char *number, pika_channel_profile_t *profile) { @@ -562,6 +586,15 @@ static unsigned pika_open_range(zap_span_t *span, unsigned boardno, unsigned spa return configured; } +/** + * \brief Initialises an openzap pika span from a configuration string + * \param span Openzap span + * \param str Configuration string + * \param type Openzap span type + * \param name Openzap span name + * \param number Openzap span number + * \return Success or failure + */ static ZIO_CONFIGURE_SPAN_FUNCTION(pika_configure_span) { int items, i; @@ -645,6 +678,11 @@ static ZIO_CONFIGURE_SPAN_FUNCTION(pika_configure_span) return configured; } +/** + * \brief Opens Pika channel + * \param zchan Channel to open + * \return Success or failure + */ static ZIO_OPEN_FUNCTION(pika_open) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -663,11 +701,23 @@ static ZIO_OPEN_FUNCTION(pika_open) return ZAP_SUCCESS; } +/** + * \brief Closes Pika channel + * \param zchan Channel to close + * \return Success + */ static ZIO_CLOSE_FUNCTION(pika_close) { return ZAP_SUCCESS; } +/** + * \brief Waits for an event on a Pika channel + * \param zchan Channel to open + * \param flags Type of event to wait for + * \param to Time to wait (in ms) + * \return Success, failure or timeout + */ static ZIO_WAIT_FUNCTION(pika_wait) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -700,6 +750,13 @@ static ZIO_WAIT_FUNCTION(pika_wait) return ZAP_SUCCESS; } +/** + * \brief Reads data from a Pika channel + * \param zchan Channel to read from + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success or failure + */ static ZIO_READ_FUNCTION(pika_read) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -734,6 +791,13 @@ static ZIO_READ_FUNCTION(pika_read) return ZAP_FAIL; } +/** + * \brief Writes data to a Pika channel + * \param zchan Channel to write to + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success or failure + */ static ZIO_WRITE_FUNCTION(pika_write) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -753,6 +817,13 @@ static ZIO_WRITE_FUNCTION(pika_write) return ZAP_FAIL; } +/** + * \brief Executes an Openzap command on a Pika channel + * \param zchan Channel to execute command on + * \param command Openzap command to execute + * \param obj Object (unused) + * \return Success or failure + */ static ZIO_COMMAND_FUNCTION(pika_command) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -882,6 +953,12 @@ static ZIO_COMMAND_FUNCTION(pika_command) return status; } +/** + * \brief Checks for events on a Pika span + * \param span Span to check for events + * \param ms Time to wait for event + * \return Success if event is waiting or failure if not + */ static ZIO_SPAN_POLL_EVENT_FUNCTION(pika_poll_event) { pika_span_data_t *span_data = (pika_span_data_t *) span->mod_data; @@ -984,6 +1061,12 @@ static ZIO_SPAN_POLL_EVENT_FUNCTION(pika_poll_event) return ZAP_FAIL; } +/** + * \brief Retrieves an event from a Pika span + * \param span Span to retrieve event from + * \param event Openzap event to return + * \return Success or failure + */ static ZIO_SPAN_NEXT_EVENT_FUNCTION(pika_next_event) { uint32_t i, event_id = 0; @@ -1122,6 +1205,11 @@ static ZIO_SPAN_NEXT_EVENT_FUNCTION(pika_next_event) return ZAP_FAIL; } +/** + * \brief Destroys a Pika Span + * \param span Span to destroy + * \return Success + */ static ZIO_SPAN_DESTROY_FUNCTION(pika_span_destroy) { pika_span_data_t *span_data = (pika_span_data_t *) span->mod_data; @@ -1134,6 +1222,11 @@ static ZIO_SPAN_DESTROY_FUNCTION(pika_span_destroy) return ZAP_SUCCESS; } +/** + * \brief Destroys a Pika Channel + * \param zchan Channel to destroy + * \return Success or failure + */ static ZIO_CHANNEL_DESTROY_FUNCTION(pika_channel_destroy) { pika_chan_data_t *chan_data = (pika_chan_data_t *) zchan->mod_data; @@ -1178,6 +1271,11 @@ static ZIO_CHANNEL_DESTROY_FUNCTION(pika_channel_destroy) return ZAP_SUCCESS; } +/** + * \brief Gets alarms from a Pika Channel (does nothing) + * \param zchan Channel to get alarms from + * \return Failure + */ static ZIO_GET_ALARMS_FUNCTION(pika_get_alarms) { return ZAP_FAIL; @@ -1185,6 +1283,11 @@ static ZIO_GET_ALARMS_FUNCTION(pika_get_alarms) static zap_io_interface_t pika_interface; +/** + * \brief Loads Pika IO module + * \param zio Openzap IO interface + * \return Success or failure + */ static ZIO_IO_LOAD_FUNCTION(pika_init) { @@ -1319,7 +1422,10 @@ static ZIO_IO_LOAD_FUNCTION(pika_init) return ZAP_SUCCESS; } - +/** + * \brief Unloads Pika IO module + * \return Success + */ static ZIO_IO_UNLOAD_FUNCTION(pika_destroy) { uint32_t x; @@ -1346,6 +1452,9 @@ static ZIO_IO_UNLOAD_FUNCTION(pika_destroy) return ZAP_SUCCESS; } +/** + * \brief Pika IO module definition + */ EX_DECLARE_DATA zap_module_t zap_module = { "pika", pika_init, diff --git a/libs/openzap/src/ozmod/ozmod_ss7_boost/ozmod_ss7_boost.c b/libs/openzap/src/ozmod/ozmod_ss7_boost/ozmod_ss7_boost.c index 22ae8e2cbf..469f5fe237 100644 --- a/libs/openzap/src/ozmod/ozmod_ss7_boost/ozmod_ss7_boost.c +++ b/libs/openzap/src/ozmod/ozmod_ss7_boost/ozmod_ss7_boost.c @@ -38,6 +38,9 @@ #include #endif +/** + * \brief Strange flag + */ typedef enum { SFLAG_FREE_REQ_ID = (1 << 0), SFLAG_SENT_FINAL_RESPONSE = (1 << 1) @@ -45,6 +48,9 @@ typedef enum { typedef uint16_t ss7_boost_request_id_t; +/** + * \brief SS7 boost request status + */ typedef enum { BST_FREE, BST_WAITING, @@ -52,6 +58,9 @@ typedef enum { BST_FAIL } ss7_boost_request_status_t; +/** + * \brief SS7 boost request structure + */ typedef struct { ss7_boost_request_status_t status; ss7bc_short_event_t event; @@ -73,6 +82,14 @@ static zap_mutex_t *signal_mutex = NULL; static uint8_t req_map[MAX_REQ_ID+1] = { 0 }; static uint8_t nack_map[MAX_REQ_ID+1] = { 0 }; +/** + * \brief Releases span and channel from setup grid + * \param span Span number + * \param chan Channel number + * \param func Calling function + * \param line Line number on request + * \return NULL if not found, channel otherwise + */ static void __release_request_id_span_chan(int span, int chan, const char *func, int line) { int id; @@ -87,6 +104,12 @@ static void __release_request_id_span_chan(int span, int chan, const char *func, } #define release_request_id_span_chan(s, c) __release_request_id_span_chan(s, c, __FUNCTION__, __LINE__) +/** + * \brief Releases request ID + * \param func Calling function + * \param line Line number on request + * \return NULL if not found, channel otherwise + */ static void __release_request_id(ss7_boost_request_id_t r, const char *func, int line) { assert(r <= MAX_REQ_ID); @@ -98,6 +121,12 @@ static void __release_request_id(ss7_boost_request_id_t r, const char *func, int static ss7_boost_request_id_t last_req = 0; +/** + * \brief Gets the first available tank request ID + * \param func Calling function + * \param line Line number on request + * \return 0 on failure, request ID on success + */ static ss7_boost_request_id_t __next_request_id(const char *func, int line) { ss7_boost_request_id_t r = 0, i = 0; @@ -136,6 +165,13 @@ static ss7_boost_request_id_t __next_request_id(const char *func, int line) } #define next_request_id() __next_request_id(__FUNCTION__, __LINE__) +/** + * \brief Finds the channel that triggered an event + * \param span Span where to search the channel + * \param event SS7 event + * \param force Do not wait for the channel to be available if in use + * \return NULL if not found, channel otherwise + */ static zap_channel_t *find_zchan(zap_span_t *span, ss7bc_short_event_t *event, int force) { int i; @@ -185,6 +221,15 @@ static zap_channel_t *find_zchan(zap_span_t *span, ss7bc_short_event_t *event, i return zchan; } +/** + * \brief Requests an ss7 boost channel on a span (outgoing call) + * \param span Span where to get a channel + * \param chan_id Specific channel to get (0 for any) + * \param direction Call direction + * \param caller_data Caller information + * \param zchan Channel to initialise + * \return Success or failure + */ static ZIO_CHANNEL_REQUEST_FUNCTION(ss7_boost_channel_request) { zap_ss7_boost_data_t *ss7_boost_data = span->signal_data; @@ -305,12 +350,22 @@ static ZIO_CHANNEL_REQUEST_FUNCTION(ss7_boost_channel_request) return status; } +/** + * \brief Starts an ss7 boost channel (outgoing call) + * \param zchan Channel to initiate call on + * \return Success + */ static ZIO_CHANNEL_OUTGOING_CALL_FUNCTION(ss7_boost_outgoing_call) { zap_status_t status = ZAP_SUCCESS; return status; } +/** + * \brief Handler for call start ack event + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_start_ack(ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_channel_t *zchan; @@ -354,6 +409,12 @@ static void handle_call_start_ack(ss7bc_connection_t *mcon, ss7bc_short_event_t } +/** + * \brief Handler for call done event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_done(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_channel_t *zchan; @@ -384,6 +445,12 @@ static void handle_call_done(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_s release_request_id_span_chan(event->span, event->chan); } +/** + * \brief Handler for call start nack event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_start_nack(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_channel_t *zchan; @@ -428,11 +495,14 @@ static void handle_call_start_nack(zap_span_t *span, ss7bc_connection_t *mcon, s 0, SIGBOOST_EVENT_CALL_START_NACK_ACK, 0); - - - } +/** + * \brief Handler for call stop event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_stop(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_channel_t *zchan; @@ -472,6 +542,12 @@ static void handle_call_stop(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_s release_request_id_span_chan(event->span, event->chan); } +/** + * \brief Handler for call answer event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_answer(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_channel_t *zchan; @@ -499,6 +575,12 @@ static void handle_call_answer(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc } } +/** + * \brief Handler for call start event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_call_start(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_event_t *event) { zap_channel_t *zchan; @@ -538,7 +620,11 @@ static void handle_call_start(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_ } - +/** + * \brief Handler for heartbeat event + * \param mcon ss7 boost connection + * \param event Event to handle + */ static void handle_heartbeat(ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { int err; @@ -554,12 +640,23 @@ static void handle_heartbeat(ss7bc_connection_t *mcon, ss7bc_short_event_t *even return; } +/** + * \brief Handler for restart ack event + * \param mcon ss7 boost connection + * \param span Span where event was fired + * \param event Event to handle + */ static void handle_restart_ack(ss7bc_connection_t *mcon, zap_span_t *span, ss7bc_short_event_t *event) { zap_log(ZAP_LOG_DEBUG, "RECV RESTART ACK\n"); } - +/** + * \brief Handler for restart event + * \param mcon ss7 boost connection + * \param span Span where event was fired + * \param event Event to handle + */ static void handle_restart(ss7bc_connection_t *mcon, zap_span_t *span, ss7bc_short_event_t *event) { zap_ss7_boost_data_t *ss7_boost_data = span->signal_data; @@ -572,6 +669,12 @@ static void handle_restart(ss7bc_connection_t *mcon, zap_span_t *span, ss7bc_sho mcon->hb_elapsed = 0; } +/** + * \brief Handler for incoming digit event + * \param mcon ss7 boost connection + * \param span Span where event was fired + * \param event Event to handle + */ static void handle_incoming_digit(ss7bc_connection_t *mcon, zap_span_t *span, ss7bc_event_t *event) { zap_channel_t *zchan = NULL; @@ -601,6 +704,12 @@ static void handle_incoming_digit(ss7bc_connection_t *mcon, zap_span_t *span, ss return; } +/** + * \brief Handler for ss7 boost event + * \param span Span where event was fired + * \param mcon ss7 boost connection + * \param event Event to handle + */ static int parse_ss7_event(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_short_event_t *event) { zap_mutex_lock(signal_mutex); @@ -669,6 +778,10 @@ static int parse_ss7_event(zap_span_t *span, ss7bc_connection_t *mcon, ss7bc_sho return 0; } +/** + * \brief Handler for channel state change + * \param zchan Channel to handle + */ static __inline__ void state_advance(zap_channel_t *zchan) { @@ -831,11 +944,18 @@ static __inline__ void state_advance(zap_channel_t *zchan) } } +/** + * \brief Initialises outgoing requests array + */ static __inline__ void init_outgoing_array(void) { memset(&OUTBOUND_REQUESTS, 0, sizeof(OUTBOUND_REQUESTS)); } +/** + * \brief Checks current state on a span + * \param span Span to check status on + */ static __inline__ void check_state(zap_span_t *span) { zap_ss7_boost_data_t *ss7_boost_data = span->signal_data; @@ -877,11 +997,13 @@ static __inline__ void check_state(zap_span_t *span) init_outgoing_array(); } } - - } - +/** + * \brief Main thread function for ss7 boost span (monitor) + * \param me Current thread + * \param obj Span to run in this thread + */ static void *zap_ss7_boost_run(zap_thread_t *me, void *obj) { zap_span_t *span = (zap_span_t *) obj; @@ -1015,6 +1137,11 @@ static void *zap_ss7_boost_run(zap_thread_t *me, void *obj) return NULL; } +/** + * \brief Loads ss7 boost signaling module + * \param zio Openzap IO interface + * \return Success + */ static ZIO_SIG_LOAD_FUNCTION(zap_ss7_boost_init) { zap_mutex_create(&request_mutex); @@ -1129,6 +1256,13 @@ static zap_state_map_t boost_state_map = { } }; +/** + * \brief Initialises an ss7 boost span from configuration variables + * \param span Span to configure + * \param sig_cb Callback function for event signals + * \param ap List of configuration variables + * \return Success or failure + */ static ZIO_SIG_CONFIGURE_FUNCTION(zap_ss7_boost_configure_span) { zap_ss7_boost_data_t *ss7_boost_data = NULL; @@ -1190,7 +1324,9 @@ static ZIO_SIG_CONFIGURE_FUNCTION(zap_ss7_boost_configure_span) return ZAP_SUCCESS; } - +/** + * \brief Openzap ss7 boost signaling module definition + */ zap_module_t zap_module = { "ss7_boost", NULL, diff --git a/libs/openzap/src/ozmod/ozmod_wanpipe/ozmod_wanpipe.c b/libs/openzap/src/ozmod/ozmod_wanpipe/ozmod_wanpipe.c index aa32132aa4..038f1c8b37 100644 --- a/libs/openzap/src/ozmod/ozmod_wanpipe/ozmod_wanpipe.c +++ b/libs/openzap/src/ozmod/ozmod_wanpipe/ozmod_wanpipe.c @@ -65,10 +65,16 @@ #define EX_DECLARE_DATA #endif +/** + * \brief Wanpipe flags + */ typedef enum { WP_RINGING = (1 << 0) } wp_flag_t; +/** + * \brief Wanpipe globals + */ static struct { uint32_t codec_ms; uint32_t wink_ms; @@ -84,9 +90,17 @@ ZIO_SPAN_NEXT_EVENT_FUNCTION(wanpipe_next_event); #define WP_INVALID_SOCKET -1 -/* a cross platform way to poll on an actual pollset (span and/or list of spans) will probably also be needed for analog */ -/* so we can have one analong handler thread that will deal with all the idle analog channels for events */ -/* the alternative would be for the driver to provide one socket for all of the oob events for all analog channels */ +/** + * \brief Poll for event on a wanpipe socket + * \param fd Wanpipe socket descriptor + * \param timeout Time to wait for event + * \param flags Sangoma event flags + * \return -1 on failure, wanpipe event flags on success + * + * a cross platform way to poll on an actual pollset (span and/or list of spans) will probably also be needed for analog + * so we can have one analong handler thread that will deal with all the idle analog channels for events + * the alternative would be for the driver to provide one socket for all of the oob events for all analog channels + */ static __inline__ int tdmv_api_wait_socket(sng_fd_t fd, int timeout, int *flags) { @@ -125,15 +139,24 @@ static __inline__ int tdmv_api_wait_socket(sng_fd_t fd, int timeout, int *flags) } +/** + * \brief Opens a sangoma channel socket (TDM API) + * \param span Span number + * \param chan Channel number + * \return 0 on success, wanpipe error code on failure + */ static __inline__ sng_fd_t tdmv_api_open_span_chan(int span, int chan) { return sangoma_open_tdmapi_span_chan(span, chan); } - - static zap_io_interface_t wanpipe_interface; +/** + * \brief Inverts bit string + * \param cas_bits CAS bit string + * \return Swapped bits + */ static unsigned char wanpipe_swap_bits(unsigned char cas_bits) { unsigned char swapped_bits = 0x0; @@ -152,6 +175,18 @@ static unsigned char wanpipe_swap_bits(unsigned char cas_bits) return swapped_bits; } +/** + * \brief Initialises a range of wanpipe channels + * \param span Openzap span + * \param spanno Wanpipe span number + * \param start Initial wanpipe channel number + * \param end Final wanpipe channel number + * \param type Openzap channel type + * \param name Openzap span name + * \param number Openzap span number + * \param cas_bits CAS bits + * \return number of spans configured + */ static unsigned wp_open_range(zap_span_t *span, unsigned spanno, unsigned start, unsigned end, zap_chan_type_t type, char *name, char *number, unsigned char cas_bits) { unsigned configured = 0, x; @@ -237,6 +272,14 @@ static unsigned wp_open_range(zap_span_t *span, unsigned spanno, unsigned start, return configured; } +/** + * \brief Process configuration variable for a Wanpipe profile + * \param category Wanpipe profile name + * \param var Variable name + * \param val Variable value + * \param lineno Line number from configuration file + * \return Success + */ static ZIO_CONFIGURE_FUNCTION(wanpipe_configure) { int num; @@ -269,6 +312,15 @@ static ZIO_CONFIGURE_FUNCTION(wanpipe_configure) return ZAP_SUCCESS; } +/** + * \brief Initialises an openzap Wanpipe span from a configuration string + * \param span Openzap span + * \param str Configuration string + * \param type Openzap span type + * \param name Openzap span name + * \param number Openzap span number + * \return Success or failure + */ static ZIO_CONFIGURE_SPAN_FUNCTION(wanpipe_configure_span) { int items, i; @@ -340,6 +392,11 @@ static ZIO_CONFIGURE_SPAN_FUNCTION(wanpipe_configure_span) return configured; } +/** + * \brief Opens Wanpipe channel + * \param zchan Channel to open + * \return Success or failure + */ static ZIO_OPEN_FUNCTION(wanpipe_open) { @@ -362,11 +419,23 @@ static ZIO_OPEN_FUNCTION(wanpipe_open) return ZAP_SUCCESS; } +/** + * \brief Closes Wanpipe channel + * \param zchan Channel to close + * \return Success + */ static ZIO_CLOSE_FUNCTION(wanpipe_close) { return ZAP_SUCCESS; } +/** + * \brief Executes an Openzap command on a Wanpipe channel + * \param zchan Channel to execute command on + * \param command Openzap command to execute + * \param obj Object (unused) + * \return Success or failure + */ static ZIO_COMMAND_FUNCTION(wanpipe_command) { wanpipe_tdm_api_t tdm_api; @@ -461,6 +530,13 @@ static ZIO_COMMAND_FUNCTION(wanpipe_command) return ZAP_SUCCESS; } +/** + * \brief Reads data from a Wanpipe channel + * \param zchan Channel to read from + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success, failure or timeout + */ static ZIO_READ_FUNCTION(wanpipe_read) { int rx_len = 0; @@ -484,6 +560,13 @@ static ZIO_READ_FUNCTION(wanpipe_read) return ZAP_SUCCESS; } +/** + * \brief Writes data to a Wanpipe channel + * \param zchan Channel to write to + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success or failure + */ static ZIO_WRITE_FUNCTION(wanpipe_write) { int bsent; @@ -502,7 +585,13 @@ static ZIO_WRITE_FUNCTION(wanpipe_write) return ZAP_FAIL; } - +/** + * \brief Waits for an event on a Wanpipe channel + * \param zchan Channel to open + * \param flags Type of event to wait for + * \param to Time to wait (in ms) + * \return Success, failure or timeout + */ static ZIO_WAIT_FUNCTION(wanpipe_wait) { int32_t inflags = 0; @@ -548,6 +637,12 @@ static ZIO_WAIT_FUNCTION(wanpipe_wait) return ZAP_SUCCESS; } +/** + * \brief Checks for events on a Wanpipe span + * \param span Span to check for events + * \param ms Time to wait for event + * \return Success if event is waiting or failure if not + */ ZIO_SPAN_POLL_EVENT_FUNCTION(wanpipe_poll_event) { #ifdef LIBSANGOMA_VERSION @@ -641,7 +736,11 @@ ZIO_SPAN_POLL_EVENT_FUNCTION(wanpipe_poll_event) return k ? ZAP_SUCCESS : ZAP_FAIL; } - +/** + * \brief Gets alarms from a Wanpipe Channel + * \param zchan Channel to get alarms from + * \return Success or failure + */ static ZIO_GET_ALARMS_FUNCTION(wanpipe_get_alarms) { wanpipe_tdm_api_t tdm_api; @@ -671,7 +770,12 @@ static ZIO_GET_ALARMS_FUNCTION(wanpipe_get_alarms) return ZAP_SUCCESS; } - +/** + * \brief Retrieves an event from a wanpipe span + * \param span Span to retrieve event from + * \param event Openzap event to return + * \return Success or failure + */ ZIO_SPAN_NEXT_EVENT_FUNCTION(wanpipe_next_event) { uint32_t i,err; @@ -827,6 +931,11 @@ ZIO_SPAN_NEXT_EVENT_FUNCTION(wanpipe_next_event) } +/** + * \brief Destroys a Wanpipe Channel + * \param zchan Channel to destroy + * \return Success + */ static ZIO_CHANNEL_DESTROY_FUNCTION(wanpipe_channel_destroy) { if (zchan->sockfd > -1) { @@ -837,6 +946,11 @@ static ZIO_CHANNEL_DESTROY_FUNCTION(wanpipe_channel_destroy) return ZAP_SUCCESS; } +/** + * \brief Loads wanpipe IO module + * \param zio Openzap IO interface + * \return Success + */ static ZIO_IO_LOAD_FUNCTION(wanpipe_init) { assert(zio != NULL); @@ -867,13 +981,19 @@ static ZIO_IO_LOAD_FUNCTION(wanpipe_init) return ZAP_SUCCESS; } +/** + * \brief Unloads wanpipe IO module + * \return Success + */ static ZIO_IO_UNLOAD_FUNCTION(wanpipe_destroy) { memset(&wanpipe_interface, 0, sizeof(wanpipe_interface)); return ZAP_SUCCESS; } - +/** + * \brief Openzap wanpipe IO module definition + */ EX_DECLARE_DATA zap_module_t zap_module = { "wanpipe", wanpipe_init, diff --git a/libs/openzap/src/ozmod/ozmod_zt/ozmod_zt.c b/libs/openzap/src/ozmod/ozmod_zt/ozmod_zt.c index db20ef95c5..7a4de2ad93 100644 --- a/libs/openzap/src/ozmod/ozmod_zt/ozmod_zt.c +++ b/libs/openzap/src/ozmod/ozmod_zt/ozmod_zt.c @@ -35,7 +35,9 @@ #include "openzap.h" #include "ozmod_zt.h" - +/** + * \brief Zaptel globals + */ static struct { uint32_t codec_ms; uint32_t wink_ms; @@ -46,6 +48,9 @@ static struct { float txgain; } zt_globals; +/** + * \brief General IOCTL codes + */ struct ioctl_codes { int GET_BLOCKSIZE; int SET_BLOCKSIZE; @@ -81,6 +86,9 @@ struct ioctl_codes { int GETRXBITS; }; +/** + * \brief Zaptel IOCTL codes + */ static struct ioctl_codes zt_ioctl_codes = { .GET_BLOCKSIZE = ZT_GET_BLOCKSIZE, .SET_BLOCKSIZE = ZT_SET_BLOCKSIZE, @@ -116,6 +124,9 @@ static struct ioctl_codes zt_ioctl_codes = { .GETRXBITS = ZT_GETRXBITS }; +/** + * \brief Dahdi IOCTL codes + */ static struct ioctl_codes dahdi_ioctl_codes = { .GET_BLOCKSIZE = DAHDI_GET_BLOCKSIZE, .SET_BLOCKSIZE = DAHDI_SET_BLOCKSIZE, @@ -167,6 +178,13 @@ static zap_socket_t CONTROL_FD = ZT_INVALID_SOCKET; ZIO_SPAN_NEXT_EVENT_FUNCTION(zt_next_event); ZIO_SPAN_POLL_EVENT_FUNCTION(zt_poll_event); +/** + * \brief Initialises codec, and rx/tx gains + * \param g Structure for gains to be initialised + * \param rxgain RX gain value + * \param txgain TX gain value + * \param codec Codec + */ static void zt_build_gains(struct zt_gains *g, float rxgain, float txgain, int codec) { int j; @@ -218,6 +236,17 @@ static void zt_build_gains(struct zt_gains *g, float rxgain, float txgain, int c } } +/** + * \brief Initialises a range of zaptel channels + * \param span Openzap span + * \param start Initial wanpipe channel number + * \param end Final wanpipe channel number + * \param type Openzap channel type + * \param name Openzap span name + * \param number Openzap span number + * \param cas_bits CAS bits + * \return number of spans configured + */ static unsigned zt_open_range(zap_span_t *span, unsigned start, unsigned end, zap_chan_type_t type, char *name, char *number, unsigned char cas_bits) { unsigned configured = 0, x; @@ -400,6 +429,15 @@ static unsigned zt_open_range(zap_span_t *span, unsigned start, unsigned end, za return configured; } +/** + * \brief Initialises an openzap zaptel span from a configuration string + * \param span Openzap span + * \param str Configuration string + * \param type Openzap span type + * \param name Openzap span name + * \param number Openzap span number + * \return Success or failure + */ static ZIO_CONFIGURE_SPAN_FUNCTION(zt_configure_span) { @@ -461,6 +499,14 @@ static ZIO_CONFIGURE_SPAN_FUNCTION(zt_configure_span) } +/** + * \brief Process configuration variable for a zaptel profile + * \param category Wanpipe profile name + * \param var Variable name + * \param val Variable value + * \param lineno Line number from configuration file + * \return Success + */ static ZIO_CONFIGURE_FUNCTION(zt_configure) { @@ -521,6 +567,11 @@ static ZIO_CONFIGURE_FUNCTION(zt_configure) return ZAP_SUCCESS; } +/** + * \brief Opens a zaptel channel + * \param zchan Channel to open + * \return Success or failure + */ static ZIO_OPEN_FUNCTION(zt_open) { zap_channel_set_feature(zchan, ZAP_CHANNEL_FEATURE_INTERVAL); @@ -596,11 +647,23 @@ static ZIO_OPEN_FUNCTION(zt_open) return ZAP_SUCCESS; } +/** + * \brief Closes zaptel channel + * \param zchan Channel to close + * \return Success + */ static ZIO_CLOSE_FUNCTION(zt_close) { return ZAP_SUCCESS; } +/** + * \brief Executes an Openzap command on a zaptel channel + * \param zchan Channel to execute command on + * \param command Openzap command to execute + * \param obj Object (unused) + * \return Success or failure + */ static ZIO_COMMAND_FUNCTION(zt_command) { zt_params_t ztp; @@ -746,6 +809,11 @@ static ZIO_COMMAND_FUNCTION(zt_command) return ZAP_SUCCESS; } +/** + * \brief Gets alarms from a zaptel Channel + * \param zchan Channel to get alarms from + * \return Success or failure + */ static ZIO_GET_ALARMS_FUNCTION(zt_get_alarms) { struct zt_spaninfo info; @@ -764,7 +832,13 @@ static ZIO_GET_ALARMS_FUNCTION(zt_get_alarms) return ZAP_SUCCESS; } - +/** + * \brief Waits for an event on a zaptel channel + * \param zchan Channel to open + * \param flags Type of event to wait for + * \param to Time to wait (in ms) + * \return Success, failure or timeout + */ static ZIO_WAIT_FUNCTION(zt_wait) { int32_t inflags = 0; @@ -825,6 +899,12 @@ static ZIO_WAIT_FUNCTION(zt_wait) } +/** + * \brief Checks for events on a zaptel span + * \param span Span to check for events + * \param ms Time to wait for event + * \return Success if event is waiting or failure if not + */ ZIO_SPAN_POLL_EVENT_FUNCTION(zt_poll_event) { struct pollfd pfds[ZAP_MAX_CHANNELS_SPAN]; @@ -862,6 +942,12 @@ ZIO_SPAN_POLL_EVENT_FUNCTION(zt_poll_event) return k ? ZAP_SUCCESS : ZAP_FAIL; } +/** + * \brief Retrieves an event from a zaptel span + * \param span Span to retrieve event from + * \param event Openzap event to return + * \return Success or failure + */ ZIO_SPAN_NEXT_EVENT_FUNCTION(zt_next_event) { uint32_t i, event_id = 0; @@ -957,7 +1043,13 @@ ZIO_SPAN_NEXT_EVENT_FUNCTION(zt_next_event) } - +/** + * \brief Reads data from a zaptel channel + * \param zchan Channel to read from + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success, failure or timeout + */ static ZIO_READ_FUNCTION(zt_read) { zap_ssize_t r = 0; @@ -983,6 +1075,13 @@ static ZIO_READ_FUNCTION(zt_read) return r == 0 ? ZAP_TIMEOUT : ZAP_FAIL; } +/** + * \brief Writes data to a zaptel channel + * \param zchan Channel to write to + * \param data Data buffer + * \param datalen Size of data buffer + * \return Success or failure + */ static ZIO_WRITE_FUNCTION(zt_write) { zap_ssize_t w = 0; @@ -1003,6 +1102,11 @@ static ZIO_WRITE_FUNCTION(zt_write) return ZAP_FAIL; } +/** + * \brief Destroys a zaptel Channel + * \param zchan Channel to destroy + * \return Success + */ static ZIO_CHANNEL_DESTROY_FUNCTION(zt_channel_destroy) { close(zchan->sockfd); @@ -1011,8 +1115,16 @@ static ZIO_CHANNEL_DESTROY_FUNCTION(zt_channel_destroy) return ZAP_SUCCESS; } +/** + * \brief Global Openzap IO interface for zaptel + */ static zap_io_interface_t zt_interface; +/** + * \brief Loads zaptel IO module + * \param zio Openzap IO interface + * \return Success or failure + */ static ZIO_IO_LOAD_FUNCTION(zt_init) { assert(zio != NULL); @@ -1063,6 +1175,10 @@ static ZIO_IO_LOAD_FUNCTION(zt_init) return ZAP_SUCCESS; } +/** + * \brief Unloads zaptel IO module + * \return Success + */ static ZIO_IO_UNLOAD_FUNCTION(zt_destroy) { close(CONTROL_FD); @@ -1070,7 +1186,9 @@ static ZIO_IO_UNLOAD_FUNCTION(zt_destroy) return ZAP_SUCCESS; } - +/** + * \brief Openzap zaptel IO module definition + */ zap_module_t zap_module = { "zt", zt_init,