5442fdb0cf4dd5431717d4ebbc136f60e6abc6bc
[asterisk/asterisk.git] / include / asterisk / cdr.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
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 /*!
20  * \file
21  * \brief Call Detail Record API
22  *
23  * \author Mark Spencer <markster@digium.com>
24  */
25
26 #ifndef _ASTERISK_CDR_H
27 #define _ASTERISK_CDR_H
28
29 #include <sys/time.h>
30
31 #include "asterisk/data.h"
32
33 /*!
34  * \brief CDR Flags
35  */
36 enum {
37         AST_CDR_FLAG_KEEP_VARS     = (1 << 0),
38         AST_CDR_FLAG_POSTED        = (1 << 1),
39         AST_CDR_FLAG_LOCKED        = (1 << 2),
40         AST_CDR_FLAG_CHILD         = (1 << 3),
41         AST_CDR_FLAG_POST_DISABLED = (1 << 4),
42         AST_CDR_FLAG_BRIDGED       = (1 << 5),
43         AST_CDR_FLAG_MAIN          = (1 << 6),
44         AST_CDR_FLAG_ENABLE        = (1 << 7),
45         AST_CDR_FLAG_ANSLOCKED     = (1 << 8),
46         AST_CDR_FLAG_DONT_TOUCH    = (1 << 9),
47         AST_CDR_FLAG_POST_ENABLE   = (1 << 10),
48         AST_CDR_FLAG_DIALED        = (1 << 11),
49         AST_CDR_FLAG_ORIGINATED    = (1 << 12),
50 };
51
52 /*!
53  * \brief CDR Flags - Disposition
54  */
55 enum {
56         AST_CDR_NOANSWER = 0,
57         AST_CDR_NULL     = (1 << 0),
58         AST_CDR_FAILED   = (1 << 1),
59         AST_CDR_BUSY     = (1 << 2),
60         AST_CDR_ANSWERED = (1 << 3),
61 };
62
63 /*!
64  * \brief CDR AMA Flags
65  */
66 enum {
67         AST_CDR_OMIT          = 1,
68         AST_CDR_BILLING       = 2,
69         AST_CDR_DOCUMENTATION = 3,
70 };
71
72 #define AST_MAX_USER_FIELD     256
73 #define AST_MAX_ACCOUNT_CODE   20
74
75 /* Include channel.h after relevant declarations it will need */
76 #include "asterisk/channel.h"
77 #include "asterisk/utils.h"
78
79 /*!
80  * \brief Responsible for call detail data
81  */
82 struct ast_cdr {
83         /*! Caller*ID with text */
84         char clid[AST_MAX_EXTENSION];
85         /*! Caller*ID number */
86         char src[AST_MAX_EXTENSION];
87         /*! Destination extension */
88         char dst[AST_MAX_EXTENSION];
89         /*! Destination context */
90         char dcontext[AST_MAX_EXTENSION];
91
92         char channel[AST_MAX_EXTENSION];
93         /*! Destination channel if appropriate */
94         char dstchannel[AST_MAX_EXTENSION];
95         /*! Last application if appropriate */
96         char lastapp[AST_MAX_EXTENSION];
97         /*! Last application data */
98         char lastdata[AST_MAX_EXTENSION];
99
100         struct timeval start;
101
102         struct timeval answer;
103
104         struct timeval end;
105         /*! Total time in system, in seconds */
106         long int duration;
107         /*! Total time call is up, in seconds */
108         long int billsec;
109         /*! What happened to the call */
110         long int disposition;
111         /*! What flags to use */
112         long int amaflags;
113         /*! What account number to use */
114         char accountcode[AST_MAX_ACCOUNT_CODE];
115         /*! Account number of the last person we talked to */
116         char peeraccount[AST_MAX_ACCOUNT_CODE];
117         /*! flags */
118         unsigned int flags;
119         /*! Unique Channel Identifier
120          * 150 = 127 (max systemname) + "-" + 10 (epoch timestamp) + "." + 10 (monotonically incrementing integer) + NULL */
121         char uniqueid[150];
122         /* Linked group Identifier */
123         char linkedid[32];
124         /*! User field */
125         char userfield[AST_MAX_USER_FIELD];
126         /*! Sequence field */
127         int sequence;
128
129         /*! A linked list for variables */
130         struct varshead varshead;
131
132         struct ast_cdr *next;
133 };
134
135 int ast_cdr_isset_unanswered(void);
136 void ast_cdr_getvar(struct ast_cdr *cdr, const char *name, char **ret, char *workspace, int workspacelen, int recur, int raw);
137 int ast_cdr_setvar(struct ast_cdr *cdr, const char *name, const char *value, int recur);
138 int ast_cdr_serialize_variables(struct ast_cdr *cdr, struct ast_str **buf, char delim, char sep, int recur);
139 void ast_cdr_free_vars(struct ast_cdr *cdr, int recur);
140 int ast_cdr_copy_vars(struct ast_cdr *to_cdr, struct ast_cdr *from_cdr);
141
142 /*!
143  * \brief CDR backend callback
144  * \warning CDR backends should NOT attempt to access the channel associated
145  * with a CDR record.  This channel is not guaranteed to exist when the CDR
146  * backend is invoked.
147  */
148 typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
149
150 /*! \brief Return TRUE if CDR subsystem is enabled */
151 int check_cdr_enabled(void);
152
153 /*!
154  * \brief Allocate a CDR record
155  * \retval a malloc'd ast_cdr structure
156  * \retval NULL on error (malloc failure)
157  */
158 struct ast_cdr *ast_cdr_alloc(void);
159
160 /*!
161  * \brief Duplicate a record and increment the sequence number.
162  * \param cdr the record to duplicate
163  * \retval a malloc'd ast_cdr structure,
164  * \retval NULL on error (malloc failure)
165  * \see ast_cdr_dup()
166  * \see ast_cdr_dup_unique_swap()
167  */
168 struct ast_cdr *ast_cdr_dup_unique(struct ast_cdr *cdr);
169
170 /*!
171  * \brief Duplicate a record and increment the sequence number of the old
172  * record.
173  * \param cdr the record to duplicate
174  * \retval a malloc'd ast_cdr structure,
175  * \retval NULL on error (malloc failure)
176  * \note This version increments the original CDR's sequence number rather than
177  * the duplicate's sequence number. The effect is as if the original CDR's
178  * sequence number was swapped with the duplicate's sequence number.
179  *
180  * \see ast_cdr_dup()
181  * \see ast_cdr_dup_unique()
182  */
183 struct ast_cdr *ast_cdr_dup_unique_swap(struct ast_cdr *cdr);
184
185 /*!
186  * \brief Duplicate a record
187  * \param cdr the record to duplicate
188  * \retval a malloc'd ast_cdr structure,
189  * \retval NULL on error (malloc failure)
190  * \see ast_cdr_dup_unique()
191  * \see ast_cdr_dup_unique_swap()
192  */
193 struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
194
195 /*!
196  * \brief Free a CDR record
197  * \param cdr ast_cdr structure to free
198  * Returns nothing
199  */
200 void ast_cdr_free(struct ast_cdr *cdr);
201
202 /*!
203  * \brief Discard and free a CDR record
204  * \param cdr ast_cdr structure to free
205  * Returns nothing  -- same as free, but no checks or complaints
206  */
207 void ast_cdr_discard(struct ast_cdr *cdr);
208
209 /*!
210  * \brief Initialize based on a channel
211  * \param cdr Call Detail Record to use for channel
212  * \param chan Channel to bind CDR with
213  * Initializes a CDR and associates it with a particular channel
214  * \return 0 by default
215  */
216 int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
217
218 /*!
219  * \brief Initialize based on a channel
220  * \param cdr Call Detail Record to use for channel
221  * \param chan Channel to bind CDR with
222  * Initializes a CDR and associates it with a particular channel
223  * \return 0 by default
224  */
225 int ast_cdr_setcid(struct ast_cdr *cdr, struct ast_channel *chan);
226
227 /*!
228  * \brief Register a CDR handling engine
229  * \param name name associated with the particular CDR handler
230  * \param desc description of the CDR handler
231  * \param be function pointer to a CDR handler
232  * Used to register a Call Detail Record handler.
233  * \retval 0 on success.
234  * \retval -1 on error
235  */
236 int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
237
238 /*!
239  * \brief Unregister a CDR handling engine
240  * \param name name of CDR handler to unregister
241  * Unregisters a CDR by it's name
242  */
243 void ast_cdr_unregister(const char *name);
244
245 /*!
246  * \brief Start a call
247  * \param cdr the cdr you wish to associate with the call
248  * Starts all CDR stuff necessary for monitoring a call
249  * Returns nothing
250  */
251 void ast_cdr_start(struct ast_cdr *cdr);
252
253 /*! \brief Answer a call
254  * \param cdr the cdr you wish to associate with the call
255  * Starts all CDR stuff necessary for doing CDR when answering a call
256  * \note NULL argument is just fine.
257  */
258 void ast_cdr_answer(struct ast_cdr *cdr);
259
260 /*!
261  * \brief A call wasn't answered
262  * \param cdr the cdr you wish to associate with the call
263  * Marks the channel disposition as "NO ANSWER"
264  * Will skip CDR's in chain with ANS_LOCK bit set. (see
265  * forkCDR() application.
266  */
267 extern void ast_cdr_noanswer(struct ast_cdr *cdr);
268
269 /*!
270  * \brief Busy a call
271  * \param cdr the cdr you wish to associate with the call
272  * Marks the channel disposition as "BUSY"
273  * Will skip CDR's in chain with ANS_LOCK bit set. (see
274  * forkCDR() application.
275  * Returns nothing
276  */
277 void ast_cdr_busy(struct ast_cdr *cdr);
278
279 /*!
280  * \brief Fail a call
281  * \param cdr the cdr you wish to associate with the call
282  * Marks the channel disposition as "FAILED"
283  * Will skip CDR's in chain with ANS_LOCK bit set. (see
284  * forkCDR() application.
285  * Returns nothing
286  */
287 void ast_cdr_failed(struct ast_cdr *cdr);
288
289 /*!
290  * \brief Save the result of the call based on the AST_CAUSE_*
291  * \param cdr the cdr you wish to associate with the call
292  * \param cause the AST_CAUSE_*
293  * Returns nothing
294  */
295 int ast_cdr_disposition(struct ast_cdr *cdr, int cause);
296
297 /*!
298  * \brief End a call
299  * \param cdr the cdr you have associated the call with
300  * Registers the end of call time in the cdr structure.
301  * Returns nothing
302  */
303 void ast_cdr_end(struct ast_cdr *cdr);
304
305 /*!
306  * \brief Detaches the detail record for posting (and freeing) either now or at a
307  * later time in bulk with other records during batch mode operation.
308  * \param cdr Which CDR to detach from the channel thread
309  * Prevents the channel thread from blocking on the CDR handling
310  * Returns nothing
311  */
312 void ast_cdr_detach(struct ast_cdr *cdr);
313
314 /*!
315  * \brief Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines
316  * \param shutdown Whether or not we are shutting down
317  * Blocks the asterisk shutdown procedures until the CDR data is submitted.
318  * Returns nothing
319  */
320 void ast_cdr_submit_batch(int shutdown);
321
322 /*!
323  * \brief Set the destination channel, if there was one
324  * \param cdr Which cdr it's applied to
325  * \param chan Channel to which dest will be
326  * Sets the destination channel the CDR is applied to
327  * Returns nothing
328  */
329 void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
330
331 /*!
332  * \brief Set the last executed application
333  * \param cdr which cdr to act upon
334  * \param app the name of the app you wish to change it to
335  * \param data the data you want in the data field of app you set it to
336  * Changes the value of the last executed app
337  * Returns nothing
338  */
339 void ast_cdr_setapp(struct ast_cdr *cdr, const char *app, const char *data);
340
341 /*!
342  * \brief Set the answer time for a call
343  * \param cdr the cdr you wish to associate with the call
344  * \param t the answer time
345  * Starts all CDR stuff necessary for doing CDR when answering a call
346  * NULL argument is just fine.
347  */
348 void ast_cdr_setanswer(struct ast_cdr *cdr, struct timeval t);
349
350 /*!
351  * \brief Set the disposition for a call
352  * \param cdr the cdr you wish to associate with the call
353  * \param disposition the new disposition
354  * Set the disposition on a call.
355  * NULL argument is just fine.
356  */
357 void ast_cdr_setdisposition(struct ast_cdr *cdr, long int disposition);
358
359 /*!
360  * \brief Convert a string to a detail record AMA flag
361  * \param flag string form of flag
362  * Converts the string form of the flag to the binary form.
363  * \return the binary form of the flag
364  */
365 int ast_cdr_amaflags2int(const char *flag);
366
367 /*!
368  * \brief Disposition to a string
369  * \param disposition input binary form
370  * Converts the binary form of a disposition to string form.
371  * \return a pointer to the string form
372  */
373 char *ast_cdr_disp2str(int disposition);
374
375 /*!
376  * \brief Reset the detail record, optionally posting it first
377  * \param cdr which cdr to act upon
378  * \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
379  *              |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
380  */
381 void ast_cdr_reset(struct ast_cdr *cdr, struct ast_flags *flags);
382
383 /*! Reset the detail record times, flags */
384 /*!
385  * \param cdr which cdr to act upon
386  * \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
387  *              |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
388  */
389 void ast_cdr_specialized_reset(struct ast_cdr *cdr, struct ast_flags *flags);
390
391 /*! Flags to a string */
392 /*!
393  * \param flags binary flag
394  * Converts binary flags to string flags
395  * Returns string with flag name
396  */
397 char *ast_cdr_flags2str(int flags);
398
399 /*!
400  * \brief Move the non-null data from the "from" cdr to the "to" cdr
401  * \param to the cdr to get the goodies
402  * \param from the cdr to give the goodies
403  */
404 void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
405
406 /*! \brief Set account code, will generate AMI event */
407 int ast_cdr_setaccount(struct ast_channel *chan, const char *account);
408
409 /*! \brief Set the peer account */
410 int ast_cdr_setpeeraccount(struct ast_channel *chan, const char *account);
411
412 /*! \brief Set AMA flags for channel */
413 int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
414
415 /*! \brief Set CDR user field for channel (stored in CDR) */
416 int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
417 /*! \brief Append to CDR user field for channel (stored in CDR) */
418 int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
419
420
421 /*! Update CDR on a channel */
422 int ast_cdr_update(struct ast_channel *chan);
423
424
425 extern int ast_default_amaflags;
426
427 extern char ast_default_accountcode[AST_MAX_ACCOUNT_CODE];
428
429 struct ast_cdr *ast_cdr_append(struct ast_cdr *cdr, struct ast_cdr *newcdr);
430
431 /*! \brief Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
432 int ast_cdr_engine_reload(void);
433
434 /*! \brief Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
435 int ast_cdr_engine_init(void);
436
437 /*! Submit any remaining CDRs and prepare for shutdown */
438 void ast_cdr_engine_term(void);
439
440 /*!
441  * \brief
442  * \param[in] tree Where to insert the cdr.
443  * \param[in] cdr The cdr structure to insert in 'tree'.
444  * \param[in] recur Go throw all the cdr levels.
445  * \retval <0 on error.
446  * \retval 0 on success.
447  */
448 int ast_cdr_data_add_structure(struct ast_data *tree, struct ast_cdr *cdr, int recur);
449
450 #endif /* _ASTERISK_CDR_H */