cdr.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \brief Call Detail Record API
00022  *
00023  * \author Mark Spencer <markster@digium.com>
00024  */
00025 
00026 #ifndef _ASTERISK_CDR_H
00027 #define _ASTERISK_CDR_H
00028 
00029 #include "asterisk/channel.h"
00030 
00031 /*! \file
00032  *
00033  * \since 12
00034  *
00035  * \brief Call Detail Record Engine.
00036  *
00037  * \page CDR Call Detail Record Engine
00038  *
00039  * \par Intro
00040  *
00041  * The Call Detail Record (CDR) engine uses the \ref stasis Stasis Message Bus
00042  * to build records for the channels in Asterisk. As the state of a channel and
00043  * the bridges it participates in changes, notifications are sent over the
00044  * Stasis Message Bus. The CDR engine consumes these notifications and builds
00045  * records that reflect that state. Over the lifetime of a channel, many CDRs
00046  * may be generated for that channel or that involve that channel.
00047  *
00048  * CDRs have a lifecycle that is a subset of the channel that they reflect. A
00049  * single CDR for a channel represents a path of communication between the
00050  * endpoint behind a channel and Asterisk, or between two endpoints. When a
00051  * channel establishes a new path of communication, a new CDR is created for the
00052  * channel. Likewise, when a path of communication is terminated, a CDR is
00053  * finalized. Finally, when a channel is no longer present in Asterisk, all CDRs
00054  * for that channel are dispatched for recording.
00055  *
00056  * Dispatching of CDRs occurs to registered CDR backends. CDR backends register
00057  * through \ref ast_cdr_register and are responsible for taking the produced
00058  * CDRs and storing them in permanent storage.
00059  *
00060  * \par CDR attributes
00061  *
00062  * While a CDR can have many attributes, all CDRs have two parties: a Party A
00063  * and a Party B. The Party A is \em always the channel that owns the CDR. A CDR
00064  * may or may not have a Party B, depending on its state.
00065  *
00066  * For the most part, attributes on a CDR are reflective of those same
00067  * attributes on the channel at the time when the CDR was finalized. Specific
00068  * CDR attributes include:
00069  * \li \c start The time when the CDR was created
00070  * \li \c answer The time when the Party A was answered, or when the path of
00071  * communication between Party A and Party B was established
00072  * \li \c end The time when the CDR was finalized
00073  * \li \c duration \c end - \c start. If \c end is not known, the current time
00074  * is used
00075  * \li \c billsec \c end - \c answer. If \c end is not known, the current time
00076  * is used
00077  * \li \c userfield User set data on some party in the CDR
00078  *
00079  * Note that \c accountcode and \c amaflags are actually properties of a
00080  * channel, not the CDR.
00081  *
00082  * \par CDR States
00083  *
00084  * CDRs go through various states during their lifetime. State transitions occur
00085  * due to messages received over the \ref stasis Stasis Message Bus. The
00086  * following describes the possible states a CDR can be in, and how it
00087  * transitions through the states.
00088  *
00089  * \par Single
00090  *
00091  * When a CDR is created, it is put into the Single state. The Single state
00092  * represents a CDR for a channel that has no Party B. CDRs can be unanswered
00093  * or answered while in the Single state.
00094  *
00095  * The following transitions can occur while in the Single state:
00096  * \li If a \ref ast_channel_dial_type indicating a Dial Begin is received, the
00097  * state transitions to Dial
00098  * \li If a \ref ast_channel_snapshot is received indicating that the channel
00099  * has hung up, the state transitions to Finalized
00100  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
00101  * state transitions to Bridge
00102  * \li If a \ref ast_bridge_blob_type message indicating an entrance to a
00103  * holding bridge with a subclass type of "parking" is received, the CDR is
00104  * transitioned to the Parked state.
00105  *
00106  * \par Dial
00107  *
00108  * This state represents a dial that is occurring within Asterisk. The Party A
00109  * can either be the caller for a two party dial, or it can be the dialed party
00110  * if the calling party is Asterisk (that is, an Originated channel). In the
00111  * first case, the Party B is \em always the dialed channel; in the second case,
00112  * the channel is not considered to be a "dialed" channel as it is alone in the
00113  * dialed operation.
00114  *
00115  * While in the Dial state, multiple CDRs can be created for the Party A if a
00116  * parallel dial occurs. Each dialed party receives its own CDR with Party A.
00117  *
00118  * The following transitions can occur while in the Dial state:
00119  * \li If a \ref ast_channel_dial_type indicating a Dial End is received where
00120  * the \ref dial_status is not ANSWER, the state transitions to Finalized
00121  * \li If a \ref ast_channel_snapshot is received indicating that the channel
00122  * has hung up, the state transitions to Finalized
00123  * \li If a \ref ast_channel_dial_type indicating a Dial End is received where
00124  * the \ref dial_status is ANSWER, the state transitions to DialedPending
00125  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
00126  * state transitions to Bridge
00127  *
00128  * \par DialedPending
00129  *
00130  * Technically, after being dialed, a CDR does not have to transition to the
00131  * Bridge state. If the channel being dialed was originated, the channel may
00132  * being executing dialplan. Strangely enough, it is also valid to have both
00133  * Party A and Party B - after a dial - to not be bridged and instead execute
00134  * dialplan. DialedPending handles the state where we figure out if the CDR
00135  * showing the dial needs to move to the Bridge state; if the CDR should show
00136  * that we started executing dialplan; of if we need a new CDR.
00137  *
00138  * The following transition can occur while in the DialedPending state:
00139  * \li If a \ref ast_channel_snapshot is received that indicates that the
00140  * channel has begun executing dialplan, we transition to the Finalized state
00141  * if we have a Party B. Otherwise, we transition to the Single state.
00142  * \li If a \ref ast_bridge_blob_type is received indicating a Bridge Enter, the
00143  * state transitions to Bridge (through the Dial state)
00144  * \li If a \ref ast_bridge_blob_type message indicating an entrance to a
00145  * holding bridge with a subclass type of "parking" is received, the CDR is
00146  * transitioned to the Parked state.
00147  *
00148  * \par Bridge
00149  *
00150  * The Bridge state represents a path of communication between Party A and one
00151  * or more other parties. When a CDR enters into the Bridge state, the following
00152  * occurs:
00153  * \li The CDR attempts to find a Party B. If the CDR has a Party B, it looks
00154  * for that channel in the bridge and updates itself accordingly. If the CDR
00155  * does not yet have a Party B, it attempts to find a channel that can be its
00156  * Party B. If it finds one, it updates itself; otherwise, the CDR is
00157  * temporarily finalized.
00158  * \li Once the CDR has a Party B or it is determined that it cannot have a
00159  * Party B, new CDRs are created for each pairing of channels with the CDR's
00160  * Party A.
00161  *
00162  * As an example, consider the following:
00163  * \li A Dials B - both answer
00164  * \li B joins a bridge. Since no one is in the bridge and it was a dialed
00165  * channel, it cannot have a Party B.
00166  * \li A joins the bridge. Since A's Party B is B, A updates itself with B.
00167  * \li Now say an Originated channel, C, joins the bridge. The bridge becomes
00168  * a multi-party bridge.
00169  * \li C attempts to get a Party B. A cannot be C's Party B, as it was created
00170  * before it. B is a dialed channel and can thus be C's Party B, so C's CDR
00171  * updates its Party B to B.
00172  * \li New CDRs are now generated. A gets a new CDR for A -> C. B is dialed, and
00173  * hence cannot get any CDR.
00174  * \li Now say another Originated channel, D, joins the bridge. Say D has the
00175  * \ref party_a flag set on it, such that it is always the preferred Party A.
00176  * As such, it takes A as its Party B.
00177  * \li New CDRs are generated. D gets new CDRs for D -> B and D -> C.
00178  *
00179  * The following transitions can occur while in the Bridge state:
00180  * \li If a \ref ast_bridge_blob_type message indicating a leave is received,
00181  * the state transitions to the Finalized state.
00182  *
00183  * \par Parked
00184  *
00185  * Parking is technically just another bridge in the Asterisk bridging
00186  * framework. Unlike other bridges, however there are several key distinctions:
00187  * \li With normal bridges, you want to show paths of communication between
00188  * the participants. In parking, however, each participant is independent.
00189  * From the perspective of a CDR, a call in parking should look like a dialplan
00190  * application just executed.
00191  * \li Holding bridges are typically items using in more complex applications,
00192  * and so we usually don't want to show them. However, with Park, there is no
00193  * application execution - often, a channel will be put directly into the
00194  * holding bridge, bypassing the dialplan. This occurs when a call is blind
00195  * transferred to a parking extension.
00196  *
00197  * As such, if a channel enters a bridge and that happens to be a holding bridge
00198  * with a subclass type of "parking", we transition the CDR into the Parked
00199  * state. The parking Stasis message updates the application name and data to
00200  * reflect that the channel is in parking. When this occurs, a special flag is
00201  * set on the CDR that prevents the application name from being updates by
00202  * subsequent channel snapshot updates.
00203  *
00204  * The following transitions can occur while in the Parked state:
00205  * \li If a \ref ast_bridge_blob_type message indicating a leave is received,
00206  * the state transitions to the Finalized state
00207  *
00208  * \par Finalized
00209  *
00210  * Once a CDR enters the finalized state, it is finished. No further updates
00211  * can be made to the party information, and the CDR cannot be changed.
00212  *
00213  * One exception to this occurs during linkedid propagation, in which the CDRs
00214  * linkedids are updated based on who the channel is bridged with. In general,
00215  * however, a finalized CDR is waiting for dispatch to the CDR backends.
00216  */
00217 
00218 /*! \brief CDR engine settings */
00219 enum ast_cdr_settings {
00220    CDR_ENABLED = 1 << 0,               /*< Enable CDRs */
00221    CDR_BATCHMODE = 1 << 1,             /*< Whether or not we should dispatch CDRs in batches */
00222    CDR_UNANSWERED = 1 << 2,            /*< Log unanswered CDRs */
00223    CDR_CONGESTION = 1 << 3,            /*< Treat congestion as if it were a failed call */
00224    CDR_END_BEFORE_H_EXTEN = 1 << 4,    /*< End the CDR before the 'h' extension runs */
00225    CDR_INITIATED_SECONDS = 1 << 5,     /*< Include microseconds into the billing time */
00226    CDR_DEBUG = 1 << 6,                 /*< Enables extra debug statements */
00227 };
00228 
00229 /*! \brief CDR Batch Mode settings */
00230 enum ast_cdr_batch_mode_settings {
00231    BATCH_MODE_SCHEDULER_ONLY = 1 << 0, /*< Don't spawn a thread to handle the batches - do it on the scheduler */
00232    BATCH_MODE_SAFE_SHUTDOWN = 1 << 1,  /*< During safe shutdown, submit the batched CDRs */
00233 };
00234 
00235 /*!
00236  * \brief CDR manipulation options. Certain function calls will manipulate the
00237  * state of a CDR object based on these flags.
00238  */
00239 enum ast_cdr_options {
00240    AST_CDR_FLAG_KEEP_VARS = (1 << 0),   /*< Copy variables during the operation */
00241    AST_CDR_FLAG_DISABLE = (1 << 1),     /*< Disable the current CDR */
00242    AST_CDR_FLAG_DISABLE_ALL = (3 << 1), /*< Disable the CDR and all future CDRs */
00243    AST_CDR_FLAG_PARTY_A = (1 << 3),     /*< Set the channel as party A */
00244    AST_CDR_FLAG_FINALIZE = (1 << 4),    /*< Finalize the current CDRs */
00245    AST_CDR_FLAG_SET_ANSWER = (1 << 5),  /*< If the channel is answered, set the answer time to now */
00246    AST_CDR_FLAG_RESET = (1 << 6),       /*< If set, set the start and answer time to now */
00247    AST_CDR_LOCK_APP = (1 << 7),         /*< Prevent any further changes to the application field/data field for this CDR */
00248 };
00249 
00250 /*!
00251  * \brief CDR Flags - Disposition
00252  */
00253 enum ast_cdr_disposition {
00254    AST_CDR_NOANSWER   = 0,
00255    AST_CDR_NULL       = (1 << 0),
00256    AST_CDR_FAILED     = (1 << 1),
00257    AST_CDR_BUSY       = (1 << 2),
00258    AST_CDR_ANSWERED   = (1 << 3),
00259    AST_CDR_CONGESTION = (1 << 4),
00260 };
00261 
00262 
00263 /*! \brief The global options available for CDRs */
00264 struct ast_cdr_config {
00265    struct ast_flags settings;       /*< CDR settings */
00266    struct batch_settings {
00267       unsigned int time;            /*< Time between batches */
00268       unsigned int size;            /*< Size to trigger a batch */
00269       struct ast_flags settings;    /*< Settings for batches */
00270    } batch_settings;
00271 };
00272 
00273 /*!
00274  * \brief Responsible for call detail data
00275  */
00276 struct ast_cdr {
00277    /*! Caller*ID with text */
00278    char clid[AST_MAX_EXTENSION];
00279    /*! Caller*ID number */
00280    char src[AST_MAX_EXTENSION];
00281    /*! Destination extension */
00282    char dst[AST_MAX_EXTENSION];
00283    /*! Destination context */
00284    char dcontext[AST_MAX_EXTENSION];
00285 
00286    char channel[AST_MAX_EXTENSION];
00287    /*! Destination channel if appropriate */
00288    char dstchannel[AST_MAX_EXTENSION];
00289    /*! Last application if appropriate */
00290    char lastapp[AST_MAX_EXTENSION];
00291    /*! Last application data */
00292    char lastdata[AST_MAX_EXTENSION];
00293 
00294    struct timeval start;
00295 
00296    struct timeval answer;
00297 
00298    struct timeval end;
00299    /*! Total time in system, in seconds */
00300    long int duration;
00301    /*! Total time call is up, in seconds */
00302    long int billsec;
00303    /*! What happened to the call */
00304    long int disposition;
00305    /*! What flags to use */
00306    long int amaflags;
00307    /*! What account number to use */
00308    char accountcode[AST_MAX_ACCOUNT_CODE];
00309    /*! Account number of the last person we talked to */
00310    char peeraccount[AST_MAX_ACCOUNT_CODE];
00311    /*! flags */
00312    unsigned int flags;
00313    /*! Unique Channel Identifier */
00314    char uniqueid[AST_MAX_UNIQUEID];
00315    /* Linked group Identifier */
00316    char linkedid[AST_MAX_UNIQUEID];
00317    /*! User field */
00318    char userfield[AST_MAX_USER_FIELD];
00319    /*! Sequence field */
00320    int sequence;
00321 
00322    /*! A linked list for variables */
00323    struct varshead varshead;
00324 
00325    struct ast_cdr *next;
00326 };
00327 
00328 /*!
00329  * \since 12
00330  * \brief Obtain the current CDR configuration
00331  *
00332  * The configuration is a ref counted object. The caller of this function must
00333  * decrement the ref count when finished with the configuration.
00334  *
00335  * \retval NULL on error
00336  * \retval The current CDR configuration
00337  */
00338 struct ast_cdr_config *ast_cdr_get_config(void);
00339 
00340 /*!
00341  * \since 12
00342  * \brief Set the current CDR configuration
00343  *
00344  * \param config The new CDR configuration
00345  */
00346 void ast_cdr_set_config(struct ast_cdr_config *config);
00347 
00348 /*!
00349  * \since 12
00350  * \brief Format a CDR variable from an already posted CDR
00351  *
00352  * \param cdr The dispatched CDR to process
00353  * \param name The name of the variable
00354  * \param ret Pointer to the formatted buffer
00355  * \param workspace A pointer to the buffer to use to format the variable
00356  * \param workspacelen The size of \ref workspace
00357  * \param raw If non-zero and a date/time is extraced, provide epoch seconds. Otherwise format as a date/time stamp
00358  */
00359 void ast_cdr_format_var(struct ast_cdr *cdr, const char *name, char **ret, char *workspace, int workspacelen, int raw);
00360 
00361 /*!
00362  * \since 12
00363  * \brief Retrieve a CDR variable from a channel's current CDR
00364  *
00365  * \param channel_name The name of the party A channel that the CDR is associated with
00366  * \param name The name of the variable to retrieve
00367  * \param value Buffer to hold the value
00368  * \param length The size of the buffer
00369  *
00370  * \retval 0 on success
00371  * \retval non-zero on failure
00372  */
00373 int ast_cdr_getvar(const char *channel_name, const char *name, char *value, size_t length);
00374 
00375 /*!
00376  * \since 12
00377  * \brief Set a variable on a CDR
00378  *
00379  * \param channel_name The channel to set the variable on
00380  * \param name The name of the variable to set
00381  * \param value The value of the variable to set
00382  *
00383  * \retval 0 on success
00384  * \retval non-zero on failure
00385  */
00386 int ast_cdr_setvar(const char *channel_name, const char *name, const char *value);
00387 
00388 /*!
00389  * \since 12
00390  * \brief Fork a CDR
00391  *
00392  * \param channel_name The name of the channel whose CDR should be forked
00393  * \param options Options to control how the fork occurs.
00394  *
00395  * \retval 0 on success
00396  * \retval -1 on failure
00397  */
00398 int ast_cdr_fork(const char *channel_name, struct ast_flags *options);
00399 
00400 /*!
00401  * \since 12
00402  * \brief Set a property on a CDR for a channel
00403  *
00404  * This function sets specific administrative properties on a CDR for a channel.
00405  * This includes properties like preventing a CDR from being dispatched, to
00406  * setting the channel as the preferred Party A in future CDRs. See
00407  * \ref enum ast_cdr_options for more information.
00408  *
00409  * \param channel_name The CDR's channel
00410  * \param option Option to apply to the CDR
00411  *
00412  * \retval 0 on success
00413  * \retval 1 on error
00414  */
00415 int ast_cdr_set_property(const char *channel_name, enum ast_cdr_options option);
00416 
00417 /*!
00418  * \since 12
00419  * \brief Clear a property on a CDR for a channel
00420  *
00421  * Clears a flag previously set by \ref ast_cdr_set_property
00422  *
00423  * \param channel_name The CDR's channel
00424  * \param option Option to clear from the CDR
00425  *
00426  * \retval 0 on success
00427  * \retval 1 on error
00428  */
00429 int ast_cdr_clear_property(const char *channel_name, enum ast_cdr_options option);
00430 
00431 /*!
00432  * \brief Reset the detail record
00433  * \param channel_name The channel that the CDR is associated with
00434  * \param keep_variables Keep the variables during the reset. If zero,
00435  *        variables are discarded during the reset.
00436  *
00437  * \retval 0 on success
00438  * \retval -1 on failure
00439  */
00440 int ast_cdr_reset(const char *channel_name, int keep_variables);
00441 
00442 /*!
00443  * \brief Serializes all the data and variables for a current CDR record
00444  * \param channel_name The channel to get the CDR for
00445  * \param buf A buffer to use for formatting the data
00446  * \param delim A delimeter to use to separate variable keys/values
00447  * \param sep A separator to use between nestings
00448  * \retval the total number of serialized variables
00449  */
00450 int ast_cdr_serialize_variables(const char *channel_name, struct ast_str **buf, char delim, char sep);
00451 
00452 /*!
00453  * \brief CDR backend callback
00454  * \warning CDR backends should NOT attempt to access the channel associated
00455  * with a CDR record.  This channel is not guaranteed to exist when the CDR
00456  * backend is invoked.
00457  */
00458 typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
00459 
00460 /*! \brief Return TRUE if CDR subsystem is enabled */
00461 int ast_cdr_is_enabled(void);
00462 
00463 /*!
00464  * \brief Allocate a CDR record
00465  * \retval a malloc'd ast_cdr structure
00466  * \retval NULL on error (malloc failure)
00467  */
00468 struct ast_cdr *ast_cdr_alloc(void);
00469 
00470 struct stasis_message_router;
00471 
00472 /*!
00473  * \brief Return the message router for the CDR engine
00474  *
00475  * This returns the \ref stasis_message_router that the CDR engine
00476  * uses for dispatching \ref stasis messages. The reference on the
00477  * message router is bumped and must be released by the caller of
00478  * this function.
00479  *
00480  * \retval NULL if the CDR engine is disabled or unavailable
00481  * \retval the \ref stasis_message_router otherwise
00482  */
00483 struct stasis_message_router *ast_cdr_message_router(void);
00484 
00485 /*!
00486  * \brief Duplicate a public CDR
00487  * \param cdr the record to duplicate
00488  *
00489  * \retval a malloc'd ast_cdr structure,
00490  * \retval NULL on error (malloc failure)
00491  */
00492 struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
00493 
00494 /*!
00495  * \brief Free a CDR record
00496  * \param cdr ast_cdr structure to free
00497  * Returns nothing
00498  */
00499 void ast_cdr_free(struct ast_cdr *cdr);
00500 
00501 /*!
00502  * \brief Register a CDR handling engine
00503  * \param name name associated with the particular CDR handler
00504  * \param desc description of the CDR handler
00505  * \param be function pointer to a CDR handler
00506  * Used to register a Call Detail Record handler.
00507  * \retval 0 on success.
00508  * \retval -1 on error
00509  */
00510 int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
00511 
00512 /*!
00513  * \brief Unregister a CDR handling engine
00514  * \param name name of CDR handler to unregister
00515  * Unregisters a CDR by it's name
00516  *
00517  * \retval 0 The backend unregistered successfully
00518  * \retval -1 The backend could not be unregistered at this time
00519  */
00520 int ast_cdr_unregister(const char *name);
00521 
00522 /*!
00523  * \brief Suspend a CDR backend temporarily
00524  *
00525   * \retval 0 The backend is suspdended
00526   * \retval -1 The backend could not be suspended
00527   */
00528 int ast_cdr_backend_suspend(const char *name);
00529 
00530 /*!
00531  * \brief Unsuspend a CDR backend
00532  *
00533  * \retval 0 The backend was unsuspended
00534  * \retval -1 The back could not be unsuspended
00535  */
00536 int ast_cdr_backend_unsuspend(const char *name);
00537 
00538 /*!
00539  * \brief Disposition to a string
00540  * \param disposition input binary form
00541  * Converts the binary form of a disposition to string form.
00542  * \return a pointer to the string form
00543  */
00544 const char *ast_cdr_disp2str(int disposition);
00545 
00546 /*!
00547  * \brief Set CDR user field for channel (stored in CDR)
00548  *
00549  * \param channel_name The name of the channel that owns the CDR
00550  * \param userfield The user field to set
00551  */
00552 void ast_cdr_setuserfield(const char *channel_name, const char *userfield);
00553 
00554 /*! \brief Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
00555 int ast_cdr_engine_reload(void);
00556 
00557 /*! \brief Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
00558 int ast_cdr_engine_init(void);
00559 
00560 /*! Submit any remaining CDRs and prepare for shutdown */
00561 void ast_cdr_engine_term(void);
00562 
00563 #endif /* _ASTERISK_CDR_H */

Generated on Thu Apr 16 06:27:17 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6