Wed Apr 6 11:29:38 2011

Asterisk developer's documentation


app_forkcdr.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Anthony Minessale anthmct@yahoo.com
00005  * Development of this app Sponsered/Funded  by TAAN Softworks Corp
00006  *
00007  * See http://www.asterisk.org for more information about
00008  * the Asterisk project. Please do not directly contact
00009  * any of the maintainers of this project for assistance;
00010  * the project provides a web site, mailing lists and IRC
00011  * channels for your use.
00012  *
00013  * This program is free software, distributed under the terms of
00014  * the GNU General Public License Version 2. See the LICENSE file
00015  * at the top of the source tree.
00016  */
00017 
00018 /*! \file
00019  *
00020  * \brief Fork CDR application
00021  *
00022  * \author Anthony Minessale anthmct@yahoo.com
00023  *
00024  * \note Development of this app Sponsored/Funded by TAAN Softworks Corp
00025  * 
00026  * \ingroup applications
00027  */
00028 
00029 #include "asterisk.h"
00030 
00031 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 227435 $")
00032 
00033 #include "asterisk/file.h"
00034 #include "asterisk/channel.h"
00035 #include "asterisk/pbx.h"
00036 #include "asterisk/cdr.h"
00037 #include "asterisk/app.h"
00038 #include "asterisk/module.h"
00039 
00040 /*** DOCUMENTATION
00041    <application name="ForkCDR" language="en_US">
00042       <synopsis>
00043          Forks the Call Data Record.
00044       </synopsis>
00045       <syntax>
00046          <parameter name="options">
00047             <optionlist>
00048                <option name="a">
00049                   <para>Update the answer time on the NEW CDR just after it's been inited.
00050                   The new CDR may have been answered already. The reset that forkcdr does
00051                   will erase the answer time. This will bring it back, but the answer time
00052                   will be a copy of the fork/start time. It will only do this if the initial
00053                   cdr was indeed already answered.</para>
00054                </option>
00055                <option name="A">
00056                   <para>Lock the original CDR against the answer time being updated. This
00057                   will allow the disposition on the original CDR to remain the same.</para>
00058                </option>
00059                <option name="d">
00060                   <para>Copy the disposition forward from the old cdr, after the init.</para>
00061                </option>
00062                <option name="D">
00063                   <para>Clear the <literal>dstchannel</literal> on the new CDR after
00064                   reset.</para>
00065                </option>
00066                <option name="e">
00067                   <para>End the original CDR. Do this after all the necessary data is copied
00068                   from the original CDR to the new forked CDR.</para>
00069                </option>
00070                <option name="r">
00071                   <para>Do <emphasis>NOT</emphasis> reset the new cdr.</para>
00072                </option>
00073                <option name="s(name=val)">
00074                   <para>Set the CDR var <replaceable>name</replaceable> in the original CDR,
00075                   with value <replaceable>val</replaceable>.</para>
00076                </option>
00077                <option name="T">
00078                   <para>Mark the original CDR with a DONT_TOUCH flag. setvar, answer, and end
00079                   cdr funcs will obey this flag; normally they don't honor the LOCKED flag
00080                   set on the original CDR record.</para>
00081                   <note><para>Using this flag may cause CDR's not to have their end times
00082                   updated! It is suggested that if you specify this flag, you might wish
00083                   to use the <literal>e</literal> flag as well!.</para></note>
00084                </option>
00085                <option name="v">
00086                   <para>When the new CDR is forked, it gets a copy of the vars attached to
00087                   the current CDR. The vars attached to the original CDR are removed unless
00088                   this option is specified.</para>
00089                </option>
00090             </optionlist>
00091          </parameter>
00092       </syntax>
00093       <description>
00094          <para> Causes the Call Data Record to fork an additional cdr record starting from the time
00095          of the fork call. This new cdr record will be linked to end of the list of cdr records attached
00096          to the channel.   The original CDR has a LOCKED flag set, which forces most cdr operations to skip
00097          it, except for the functions that set the answer and end times, which ignore the LOCKED flag. This
00098          allows all the cdr records in the channel to be 'ended' together when the channel is closed.</para>
00099          <para>The CDR() func (when setting CDR values) normally ignores the LOCKED flag also, but has options
00100          to vary its behavior. The 'T' option (described below), can override this behavior, but beware
00101          the risks.</para>
00102          <para>First, this app finds the last cdr record in the list, and makes a copy of it. This new copy
00103          will be the newly forked cdr record. Next, this new record is linked to the end of the cdr record list.
00104          Next, The new cdr record is RESET (unless you use an option to prevent this)</para>
00105          <para>This means that:</para>
00106          <para>   1. All flags are unset on the cdr record</para>
00107          <para>   2. the start, end, and answer times are all set to zero.</para>
00108          <para>   3. the billsec and duration fields are set to zero.</para>
00109          <para>   4. the start time is set to the current time.</para>
00110          <para>   5. the disposition is set to NULL.</para>
00111          <para>Next, unless you specified the <literal>v</literal> option, all variables will be removed from
00112          the original cdr record. Thus, the <literal>v</literal> option allows any CDR variables to be replicated
00113          to all new forked cdr records. Without the <literal>v</literal> option, the variables on the original
00114          are effectively moved to the new forked cdr record.</para>
00115          <para>Next, if the <literal>s</literal> option is set, the provided variable and value are set on the
00116          original cdr record.</para>
00117          <para>Next, if the <literal>a</literal> option is given, and the original cdr record has an answer time
00118          set, then the new forked cdr record will have its answer time set to its start time. If the old answer
00119          time were carried forward, the answer time would be earlier than the start time, giving strange
00120          duration and billsec times.</para>
00121          <para>If the <literal>d</literal> option was specified, the disposition is copied from
00122          the original cdr record to the new forked cdr. If the <literal>D</literal> option was specified,
00123          the destination channel field in the new forked CDR is erased. If the <literal>e</literal> option
00124          was specified, the 'end' time for the original cdr record is set to the current time. Future hang-up or
00125          ending events will not override this time stamp. If the <literal>A</literal> option is specified,
00126          the original cdr record will have it ANS_LOCKED flag set, which prevent future answer events from updating
00127          the original cdr record's disposition. Normally, an <literal>ANSWERED</literal> event would mark all cdr
00128          records in the chain as <literal>ANSWERED</literal>. If the <literal>T</literal> option is specified,
00129          the original cdr record will have its <literal>DONT_TOUCH</literal> flag set, which will force the
00130          cdr_answer, cdr_end, and cdr_setvar functions to leave that cdr record alone.</para>
00131          <para>And, last but not least, the original cdr record has its LOCKED flag set. Almost all internal
00132          CDR functions (except for the funcs that set the end, and answer times, and set a variable) will honor
00133          this flag and leave a LOCKED cdr record alone. This means that the newly created forked cdr record
00134          will be affected by events transpiring within Asterisk, with the previously noted exceptions.</para>
00135       </description>
00136       <see-also>
00137          <ref type="function">CDR</ref>
00138          <ref type="application">NoCDR</ref>
00139          <ref type="application">ResetCDR</ref>
00140       </see-also>
00141    </application>
00142  ***/
00143 
00144 static char *app = "ForkCDR";
00145 
00146 enum {
00147    OPT_SETANS =            (1 << 0),
00148    OPT_SETDISP =           (1 << 1),
00149    OPT_RESETDEST =         (1 << 2),
00150    OPT_ENDCDR =            (1 << 3),
00151    OPT_NORESET =           (1 << 4),
00152    OPT_KEEPVARS =          (1 << 5),
00153    OPT_VARSET =            (1 << 6),
00154    OPT_ANSLOCK =           (1 << 7),
00155    OPT_DONTOUCH =          (1 << 8),
00156 };
00157 
00158 enum {
00159    OPT_ARG_VARSET = 0,
00160    /* note: this entry _MUST_ be the last one in the enum */
00161    OPT_ARG_ARRAY_SIZE,
00162 };
00163 
00164 AST_APP_OPTIONS(forkcdr_exec_options, {
00165    AST_APP_OPTION('a', OPT_SETANS),
00166    AST_APP_OPTION('A', OPT_ANSLOCK),
00167    AST_APP_OPTION('d', OPT_SETDISP),
00168    AST_APP_OPTION('D', OPT_RESETDEST),
00169    AST_APP_OPTION('e', OPT_ENDCDR),
00170    AST_APP_OPTION('R', OPT_NORESET),
00171    AST_APP_OPTION_ARG('s', OPT_VARSET, OPT_ARG_VARSET),
00172    AST_APP_OPTION('T', OPT_DONTOUCH),
00173    AST_APP_OPTION('v', OPT_KEEPVARS),
00174 });
00175 
00176 static void ast_cdr_fork(struct ast_channel *chan, struct ast_flags optflags, char *set) 
00177 {
00178    struct ast_cdr *cdr;
00179    struct ast_cdr *newcdr;
00180    struct ast_flags flags = { AST_CDR_FLAG_KEEP_VARS };
00181 
00182    cdr = chan->cdr;
00183 
00184    while (cdr->next)
00185       cdr = cdr->next;
00186    
00187    if (!(newcdr = ast_cdr_dup_unique(cdr)))
00188       return;
00189    
00190    ast_cdr_append(cdr, newcdr);
00191 
00192    if (!ast_test_flag(&optflags, OPT_NORESET))
00193       ast_cdr_reset(newcdr, &flags);
00194       
00195    if (!ast_test_flag(cdr, AST_CDR_FLAG_KEEP_VARS))
00196       ast_cdr_free_vars(cdr, 0);
00197    
00198    if (!ast_strlen_zero(set)) {
00199       char *varname = ast_strdupa(set), *varval;
00200       varval = strchr(varname,'=');
00201       if (varval) {
00202          *varval = 0;
00203          varval++;
00204          ast_cdr_setvar(cdr, varname, varval, 0);
00205       }
00206    }
00207    
00208    if (ast_test_flag(&optflags, OPT_SETANS) && !ast_tvzero(cdr->answer))
00209       newcdr->answer = newcdr->start;
00210 
00211    if (ast_test_flag(&optflags, OPT_SETDISP))
00212       newcdr->disposition = cdr->disposition;
00213    
00214    if (ast_test_flag(&optflags, OPT_RESETDEST))
00215       newcdr->dstchannel[0] = 0;
00216    
00217    if (ast_test_flag(&optflags, OPT_ENDCDR))
00218       ast_cdr_end(cdr);
00219 
00220    if (ast_test_flag(&optflags, OPT_ANSLOCK))
00221       ast_set_flag(cdr, AST_CDR_FLAG_ANSLOCKED);
00222    
00223    if (ast_test_flag(&optflags, OPT_DONTOUCH))
00224       ast_set_flag(cdr, AST_CDR_FLAG_DONT_TOUCH);
00225       
00226    ast_set_flag(cdr, AST_CDR_FLAG_CHILD | AST_CDR_FLAG_LOCKED);
00227 }
00228 
00229 static int forkcdr_exec(struct ast_channel *chan, const char *data)
00230 {
00231    int res = 0;
00232    char *argcopy = NULL;
00233    struct ast_flags flags = {0};
00234    char *opts[OPT_ARG_ARRAY_SIZE];
00235    AST_DECLARE_APP_ARGS(arglist,
00236       AST_APP_ARG(options);
00237    );
00238 
00239    if (!chan->cdr) {
00240       ast_log(LOG_WARNING, "Channel does not have a CDR\n");
00241       return 0;
00242    }
00243 
00244    argcopy = ast_strdupa(data);
00245 
00246    AST_STANDARD_APP_ARGS(arglist, argcopy);
00247 
00248    opts[OPT_ARG_VARSET] = 0;
00249 
00250    if (!ast_strlen_zero(arglist.options))
00251       ast_app_parse_options(forkcdr_exec_options, &flags, opts, arglist.options);
00252 
00253    if (!ast_strlen_zero(data)) {
00254       int keepvars = ast_test_flag(&flags, OPT_KEEPVARS) ? 1 : 0;
00255       ast_set2_flag(chan->cdr, keepvars, AST_CDR_FLAG_KEEP_VARS);
00256    }
00257    
00258    ast_cdr_fork(chan, flags, opts[OPT_ARG_VARSET]);
00259 
00260    return res;
00261 }
00262 
00263 static int unload_module(void)
00264 {
00265    return ast_unregister_application(app);
00266 }
00267 
00268 static int load_module(void)
00269 {
00270    return ast_register_application_xml(app, forkcdr_exec);
00271 }
00272 
00273 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Fork The CDR into 2 separate entities");

Generated on Wed Apr 6 11:29:38 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7