e7f14af2a9a30d596302fa54db5a0cc117447818
[asterisk/asterisk.git] / funcs / func_cdr.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999-2006, Digium, Inc.
5  *
6  * Portions Copyright (C) 2005, Anthony Minessale II
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief  Call Detail Record related dialplan functions
22  *
23  * \author Anthony Minessale II 
24  *
25  * \ingroup functions
26  */
27
28 #include "asterisk.h"
29
30 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
31
32 #include "asterisk/module.h"
33 #include "asterisk/channel.h"
34 #include "asterisk/pbx.h"
35 #include "asterisk/utils.h"
36 #include "asterisk/app.h"
37 #include "asterisk/cdr.h"
38
39 /*** DOCUMENTATION
40         <function name="CDR" language="en_US">
41                 <synopsis>
42                         Gets or sets a CDR variable.
43                 </synopsis>     
44                 <syntax>
45                         <parameter name="name" required="true">
46                                 <para>CDR field name:</para>
47                                 <enumlist>
48                                         <enum name="clid">
49                                                 <para>Caller ID.</para>
50                                         </enum>
51                                         <enum name="lastdata">
52                                                 <para>Last application arguments.</para>
53                                         </enum>
54                                         <enum name="disposition">
55                                                 <para>ANSWERED, NO ANSWER, BUSY.</para>
56                                         </enum>
57                                         <enum name="src">
58                                                 <para>Source.</para>
59                                         </enum>
60                                         <enum name="start">
61                                                 <para>Time the call started.</para>
62                                         </enum>
63                                         <enum name="amaflags">
64                                                 <para>DOCUMENTATION, BILL, IGNORE, etc.</para>
65                                         </enum>
66                                         <enum name="dst">
67                                                 <para>Destination.</para>
68                                         </enum>
69                                         <enum name="answer">
70                                                 <para>Time the call was answered.</para>
71                                         </enum>
72                                         <enum name="accountcode">
73                                                 <para>The channel's account code.</para>
74                                         </enum>
75                                         <enum name="dcontext">
76                                                 <para>Destination context.</para>
77                                         </enum>
78                                         <enum name="end">
79                                                 <para>Time the call ended.</para>
80                                         </enum>
81                                         <enum name="uniqueid">
82                                                 <para>The channel's unique id.</para>
83                                         </enum>
84                                         <enum name="dstchannel">
85                                                 <para>Destination channel.</para>
86                                         </enum>
87                                         <enum name="duration">
88                                                 <para>Duration of the call.</para>
89                                         </enum>
90                                         <enum name="userfield">
91                                                 <para>The channel's user specified field.</para>
92                                         </enum>
93                                         <enum name="lastapp">
94                                                 <para>Last application.</para>
95                                         </enum>
96                                         <enum name="billsec">
97                                                 <para>Duration of the call once it was answered.</para>
98                                         </enum>
99                                         <enum name="channel">
100                                                 <para>Channel name.</para>
101                                         </enum>
102                                 </enumlist>
103                         </parameter>
104                         <parameter name="options" required="false">
105                                 <optionlist>
106                                         <option name="l">
107                                                 <para>Uses the most recent CDR on a channel with multiple records</para>
108                                         </option>
109                                         <option name="r">
110                                                 <para>Searches the entire stack of CDRs on the channel.</para>
111                                         </option>
112                                         <option name="s">
113                                                 <para>Skips any CDR's that are marked 'LOCKED' due to forkCDR() calls.
114                                                 (on setting/writing CDR vars only)</para>
115                                         </option>
116                                         <option name="u">
117                                                 <para>Retrieves the raw, unprocessed value.</para>
118                                                 <para>For example, 'start', 'answer', and 'end' will be retrieved as epoch
119                                                 values, when the <literal>u</literal> option is passed, but formatted as YYYY-MM-DD HH:MM:SS
120                                                 otherwise.  Similarly, disposition and amaflags will return their raw
121                                                 integral values.</para>
122                                         </option>
123                                 </optionlist>
124                         </parameter>
125                 </syntax>
126                 <description>
127                         <para>All of the CDR field names are read-only, except for <literal>accountcode</literal>,
128                         <literal>userfield</literal>, and <literal>amaflags</literal>. You may, however, supply
129                         a name not on the above list, and create your own variable, whose value can be changed
130                         with this function, and this variable will be stored on the cdr.</para>
131                         <note><para>For setting CDR values, the <literal>l</literal> flag does not apply to
132                         setting the <literal>accountcode</literal>, <literal>userfield</literal>, or
133                         <literal>amaflags</literal>.</para></note>
134                         <para>Raw values for <literal>disposition</literal>:</para>
135                         <enumlist>
136                                 <enum name="1">
137                                         <para>NO ANSWER</para>
138                                 </enum>
139                                 <enum name="2">
140                                         <para>BUSY</para>
141                                 </enum>
142                                 <enum name="3">
143                                         <para>FAILED</para>
144                                 </enum>
145                                 <enum name="4">
146                                         <para>ANSWERED</para>
147                                 </enum>
148                         </enumlist>
149                         <para>Raw values for <literal>amaflags</literal>:</para>
150                         <enumlist>
151                                 <enum name="1">
152                                         <para>OMIT</para>
153                                 </enum>
154                                 <enum name="2">
155                                         <para>BILLING</para>
156                                 </enum>
157                                 <enum name="3">
158                                         <para>DOCUMENTATION</para>
159                                 </enum>
160                         </enumlist>
161                         <para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
162                 </description>
163         </function>
164  ***/
165
166 enum cdr_option_flags {
167         OPT_RECURSIVE = (1 << 0),
168         OPT_UNPARSED = (1 << 1),
169         OPT_LAST = (1 << 2),
170         OPT_SKIPLOCKED = (1 << 3),
171 };
172
173 AST_APP_OPTIONS(cdr_func_options, {
174         AST_APP_OPTION('l', OPT_LAST),
175         AST_APP_OPTION('r', OPT_RECURSIVE),
176         AST_APP_OPTION('s', OPT_SKIPLOCKED),
177         AST_APP_OPTION('u', OPT_UNPARSED),
178 });
179
180 static int cdr_read(struct ast_channel *chan, const char *cmd, char *parse,
181                     char *buf, size_t len)
182 {
183         char *ret;
184         struct ast_flags flags = { 0 };
185         struct ast_cdr *cdr = chan ? chan->cdr : NULL;
186         AST_DECLARE_APP_ARGS(args,
187                              AST_APP_ARG(variable);
188                              AST_APP_ARG(options);
189         );
190
191         if (ast_strlen_zero(parse))
192                 return -1;
193
194         if (!cdr)
195                 return -1;
196
197         AST_STANDARD_APP_ARGS(args, parse);
198
199         if (!ast_strlen_zero(args.options))
200                 ast_app_parse_options(cdr_func_options, &flags, NULL, args.options);
201
202         if (ast_test_flag(&flags, OPT_LAST))
203                 while (cdr->next)
204                         cdr = cdr->next;
205
206         if (ast_test_flag(&flags, OPT_SKIPLOCKED))
207                 while (ast_test_flag(cdr, AST_CDR_FLAG_LOCKED) && cdr->next)
208                         cdr = cdr->next;
209
210         ast_cdr_getvar(cdr, args.variable, &ret, buf, len,
211                        ast_test_flag(&flags, OPT_RECURSIVE),
212                            ast_test_flag(&flags, OPT_UNPARSED));
213
214         return ret ? 0 : -1;
215 }
216
217 static int cdr_write(struct ast_channel *chan, const char *cmd, char *parse,
218                      const char *value)
219 {
220         struct ast_cdr *cdr = chan ? chan->cdr : NULL;
221         struct ast_flags flags = { 0 };
222         AST_DECLARE_APP_ARGS(args,
223                              AST_APP_ARG(variable);
224                              AST_APP_ARG(options);
225         );
226
227         if (ast_strlen_zero(parse) || !value || !chan)
228                 return -1;
229
230         if (!cdr)
231                 return -1;
232
233         AST_STANDARD_APP_ARGS(args, parse);
234
235         if (!ast_strlen_zero(args.options))
236                 ast_app_parse_options(cdr_func_options, &flags, NULL, args.options);
237
238         if (ast_test_flag(&flags, OPT_LAST))
239                 while (cdr->next)
240                         cdr = cdr->next;
241
242         if (!strcasecmp(args.variable, "accountcode"))  /* the 'l' flag doesn't apply to setting the accountcode, userfield, or amaflags */
243                 ast_cdr_setaccount(chan, value);
244         else if (!strcasecmp(args.variable, "peeraccount"))
245                 ast_cdr_setpeeraccount(chan, value);
246         else if (!strcasecmp(args.variable, "userfield"))
247                 ast_cdr_setuserfield(chan, value);
248         else if (!strcasecmp(args.variable, "amaflags"))
249                 ast_cdr_setamaflags(chan, value);
250         else
251                 ast_cdr_setvar(cdr, args.variable, value, ast_test_flag(&flags, OPT_RECURSIVE));
252                 /* No need to worry about the u flag, as all fields for which setting
253                  * 'u' would do anything are marked as readonly. */
254
255         return 0;
256 }
257
258 static struct ast_custom_function cdr_function = {
259         .name = "CDR",
260         .read = cdr_read,
261         .write = cdr_write,
262 };
263
264 static int unload_module(void)
265 {
266         return ast_custom_function_unregister(&cdr_function);
267 }
268
269 static int load_module(void)
270 {
271         return ast_custom_function_register(&cdr_function);
272 }
273
274 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Call Detail Record (CDR) dialplan function");