Fixup skinny registration following network issues.
[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 "asterisk/channel.h"
30
31 /*! \file
32  *
33  * \since 12
34  *
35  * \brief Call Detail Record Engine.
36  *
37  * \page CDR Call Detail Record Engine
38  *
39  * \par Intro
40  *
41  * The Call Detail Record (CDR) engine uses the \ref stasis Stasis Message Bus
42  * to build records for the channels in Asterisk. As the state of a channel and
43  * the bridges it participates in changes, notifications are sent over the
44  * Stasis Message Bus. The CDR engine consumes these notifications and builds
45  * records that reflect that state. Over the lifetime of a channel, many CDRs
46  * may be generated for that channel or that involve that channel.
47  *
48  * CDRs have a lifecycle that is a subset of the channel that they reflect. A
49  * single CDR for a channel represents a path of communication between the
50  * endpoint behind a channel and Asterisk, or between two endpoints. When a
51  * channel establishes a new path of communication, a new CDR is created for the
52  * channel. Likewise, when a path of communication is terminated, a CDR is
53  * finalized. Finally, when a channel is no longer present in Asterisk, all CDRs
54  * for that channel are dispatched for recording.
55  *
56  * Dispatching of CDRs occurs to registered CDR backends. CDR backends register
57  * through \ref ast_cdr_register and are responsible for taking the produced
58  * CDRs and storing them in permanent storage.
59  *
60  * \par CDR attributes
61  *
62  * While a CDR can have many attributes, all CDRs have two parties: a Party A
63  * and a Party B. The Party A is \em always the channel that owns the CDR. A CDR
64  * may or may not have a Party B, depending on its state.
65  *
66  * For the most part, attributes on a CDR are reflective of those same
67  * attributes on the channel at the time when the CDR was finalized. Specific
68  * CDR attributes include:
69  * \li \c start The time when the CDR was created
70  * \li \c answer The time when the Party A was answered, or when the path of
71  * communication between Party A and Party B was established
72  * \li \c end The time when the CDR was finalized
73  * \li \c duration \c end - \c start. If \c end is not known, the current time
74  * is used
75  * \li \c billsec \c end - \c answer. If \c end is not known, the current time
76  * is used
77  * \li \c userfield User set data on some party in the CDR
78  *
79  * Note that \c accountcode and \c amaflags are actually properties of a
80  * channel, not the CDR.
81  *
82  * \par CDR States
83  *
84  * CDRs go through various states during their lifetime. State transitions occur
85  * due to messages received over the \ref stasis Stasis Message Bus. The
86  * following describes the possible states a CDR can be in, and how it
87  * transitions through the states.
88  *
89  * \par Single
90  *
91  * When a CDR is created, it is put into the Single state. The Single state
92  * represents a CDR for a channel that has no Party B. CDRs can be unanswered
93  * or answered while in the Single state.
94  *
95  * The following transitions can occur while in the Single state:
96  * \li If a \ref ast_channel_dial_type indicating a Dial Begin is received, the
97  * state transitions to Dial
98  * \li If a \ref ast_channel_snapshot is received indicating that the channel
99  * has hung up, the state transitions to Finalized
100  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
101  * state transitions to Bridge
102  * \li If a \ref ast_bridge_blob_type message indicating an entrance to a
103  * holding bridge with a subclass type of "parking" is received, the CDR is
104  * transitioned to the Parked state.
105  *
106  * \par Dial
107  *
108  * This state represents a dial that is occurring within Asterisk. The Party A
109  * can either be the caller for a two party dial, or it can be the dialed party
110  * if the calling party is Asterisk (that is, an Originated channel). In the
111  * first case, the Party B is \em always the dialed channel; in the second case,
112  * the channel is not considered to be a "dialed" channel as it is alone in the
113  * dialed operation.
114  *
115  * While in the Dial state, multiple CDRs can be created for the Party A if a
116  * parallel dial occurs. Each dialed party receives its own CDR with Party A.
117  *
118  * The following transitions can occur while in the Dial state:
119  * \li If a \ref ast_channel_dial_type indicating a Dial End is received where
120  * the \ref dial_status is not ANSWER, the state transitions to Finalized
121  * \li If a \ref ast_channel_snapshot is received indicating that the channel
122  * has hung up, the state transitions to Finalized
123  * \li If a \ref ast_channel_dial_type indicating a Dial End is received where
124  * the \ref dial_status is ANSWER, the state transitions to DialedPending
125  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
126  * state transitions to Bridge
127  *
128  * \par DialedPending
129  *
130  * Technically, after being dialed, a CDR does not have to transition to the
131  * Bridge state. If the channel being dialed was originated, the channel may
132  * being executing dialplan. Strangely enough, it is also valid to have both
133  * Party A and Party B - after a dial - to not be bridged and instead execute
134  * dialplan. DialedPending handles the state where we figure out if the CDR
135  * showing the dial needs to move to the Bridge state; if the CDR should show
136  * that we started executing dialplan; of if we need a new CDR.
137  *
138  * The following transition can occur while in the DialedPending state:
139  * \li If a \ref ast_channel_snapshot is received that indicates that the
140  * channel has begun executing dialplan, we transition to the Finalized state
141  * if we have a Party B. Otherwise, we transition to the Single state.
142  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
143  * state transitions to Bridge (through the Dial state)
144  * \li If a \ref ast_bridge_blob_type message indicating an entrance to a
145  * holding bridge with a subclass type of "parking" is received, the CDR is
146  * transitioned to the Parked state.
147  *
148  * \par Bridge
149  *
150  * The Bridge state represents a path of communication between Party A and one
151  * or more other parties. When a CDR enters into the Bridge state, the following
152  * occurs:
153  * \li The CDR attempts to find a Party B. If the CDR has a Party B, it looks
154  * for that channel in the bridge and updates itself accordingly. If the CDR
155  * does not yet have a Party B, it attempts to find a channel that can be its
156  * Party B. If it finds one, it updates itself; otherwise, the CDR is
157  * temporarily finalized.
158  * \li Once the CDR has a Party B or it is determined that it cannot have a
159  * Party B, new CDRs are created for each pairing of channels with the CDR's
160  * Party A.
161  *
162  * As an example, consider the following:
163  * \li A Dials B - both answer
164  * \li B joins a bridge. Since no one is in the bridge and it was a dialed
165  * channel, it cannot have a Party B.
166  * \li A joins the bridge. Since A's Party B is B, A updates itself with B.
167  * \li Now say an Originated channel, C, joins the bridge. The bridge becomes
168  * a multi-party bridge.
169  * \li C attempts to get a Party B. A cannot be C's Party B, as it was created
170  * before it. B is a dialed channel and can thus be C's Party B, so C's CDR
171  * updates its Party B to B.
172  * \li New CDRs are now generated. A gets a new CDR for A -> C. B is dialed, and
173  * hence cannot get any CDR.
174  * \li Now say another Originated channel, D, joins the bridge. Say D has the
175  * \ref party_a flag set on it, such that it is always the preferred Party A.
176  * As such, it takes A as its Party B.
177  * \li New CDRs are generated. D gets new CDRs for D -> B and D -> C.
178  *
179  * The following transitions can occur while in the Bridge state:
180  * \li If a \ref ast_bridge_blob_type message indicating a leave is received,
181  * the state transitions to the Finalized state.
182  *
183  * \par Parked
184  *
185  * Parking is technically just another bridge in the Asterisk bridging
186  * framework. Unlike other bridges, however there are several key distinctions:
187  * \li With normal bridges, you want to show paths of communication between
188  * the participants. In parking, however, each participant is independent.
189  * From the perspective of a CDR, a call in parking should look like a dialplan
190  * application just executed.
191  * \li Holding bridges are typically items using in more complex applications,
192  * and so we usually don't want to show them. However, with Park, there is no
193  * application execution - often, a channel will be put directly into the
194  * holding bridge, bypassing the dialplan. This occurs when a call is blind
195  * transferred to a parking extension.
196  *
197  * As such, if a channel enters a bridge and that happens to be a holding bridge
198  * with a subclass type of "parking", we transition the CDR into the Parked
199  * state. The parking Stasis message updates the application name and data to
200  * reflect that the channel is in parking. When this occurs, a special flag is
201  * set on the CDR that prevents the application name from being updates by
202  * subsequent channel snapshot updates.
203  *
204  * The following transitions can occur while in the Parked state:
205  * \li If a \ref ast_bridge_blob_type message indicating a leave is received,
206  * the state transitions to the Finalized state
207  *
208  * \par Finalized
209  *
210  * Once a CDR enters the finalized state, it is finished. No further updates
211  * can be made to the party information, and the CDR cannot be changed.
212  *
213  * One exception to this occurs during linkedid propagation, in which the CDRs
214  * linkedids are updated based on who the channel is bridged with. In general,
215  * however, a finalized CDR is waiting for dispatch to the CDR backends.
216  */
217
218 /*! \brief CDR engine settings */
219 enum ast_cdr_settings {
220         CDR_ENABLED = 1 << 0,               /*< Enable CDRs */
221         CDR_BATCHMODE = 1 << 1,             /*< Whether or not we should dispatch CDRs in batches */
222         CDR_UNANSWERED = 1 << 2,            /*< Log unanswered CDRs */
223         CDR_CONGESTION = 1 << 3,            /*< Treat congestion as if it were a failed call */
224         CDR_END_BEFORE_H_EXTEN = 1 << 4,    /*< End the CDR before the 'h' extension runs */
225         CDR_INITIATED_SECONDS = 1 << 5,     /*< Include microseconds into the billing time */
226         CDR_DEBUG = 1 << 6,                 /*< Enables extra debug statements */
227 };
228
229 /*! \brief CDR Batch Mode settings */
230 enum ast_cdr_batch_mode_settings {
231         BATCH_MODE_SCHEDULER_ONLY = 1 << 0, /*< Don't spawn a thread to handle the batches - do it on the scheduler */
232         BATCH_MODE_SAFE_SHUTDOWN = 1 << 1,  /*< During safe shutdown, submit the batched CDRs */
233 };
234
235 /*!
236  * \brief CDR manipulation options. Certain function calls will manipulate the
237  * state of a CDR object based on these flags.
238  */
239 enum ast_cdr_options {
240         AST_CDR_FLAG_KEEP_VARS = (1 << 0),   /*< Copy variables during the operation */
241         AST_CDR_FLAG_DISABLE = (1 << 1),     /*< Disable the current CDR */
242         AST_CDR_FLAG_DISABLE_ALL = (3 << 1), /*< Disable the CDR and all future CDRs */
243         AST_CDR_FLAG_PARTY_A = (1 << 3),     /*< Set the channel as party A */
244         AST_CDR_FLAG_FINALIZE = (1 << 4),    /*< Finalize the current CDRs */
245         AST_CDR_FLAG_SET_ANSWER = (1 << 5),  /*< If the channel is answered, set the answer time to now */
246         AST_CDR_FLAG_RESET = (1 << 6),       /*< If set, set the start and answer time to now */
247         AST_CDR_LOCK_APP = (1 << 7),         /*< Prevent any further changes to the application field/data field for this CDR */
248 };
249
250 /*!
251  * \brief CDR Flags - Disposition
252  */
253 enum ast_cdr_disposition {
254         AST_CDR_NOANSWER   = 0,
255         AST_CDR_NULL       = (1 << 0),
256         AST_CDR_FAILED     = (1 << 1),
257         AST_CDR_BUSY       = (1 << 2),
258         AST_CDR_ANSWERED   = (1 << 3),
259         AST_CDR_CONGESTION = (1 << 4),
260 };
261
262
263 /*! \brief The global options available for CDRs */
264 struct ast_cdr_config {
265         struct ast_flags settings;                      /*< CDR settings */
266         struct batch_settings {
267                 unsigned int time;                              /*< Time between batches */
268                 unsigned int size;                              /*< Size to trigger a batch */
269                 struct ast_flags settings;              /*< Settings for batches */
270         } batch_settings;
271 };
272
273 /*!
274  * \brief Responsible for call detail data
275  */
276 struct ast_cdr {
277         /*! Caller*ID with text */
278         char clid[AST_MAX_EXTENSION];
279         /*! Caller*ID number */
280         char src[AST_MAX_EXTENSION];
281         /*! Destination extension */
282         char dst[AST_MAX_EXTENSION];
283         /*! Destination context */
284         char dcontext[AST_MAX_EXTENSION];
285
286         char channel[AST_MAX_EXTENSION];
287         /*! Destination channel if appropriate */
288         char dstchannel[AST_MAX_EXTENSION];
289         /*! Last application if appropriate */
290         char lastapp[AST_MAX_EXTENSION];
291         /*! Last application data */
292         char lastdata[AST_MAX_EXTENSION];
293
294         struct timeval start;
295
296         struct timeval answer;
297
298         struct timeval end;
299         /*! Total time in system, in seconds */
300         long int duration;
301         /*! Total time call is up, in seconds */
302         long int billsec;
303         /*! What happened to the call */
304         long int disposition;
305         /*! What flags to use */
306         long int amaflags;
307         /*! What account number to use */
308         char accountcode[AST_MAX_ACCOUNT_CODE];
309         /*! Account number of the last person we talked to */
310         char peeraccount[AST_MAX_ACCOUNT_CODE];
311         /*! flags */
312         unsigned int flags;
313         /*! Unique Channel Identifier */
314         char uniqueid[AST_MAX_UNIQUEID];
315         /* Linked group Identifier */
316         char linkedid[AST_MAX_UNIQUEID];
317         /*! User field */
318         char userfield[AST_MAX_USER_FIELD];
319         /*! Sequence field */
320         int sequence;
321
322         /*! A linked list for variables */
323         struct varshead varshead;
324
325         struct ast_cdr *next;
326 };
327
328 /*!
329  * \since 12
330  * \brief Obtain the current CDR configuration
331  *
332  * The configuration is a ref counted object. The caller of this function must
333  * decrement the ref count when finished with the configuration.
334  *
335  * \retval NULL on error
336  * \retval The current CDR configuration
337  */
338 struct ast_cdr_config *ast_cdr_get_config(void);
339
340 /*!
341  * \since 12
342  * \brief Set the current CDR configuration
343  *
344  * \param config The new CDR configuration
345  */
346 void ast_cdr_set_config(struct ast_cdr_config *config);
347
348 /*!
349  * \since 12
350  * \brief Format a CDR variable from an already posted CDR
351  *
352  * \param cdr The dispatched CDR to process
353  * \param name The name of the variable
354  * \param ret Pointer to the formatted buffer
355  * \param workspace A pointer to the buffer to use to format the variable
356  * \param workspacelen The size of \ref workspace
357  * \param raw If non-zero and a date/time is extraced, provide epoch seconds. Otherwise format as a date/time stamp
358  */
359 void ast_cdr_format_var(struct ast_cdr *cdr, const char *name, char **ret, char *workspace, int workspacelen, int raw);
360
361 /*!
362  * \since 12
363  * \brief Retrieve a CDR variable from a channel's current CDR
364  *
365  * \param channel_name The name of the party A channel that the CDR is associated with
366  * \param name The name of the variable to retrieve
367  * \param value Buffer to hold the value
368  * \param length The size of the buffer
369  *
370  * \retval 0 on success
371  * \retval non-zero on failure
372  */
373 int ast_cdr_getvar(const char *channel_name, const char *name, char *value, size_t length);
374
375 /*!
376  * \since 12
377  * \brief Set a variable on a CDR
378  *
379  * \param channel_name The channel to set the variable on
380  * \param name The name of the variable to set
381  * \param value The value of the variable to set
382  *
383  * \retval 0 on success
384  * \retval non-zero on failure
385  */
386 int ast_cdr_setvar(const char *channel_name, const char *name, const char *value);
387
388 /*!
389  * \since 12
390  * \brief Fork a CDR
391  *
392  * \param channel_name The name of the channel whose CDR should be forked
393  * \param options Options to control how the fork occurs.
394  *
395  * \retval 0 on success
396  * \retval -1 on failure
397  */
398 int ast_cdr_fork(const char *channel_name, struct ast_flags *options);
399
400 /*!
401  * \since 12
402  * \brief Set a property on a CDR for a channel
403  *
404  * This function sets specific administrative properties on a CDR for a channel.
405  * This includes properties like preventing a CDR from being dispatched, to
406  * setting the channel as the preferred Party A in future CDRs. See
407  * \ref enum ast_cdr_options for more information.
408  *
409  * \param channel_name The CDR's channel
410  * \param option Option to apply to the CDR
411  *
412  * \retval 0 on success
413  * \retval 1 on error
414  */
415 int ast_cdr_set_property(const char *channel_name, enum ast_cdr_options option);
416
417 /*!
418  * \since 12
419  * \brief Clear a property on a CDR for a channel
420  *
421  * Clears a flag previously set by \ref ast_cdr_set_property
422  *
423  * \param channel_name The CDR's channel
424  * \param option Option to clear from the CDR
425  *
426  * \retval 0 on success
427  * \retval 1 on error
428  */
429 int ast_cdr_clear_property(const char *channel_name, enum ast_cdr_options option);
430
431 /*!
432  * \brief Reset the detail record
433  * \param channel_name The channel that the CDR is associated with
434  * \param options Options that control what the reset operation does.
435  *
436  * Valid options are:
437  * \ref AST_CDR_FLAG_KEEP_VARS - keep the variables during the reset
438  * \ref AST_CDR_FLAG_DISABLE_ALL - when used with \ref ast_cdr_reset, re-enables
439  * the CDR
440  *
441  * \retval 0 on success
442  * \retval -1 on failure
443  */
444 int ast_cdr_reset(const char *channel_name, struct ast_flags *options);
445
446 /*!
447  * \brief Serializes all the data and variables for a current CDR record
448  * \param channel_name The channel to get the CDR for
449  * \param buf A buffer to use for formatting the data
450  * \param delim A delimeter to use to separate variable keys/values
451  * \param sep A separator to use between nestings
452  * \retval the total number of serialized variables
453  */
454 int ast_cdr_serialize_variables(const char *channel_name, struct ast_str **buf, char delim, char sep);
455
456 /*!
457  * \brief CDR backend callback
458  * \warning CDR backends should NOT attempt to access the channel associated
459  * with a CDR record.  This channel is not guaranteed to exist when the CDR
460  * backend is invoked.
461  */
462 typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
463
464 /*! \brief Return TRUE if CDR subsystem is enabled */
465 int ast_cdr_is_enabled(void);
466
467 /*!
468  * \brief Allocate a CDR record
469  * \retval a malloc'd ast_cdr structure
470  * \retval NULL on error (malloc failure)
471  */
472 struct ast_cdr *ast_cdr_alloc(void);
473
474
475 /*!
476  * \brief Duplicate a public CDR
477  * \param cdr the record to duplicate
478  *
479  * \retval a malloc'd ast_cdr structure,
480  * \retval NULL on error (malloc failure)
481  */
482 struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
483
484 /*!
485  * \brief Free a CDR record
486  * \param cdr ast_cdr structure to free
487  * Returns nothing
488  */
489 void ast_cdr_free(struct ast_cdr *cdr);
490
491 /*!
492  * \brief Register a CDR handling engine
493  * \param name name associated with the particular CDR handler
494  * \param desc description of the CDR handler
495  * \param be function pointer to a CDR handler
496  * Used to register a Call Detail Record handler.
497  * \retval 0 on success.
498  * \retval -1 on error
499  */
500 int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
501
502 /*!
503  * \brief Unregister a CDR handling engine
504  * \param name name of CDR handler to unregister
505  * Unregisters a CDR by it's name
506  *
507  * \retval 0 The backend unregistered successfully
508  * \retval -1 The backend could not be unregistered at this time
509  */
510 int ast_cdr_unregister(const char *name);
511
512 /*!
513  * \brief Suspend a CDR backend temporarily
514  *
515   * \retval 0 The backend is suspdended
516   * \retval -1 The backend could not be suspended
517   */
518 int ast_cdr_backend_suspend(const char *name);
519
520 /*!
521  * \brief Unsuspend a CDR backend
522  *
523  * \retval 0 The backend was unsuspended
524  * \retval -1 The back could not be unsuspended
525  */
526 int ast_cdr_backend_unsuspend(const char *name);
527
528 /*!
529  * \brief Disposition to a string
530  * \param disposition input binary form
531  * Converts the binary form of a disposition to string form.
532  * \return a pointer to the string form
533  */
534 const char *ast_cdr_disp2str(int disposition);
535
536 /*!
537  * \brief Set CDR user field for channel (stored in CDR)
538  *
539  * \param channel_name The name of the channel that owns the CDR
540  * \param userfield The user field to set
541  */
542 void ast_cdr_setuserfield(const char *channel_name, const char *userfield);
543
544 /*! \brief Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
545 int ast_cdr_engine_reload(void);
546
547 /*! \brief Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
548 int ast_cdr_engine_init(void);
549
550 /*! Submit any remaining CDRs and prepare for shutdown */
551 void ast_cdr_engine_term(void);
552
553 #endif /* _ASTERISK_CDR_H */