From d55ebd58d2b1f60b9669208b855064e996fed285 Mon Sep 17 00:00:00 2001 From: Pedro Kiefer Date: Mon, 13 Aug 2012 14:38:06 -0300 Subject: [PATCH 7/7] Fix documentation --- apps/app_alarmreceiver.c | 150 ++++++++++++++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 52 deletions(-) diff --git a/apps/app_alarmreceiver.c b/apps/app_alarmreceiver.c index f8a1301..79705cf 100644 --- a/apps/app_alarmreceiver.c +++ b/apps/app_alarmreceiver.c @@ -105,13 +105,16 @@ static char time_stamp_format[128] = {"%a %b %d, %Y @ %H:%M:%S %Z"}; /* Misc variables */ static char event_file[14] = "/event-XXXXXX"; -/* -* Attempt to access a database variable and increment it, -* provided that the user defined db-family in alarmreceiver.conf -* The alarmreceiver app will write statistics to a few variables -* in this family if it is defined. If the new key doesn't exist in the -* family, then create it and set its value to 1. -*/ +/** + * Attempt to access a database variable and increment it + * provided that the user defined db-family in alarmreceiver.conf + * + * The alarmreceiver app will write statistics to a few variables + * in this family if it is defined. If the new key doesn't exist in the + * family, then create it and set its value to 1. + * + * @param key A database key to increment + */ static void database_increment(char *key) { unsigned v; @@ -140,10 +143,15 @@ static void database_increment(char *key) return; } - -/* -* Build a MuLaw data block for a single frequency tone -*/ +/** + * Build a MuLaw data block for a single frequency tone + * + * @param data Data pointer + * @param freq Frequency Tone + * @param loudness Signal Gain + * @param len Data Array Length + * @param x + */ static void make_tone_burst(unsigned char *data, float freq, float loudness, int len, int *x) { int i; @@ -160,10 +168,15 @@ static void make_tone_burst(unsigned char *data, float freq, float loudness, int } } -/* -* Send a single tone burst for a specifed duration and frequency. -* Returns 0 if successful -*/ +/** + * Send a single tone burst for a specified duration and frequency. + * + * @param chan Asterisk Channel + * @param freq Tone Frequency + * @param duration Duration + * @param tldn Signal Gain + * @return 0 if successful, -1 otherwise + */ static int send_tone_burst(struct ast_channel *chan, float freq, int duration, int tldn) { int i = 0; @@ -216,16 +229,17 @@ static int send_tone_burst(struct ast_channel *chan, float freq, int duration, i return -1; } -/* -* Receive a string of DTMF digits where the length of the digit string is known in advance. Do not give preferential -* treatment to any digit value, and allow separate time out values to be specified for the first digit and all subsequent -* digits. -* -* Returns 0 if all digits successfully received. -* Returns 1 if a digit time out occurred -* Returns -1 if the caller hung up or there was a channel error. -* -*/ +/** + * Receive a fixed length DTMF string. Doesn't give preferential treatment to any digit, + * allow different timeout values for the first and all subsequent digits + * + * @param chan Asterisk Channel + * @param digit_string Digits String + * @param length Length of the String + * @param fdto First Digit Timeout + * @param sdto Other Digits Timeout + * @return 0 if all digits were successfully received, 1 if a timeout occurred, -1 if the caller hung up or on channel errors + */ static int receive_dtmf_digits(struct ast_channel *chan, char *digit_string, int length, int fdto, int sdto) { int rtn = 0; @@ -286,9 +300,14 @@ static int receive_dtmf_digits(struct ast_channel *chan, char *digit_string, int return rtn; } -/* -* Write the metadata to the log file -*/ +/** + * Write metadata to log file + * + * @param logfile Log File Pointer + * @param signalling_type Signaling Type + * @param chan Asterisk Channel + * @return 0 if successful, -1 otherwise + */ static int write_metadata(FILE *logfile, char *signalling_type, struct ast_channel *chan) { struct timeval t; @@ -331,9 +350,13 @@ static int write_metadata(FILE *logfile, char *signalling_type, struct ast_chann return 0; } -/* -* Write a single event to the log file -*/ +/** + * Log a single event + * + * @param logfile Log File Pointer + * @param event Event Structure + * @return 0 if successful, -1 otherwise + */ static int write_event(FILE *logfile, event_node_t *event) { if (fprintf(logfile, "%s\n", event->data) < 0) @@ -341,10 +364,14 @@ static int write_event(FILE *logfile, event_node_t *event) return 0; } -/* -* If we are configured to log events, do so here. -* -*/ +/** + * Log events if configuration key logindividualevents is enabled + * + * @param chan Asterisk Channel + * @param signalling_type Signaling Type + * @param event Event Structure + * @return + */ static int log_events(struct ast_channel *chan, char *signalling_type, event_node_t *event) { char workstring[sizeof(event_spool_dir) + sizeof(event_file)] = ""; @@ -389,8 +416,11 @@ static int log_events(struct ast_channel *chan, char *signalling_type, event_nod return 0; } -/* - * Ademco checksum +/** + * Verify Ademco checksum + * + * @param event Received DTMF String + * @return 0 if successful, -1 otherwise */ static int ademco_verify_checksum(char *event) { @@ -424,11 +454,17 @@ static int ademco_verify_checksum(char *event) return -1; } -/* -* This function implements the logic to receive the Ademco contact ID format. -* -* The function will return 0 when the caller hangs up, else a -1 if there was a problem. -*/ +/** + * Receive Ademco ContactID Data String + * + * @param chan + * @param data + * @param fdto + * @param sdto + * @param tldn + * @param ehead + * @return 0 if successful, -1 otherwise + */ static int receive_ademco_contact_id(struct ast_channel *chan, const void *data, int fdto, int sdto, int tldn, event_node_t **ehead) { int res = 0; @@ -561,10 +597,13 @@ static int receive_ademco_contact_id(struct ast_channel *chan, const void *data, return res; } -/* -* This is the main function called by Asterisk Core whenever the App is invoked in the extension logic. -* This function will always return 0. -*/ +/** + * This is the main function called by Asterisk Core whenever the App is invoked in the extension logic. + * + * @param chan + * @param data + * @return Always return 0 + */ static int alarmreceiver_exec(struct ast_channel *chan, const char *data) { int res = 0; @@ -634,9 +673,11 @@ static int alarmreceiver_exec(struct ast_channel *chan, const char *data) return 0; } -/* -* Load the configuration from the configuration file -*/ +/** + * Load the configuration from the configuration file + * + * @return 1 if sucessfull, 0 otherwise + */ static int load_config(void) { struct ast_config *cfg; @@ -710,14 +751,19 @@ static int load_config(void) return 1; } -/* -* These functions are required to implement an Asterisk App. -*/ +/** + * Unregister Alarm Receiver App + * @return + */ static int unload_module(void) { return ast_unregister_application(app); } +/** + * Register Alarm Receiver App + * @return + */ static int load_module(void) { if (load_config()) { -- 1.7.9.6 (Apple Git-31.1)