Merged revisions 238230 via svnmerge from
[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, FAILED.</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                                         <enum name="sequence">
103                                                 <para>CDR sequence number.</para>
104                                         </enum>
105                                 </enumlist>
106                         </parameter>
107                         <parameter name="options" required="false">
108                                 <optionlist>
109                                         <option name="l">
110                                                 <para>Uses the most recent CDR on a channel with multiple records</para>
111                                         </option>
112                                         <option name="r">
113                                                 <para>Searches the entire stack of CDRs on the channel.</para>
114                                         </option>
115                                         <option name="s">
116                                                 <para>Skips any CDR's that are marked 'LOCKED' due to forkCDR() calls.
117                                                 (on setting/writing CDR vars only)</para>
118                                         </option>
119                                         <option name="u">
120                                                 <para>Retrieves the raw, unprocessed value.</para>
121                                                 <para>For example, 'start', 'answer', and 'end' will be retrieved as epoch
122                                                 values, when the <literal>u</literal> option is passed, but formatted as YYYY-MM-DD HH:MM:SS
123                                                 otherwise.  Similarly, disposition and amaflags will return their raw
124                                                 integral values.</para>
125                                         </option>
126                                 </optionlist>
127                         </parameter>
128                 </syntax>
129                 <description>
130                         <para>All of the CDR field names are read-only, except for <literal>accountcode</literal>,
131                         <literal>userfield</literal>, and <literal>amaflags</literal>. You may, however, supply
132                         a name not on the above list, and create your own variable, whose value can be changed
133                         with this function, and this variable will be stored on the cdr.</para>
134                         <note><para>For setting CDR values, the <literal>l</literal> flag does not apply to
135                         setting the <literal>accountcode</literal>, <literal>userfield</literal>, or
136                         <literal>amaflags</literal>.</para></note>
137                         <para>Raw values for <literal>disposition</literal>:</para>
138                         <enumlist>
139                                 <enum name="0">
140                                         <para>NO ANSWER</para>
141                                 </enum>
142                                 <enum name="1">
143                                         <para>NO ANSWER (NULL record)</para>
144                                 </enum>
145                                 <enum name="2">
146                                         <para>FAILED</para>
147                                 </enum>
148                                 <enum name="4">
149                                         <para>BUSY</para>
150                                 </enum>
151                                 <enum name="8">
152                                         <para>ANSWERED</para>
153                                 </enum>
154                         </enumlist>
155                         <para>Raw values for <literal>amaflags</literal>:</para>
156                         <enumlist>
157                                 <enum name="1">
158                                         <para>OMIT</para>
159                                 </enum>
160                                 <enum name="2">
161                                         <para>BILLING</para>
162                                 </enum>
163                                 <enum name="3">
164                                         <para>DOCUMENTATION</para>
165                                 </enum>
166                         </enumlist>
167                         <para>Example: exten => 1,1,Set(CDR(userfield)=test)</para>
168                 </description>
169         </function>
170  ***/
171
172 enum cdr_option_flags {
173         OPT_RECURSIVE = (1 << 0),
174         OPT_UNPARSED = (1 << 1),
175         OPT_LAST = (1 << 2),
176         OPT_SKIPLOCKED = (1 << 3),
177 };
178
179 AST_APP_OPTIONS(cdr_func_options, {
180         AST_APP_OPTION('l', OPT_LAST),
181         AST_APP_OPTION('r', OPT_RECURSIVE),
182         AST_APP_OPTION('s', OPT_SKIPLOCKED),
183         AST_APP_OPTION('u', OPT_UNPARSED),
184 });
185
186 static int cdr_read(struct ast_channel *chan, const char *cmd, char *parse,
187                     char *buf, size_t len)
188 {
189         char *ret;
190         struct ast_flags flags = { 0 };
191         struct ast_cdr *cdr = chan ? chan->cdr : NULL;
192         AST_DECLARE_APP_ARGS(args,
193                              AST_APP_ARG(variable);
194                              AST_APP_ARG(options);
195         );
196
197         if (ast_strlen_zero(parse))
198                 return -1;
199
200         if (!cdr)
201                 return -1;
202
203         AST_STANDARD_APP_ARGS(args, parse);
204
205         if (!ast_strlen_zero(args.options))
206                 ast_app_parse_options(cdr_func_options, &flags, NULL, args.options);
207
208         if (ast_test_flag(&flags, OPT_LAST))
209                 while (cdr->next)
210                         cdr = cdr->next;
211
212         if (ast_test_flag(&flags, OPT_SKIPLOCKED))
213                 while (ast_test_flag(cdr, AST_CDR_FLAG_LOCKED) && cdr->next)
214                         cdr = cdr->next;
215
216         ast_cdr_getvar(cdr, args.variable, &ret, buf, len,
217                        ast_test_flag(&flags, OPT_RECURSIVE),
218                            ast_test_flag(&flags, OPT_UNPARSED));
219
220         return ret ? 0 : -1;
221 }
222
223 static int cdr_write(struct ast_channel *chan, const char *cmd, char *parse,
224                      const char *value)
225 {
226         struct ast_cdr *cdr = chan ? chan->cdr : NULL;
227         struct ast_flags flags = { 0 };
228         AST_DECLARE_APP_ARGS(args,
229                              AST_APP_ARG(variable);
230                              AST_APP_ARG(options);
231         );
232
233         if (ast_strlen_zero(parse) || !value || !chan)
234                 return -1;
235
236         if (!cdr)
237                 return -1;
238
239         AST_STANDARD_APP_ARGS(args, parse);
240
241         if (!ast_strlen_zero(args.options))
242                 ast_app_parse_options(cdr_func_options, &flags, NULL, args.options);
243
244         if (ast_test_flag(&flags, OPT_LAST))
245                 while (cdr->next)
246                         cdr = cdr->next;
247
248         if (!strcasecmp(args.variable, "accountcode"))  /* the 'l' flag doesn't apply to setting the accountcode, userfield, or amaflags */
249                 ast_cdr_setaccount(chan, value);
250         else if (!strcasecmp(args.variable, "peeraccount"))
251                 ast_cdr_setpeeraccount(chan, value);
252         else if (!strcasecmp(args.variable, "userfield"))
253                 ast_cdr_setuserfield(chan, value);
254         else if (!strcasecmp(args.variable, "amaflags"))
255                 ast_cdr_setamaflags(chan, value);
256         else
257                 ast_cdr_setvar(cdr, args.variable, value, ast_test_flag(&flags, OPT_RECURSIVE));
258                 /* No need to worry about the u flag, as all fields for which setting
259                  * 'u' would do anything are marked as readonly. */
260
261         return 0;
262 }
263
264 static struct ast_custom_function cdr_function = {
265         .name = "CDR",
266         .read = cdr_read,
267         .write = cdr_write,
268 };
269
270 static int unload_module(void)
271 {
272         return ast_custom_function_unregister(&cdr_function);
273 }
274
275 static int load_module(void)
276 {
277         return ast_custom_function_register(&cdr_function);
278 }
279
280 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Call Detail Record (CDR) dialplan function");