From a57a3cbf1964acde1fbf588d952b3fa59f197226 Mon Sep 17 00:00:00 2001 From: "Eliel C. Sardanons" Date: Tue, 4 Nov 2008 18:06:50 +0000 Subject: Add XML documentation for the ForkCDR() application. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@154225 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- apps/app_forkcdr.c | 189 +++++++++++++++++++++++++++++------------------------ 1 file changed, 104 insertions(+), 85 deletions(-) (limited to 'apps/app_forkcdr.c') diff --git a/apps/app_forkcdr.c b/apps/app_forkcdr.c index b2e4f307d..d48b6b50b 100644 --- a/apps/app_forkcdr.c +++ b/apps/app_forkcdr.c @@ -37,91 +37,110 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$") #include "asterisk/app.h" #include "asterisk/module.h" -static char *app = "ForkCDR"; -static char *synopsis = -"Forks the Call Data Record"; -static char *descrip = -" ForkCDR([options]): Causes the Call Data Record to fork an additional\n" -"cdr record starting from the time of the fork call. This new cdr record will\n" -"be linked to end of the list of cdr records attached to the channel. The original CDR is\n" -"has a LOCKED flag set, which forces most cdr operations to skip it, except\n" -"for the functions that set the answer and end times, which ignore the LOCKED\n" -"flag. This allows all the cdr records in the channel to be 'ended' together\n" -"when the channel is closed.\n" -"The CDR() func (when setting CDR values) normally ignores the LOCKED flag also,\n" -"but has options to vary its behavior. The 'T' option (described below), can\n" -"override this behavior, but beware the risks.\n" -"\n" -"Detailed Behavior Description:\n" -"First, this app finds the last cdr record in the list, and makes\n" -"a copy of it. This new copy will be the newly forked cdr record.\n" -"Next, this new record is linked to the end of the cdr record list.\n" -"Next, The new cdr record is RESET (unless you use an option to prevent this)\n" -"This means that:\n" -" 1. All flags are unset on the cdr record\n" -" 2. the start, end, and answer times are all set to zero.\n" -" 3. the billsec and duration fields are set to zero.\n" -" 4. the start time is set to the current time.\n" -" 5. the disposition is set to NULL.\n" -"Next, unless you specified the 'v' option, all variables will be\n" -"removed from the original cdr record. Thus, the 'v' option allows\n" -"any CDR variables to be replicated to all new forked cdr records.\n" -"Without the 'v' option, the variables on the original are effectively\n" -"moved to the new forked cdr record.\n" -"Next, if the 's' option is set, the provided variable and value\n" -"are set on the original cdr record.\n" -"Next, if the 'a' option is given, and the original cdr record has an\n" -"answer time set, then the new forked cdr record will have its answer\n" -"time set to its start time. If the old answer time were carried forward,\n" -"the answer time would be earlier than the start time, giving strange\n" -"duration and billsec times.\n" -"Next, if the 'd' option was specified, the disposition is copied from\n" -"the original cdr record to the new forked cdr.\n" -"Next, if the 'D' option was specified, the destination channel field\n" -"in the new forked CDR is erased.\n" -"Next, if the 'e' option was specified, the 'end' time for the original\n" -"cdr record is set to the current time. Future hang-up or ending events\n" -"will not override this time stamp.\n" -"Next, If the 'A' option is specified, the original cdr record will have\n" -"it ANS_LOCKED flag set, which prevent future answer events\n" -"from updating the original cdr record's disposition. Normally, an\n" -"'ANSWERED' event would mark all cdr records in the chain as 'ANSWERED'.\n" -"Next, if the 'T' option is specified, the original cdr record will have\n" -"its 'DONT_TOUCH' flag set, which will force the cdr_answer, cdr_end, and\n" -"cdr_setvar functions to leave that cdr record alone.\n" -"And, last but not least, the original cdr record has its LOCKED flag\n" -"set. Almost all internal CDR functions (except for the funcs that set\n" -"the end, and answer times, and set a variable) will honor this flag\n" -"and leave a LOCKED cdr record alone.\n" -"This means that the newly created forked cdr record will affected\n" -"by events transpiring within Asterisk, with the previously noted\n" -"exceptions.\n" -" Options:\n" -" a - update the answer time on the NEW CDR just after it's been inited..\n" -" The new CDR may have been answered already, the reset that forkcdr.\n" -" does will erase the answer time. This will bring it back, but\n" -" the answer time will be a copy of the fork/start time. It will.\n" -" only do this if the initial cdr was indeed already answered..\n" -" A - Lock the original CDR against the answer time being updated.\n" -" This will allow the disposition on the original CDR to remain the same.\n" -" d - Copy the disposition forward from the old cdr, after the .\n" -" init..\n" -" D - Clear the dstchannel on the new CDR after reset..\n" -" e - end the original CDR. Do this after all the necc. data.\n" -" is copied from the original CDR to the new forked CDR..\n" -" R - do NOT reset the new cdr..\n" -" s(name=val) - Set the CDR var 'name' in the original CDR, with value.\n" -" 'val'.\n" -" T - Mark the original CDR with a DONT_TOUCH flag. setvar, answer, and end\n" -" cdr funcs will obey this flag; normally they don't honor the LOCKED\n" -" flag set on the original CDR record.\n" -" Beware-- using this flag may cause CDR's not to have their end times\n" -" updated! It is suggested that if you specify this flag, you might\n" -" wish to use the 'e' flag as well!\n" -" v - When the new CDR is forked, it gets a copy of the vars attached\n" -" to the current CDR. The vars attached to the original CDR are removed\n" -" unless this option is specified.\n"; +/*** DOCUMENTATION + + + Forks the Call Data Record. + + + + + + + + + + + + + + + + + + Causes the Call Data Record to fork an additional cdr record starting from the time + of the fork call. This new cdr record will be linked to end of the list of cdr records attached + to the channel. The original CDR has a LOCKED flag set, which forces most cdr operations to skip + it, except for the functions that set the answer and end times, which ignore the LOCKED flag. This + allows all the cdr records in the channel to be 'ended' together when the channel is closed. + The CDR() func (when setting CDR values) normally ignores the LOCKED flag also, but has options + to vary its behavior. The 'T' option (described below), can override this behavior, but beware + the risks. + First, this app finds the last cdr record in the list, and makes a copy of it. This new copy + will be the newly forked cdr record. Next, this new record is linked to the end of the cdr record list. + Next, The new cdr record is RESET (unless you use an option to prevent this) + This means that: + 1. All flags are unset on the cdr record + 2. the start, end, and answer times are all set to zero. + 3. the billsec and duration fields are set to zero. + 4. the start time is set to the current time. + 5. the disposition is set to NULL. + Next, unless you specified the v option, all variables will be removed from + the original cdr record. Thus, the v option allows any CDR variables to be replicated + to all new forked cdr records. Without the v option, the variables on the original + are effectively moved to the new forked cdr record. + Next, if the s option is set, the provided variable and value are set on the + original cdr record. + Next, if the a option is given, and the original cdr record has an answer time + set, then the new forked cdr record will have its answer time set to its start time. If the old answer + time were carried forward, the answer time would be earlier than the start time, giving strange + duration and billsec times. + If the d option was specified, the disposition is copied from + the original cdr record to the new forked cdr. If the D option was specified, + the destination channel field in the new forked CDR is erased. If the e option + was specified, the 'end' time for the original cdr record is set to the current time. Future hang-up or + ending events will not override this time stamp. If the A option is specified, + the original cdr record will have it ANS_LOCKED flag set, which prevent future answer events from updating + the original cdr record's disposition. Normally, an ANSWERED event would mark all cdr + records in the chain as ANSWERED. If the T option is specified, + the original cdr record will have its DONT_TOUCH flag set, which will force the + cdr_answer, cdr_end, and cdr_setvar functions to leave that cdr record alone. + And, last but not least, the original cdr record has its LOCKED flag set. Almost all internal + CDR functions (except for the funcs that set the end, and answer times, and set a variable) will honor + this flag and leave a LOCKED cdr record alone. This means that the newly created forked cdr record + will be affected by events transpiring within Asterisk, with the previously noted exceptions. + + + CDR + NoCDR + ResetCDR + + + ***/ +static char *app = "ForkCDR"; enum { OPT_SETANS = (1 << 0), @@ -247,7 +266,7 @@ static int unload_module(void) static int load_module(void) { - return ast_register_application(app, forkcdr_exec, synopsis, descrip); + return ast_register_application_xml(app, forkcdr_exec); } AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Fork The CDR into 2 separate entities"); -- cgit v1.2.3