Mon Mar 20 08:25:38 2006

Asterisk developer's documentation


Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

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 /*! \file
00020  * \brief Call Detail Record API 
00021  */
00022 
00023 #ifndef _ASTERISK_CDR_H
00024 #define _ASTERISK_CDR_H
00025 
00026 #include <sys/time.h>
00027 #define AST_CDR_FLAG_KEEP_VARS         (1 << 0)
00028 #define AST_CDR_FLAG_POSTED         (1 << 1)
00029 #define AST_CDR_FLAG_LOCKED         (1 << 2)
00030 #define AST_CDR_FLAG_CHILD       (1 << 3)
00031 #define AST_CDR_FLAG_POST_DISABLED     (1 << 4)
00032 
00033 #define AST_CDR_NOANSWER         (1 << 0)
00034 #define AST_CDR_BUSY          (1 << 1)
00035 #define AST_CDR_ANSWERED         (1 << 2)
00036 #define AST_CDR_FAILED           (1 << 3)
00037 
00038 /*! AMA Flags */
00039 #define AST_CDR_OMIT          (1)
00040 #define AST_CDR_BILLING          (2)
00041 #define AST_CDR_DOCUMENTATION       (3)
00042 
00043 #define AST_MAX_USER_FIELD       256
00044 #define AST_MAX_ACCOUNT_CODE        20
00045 
00046 /* Include channel.h after relevant declarations it will need */
00047 #include "asterisk/channel.h"
00048 #include "asterisk/utils.h"
00049 
00050 struct ast_channel;
00051 
00052 /*! Responsible for call detail data */
00053 struct ast_cdr {
00054    /*! Caller*ID with text */
00055    char clid[AST_MAX_EXTENSION];
00056    /*! Caller*ID number */
00057    char src[AST_MAX_EXTENSION];     
00058    /*! Destination extension */
00059    char dst[AST_MAX_EXTENSION];     
00060    /*! Destination context */
00061    char dcontext[AST_MAX_EXTENSION];   
00062    
00063    char channel[AST_MAX_EXTENSION];
00064    /*! Destination channel if appropriate */
00065    char dstchannel[AST_MAX_EXTENSION]; 
00066    /*! Last application if appropriate */
00067    char lastapp[AST_MAX_EXTENSION]; 
00068    /*! Last application data */
00069    char lastdata[AST_MAX_EXTENSION];   
00070    
00071    struct timeval start;
00072    
00073    struct timeval answer;
00074    
00075    struct timeval end;
00076    /*! Total time in system, in seconds */
00077    long int duration;            
00078    /*! Total time call is up, in seconds */
00079    long int billsec;          
00080    /*! What happened to the call */
00081    long int disposition;         
00082    /*! What flags to use */
00083    long int amaflags;            
00084    /*! What account number to use */
00085    char accountcode[AST_MAX_ACCOUNT_CODE];         
00086    /*! flags */
00087    unsigned int flags;           
00088    /* Unique Channel Identifier */
00089    char uniqueid[32];
00090    /* User field */
00091    char userfield[AST_MAX_USER_FIELD];
00092 
00093    /* A linked list for variables */
00094    struct varshead varshead;
00095 
00096    struct ast_cdr *next;
00097 };
00098 
00099 extern void ast_cdr_getvar(struct ast_cdr *cdr, const char *name, char **ret, char *workspace, int workspacelen, int recur);
00100 extern int ast_cdr_setvar(struct ast_cdr *cdr, const char *name, const char *value, int recur);
00101 extern int ast_cdr_serialize_variables(struct ast_cdr *cdr, char *buf, size_t size, char delim, char sep, int recur);
00102 extern void ast_cdr_free_vars(struct ast_cdr *cdr, int recur);
00103 extern int ast_cdr_copy_vars(struct ast_cdr *to_cdr, struct ast_cdr *from_cdr);
00104 
00105 typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
00106 
00107 /*! \brief Allocate a CDR record 
00108  * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
00109  */
00110 extern struct ast_cdr *ast_cdr_alloc(void);
00111 
00112 /*! \brief Duplicate a record 
00113  * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
00114  */
00115 extern struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
00116 
00117 /*! \brief Free a CDR record 
00118  * \param cdr ast_cdr structure to free
00119  * Returns nothing important
00120  */
00121 extern void ast_cdr_free(struct ast_cdr *cdr);
00122 
00123 /*! \brief Initialize based on a channel
00124  * \param cdr Call Detail Record to use for channel
00125  * \param chan Channel to bind CDR with
00126  * Initializes a CDR and associates it with a particular channel
00127  * Return is negligible.  (returns 0 by default)
00128  */
00129 extern int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
00130 
00131 /*! Initialize based on a channel */
00132 /*! 
00133  * \param cdr Call Detail Record to use for channel
00134  * \param chan Channel to bind CDR with
00135  * Initializes a CDR and associates it with a particular channel
00136  * Return is negligible.  (returns 0 by default)
00137  */
00138 extern int ast_cdr_setcid(struct ast_cdr *cdr, struct ast_channel *chan);
00139 
00140 /*! Register a CDR handling engine */
00141 /*!
00142  * \param name name associated with the particular CDR handler
00143  * \param desc description of the CDR handler
00144  * \param be function pointer to a CDR handler
00145  * Used to register a Call Detail Record handler.
00146  * Returns -1 on error, 0 on success.
00147  */
00148 extern int ast_cdr_register(char *name, char *desc, ast_cdrbe be);
00149 
00150 /*! Unregister a CDR handling engine */
00151 /*!
00152  * \param name name of CDR handler to unregister
00153  * Unregisters a CDR by it's name
00154  */
00155 extern void ast_cdr_unregister(char *name);
00156 
00157 /*! Start a call */
00158 /*!
00159  * \param cdr the cdr you wish to associate with the call
00160  * Starts all CDR stuff necessary for monitoring a call
00161  * Returns nothing important
00162  */
00163 extern void ast_cdr_start(struct ast_cdr *cdr);
00164 
00165 /*! Answer a call */
00166 /*!
00167  * \param cdr the cdr you wish to associate with the call
00168  * Starts all CDR stuff necessary for doing CDR when answering a call
00169  */
00170 extern void ast_cdr_answer(struct ast_cdr *cdr);
00171 
00172 /*! Busy a call */
00173 /*!
00174  * \param cdr the cdr you wish to associate with the call
00175  * Returns nothing important
00176  */
00177 extern void ast_cdr_busy(struct ast_cdr *cdr);
00178 
00179 /*! Fail a call */
00180 /*!
00181  * \param cdr the cdr you wish to associate with the call
00182  * Returns nothing important
00183  */
00184 extern void ast_cdr_failed(struct ast_cdr *cdr);
00185 
00186 /*! Save the result of the call based on the AST_CAUSE_* */
00187 /*!
00188  * \param cdr the cdr you wish to associate with the call
00189  * Returns nothing important
00190  * \param cause the AST_CAUSE_*
00191  */
00192 extern int ast_cdr_disposition(struct ast_cdr *cdr, int cause);
00193    
00194 /*! End a call */
00195 /*!
00196  * \param cdr the cdr you have associated the call with
00197  * Registers the end of call time in the cdr structure.
00198  * Returns nothing important
00199  */
00200 extern void ast_cdr_end(struct ast_cdr *cdr);
00201 
00202 /*! Detaches the detail record for posting (and freeing) either now or at a
00203  * later time in bulk with other records during batch mode operation */
00204 /*! 
00205  * \param cdr Which CDR to detach from the channel thread
00206  * Prevents the channel thread from blocking on the CDR handling
00207  * Returns nothing
00208  */
00209 extern void ast_cdr_detach(struct ast_cdr *cdr);
00210 
00211 /*! Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines */
00212 /*!
00213  * \param shutdown Whether or not we are shutting down
00214  * Blocks the asterisk shutdown procedures until the CDR data is submitted.
00215  * Returns nothing
00216  */
00217 extern void ast_cdr_submit_batch(int shutdown);
00218 
00219 /*! Set the destination channel, if there was one */
00220 /*!
00221  * \param cdr Which cdr it's applied to
00222  * \param chan Channel to which dest will be
00223  * Sets the destination channel the CDR is applied to
00224  * Returns nothing
00225  */
00226 extern void ast_cdr_setdestchan(struct ast_cdr *cdr, char *chan);
00227 
00228 /*! Set the last executed application */
00229 /*!
00230  * \param cdr which cdr to act upon
00231  * \param app the name of the app you wish to change it to
00232  * \param data the data you want in the data field of app you set it to
00233  * Changes the value of the last executed app
00234  * Returns nothing
00235  */
00236 extern void ast_cdr_setapp(struct ast_cdr *cdr, char *app, char *data);
00237 
00238 /*! Convert a string to a detail record AMA flag */
00239 /*!
00240  * \param flag string form of flag
00241  * Converts the string form of the flag to the binary form.
00242  * Returns the binary form of the flag
00243  */
00244 extern int ast_cdr_amaflags2int(const char *flag);
00245 
00246 /*! Disposition to a string */
00247 /*!
00248  * \param disposition input binary form
00249  * Converts the binary form of a disposition to string form.
00250  * Returns a pointer to the string form
00251  */
00252 extern char *ast_cdr_disp2str(int disposition);
00253 
00254 /*! Reset the detail record, optionally posting it first */
00255 /*!
00256  * \param cdr which cdr to act upon
00257  * \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
00258  *              |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
00259  */
00260 extern void ast_cdr_reset(struct ast_cdr *cdr, struct ast_flags *flags);
00261 
00262 /*! Flags to a string */
00263 /*!
00264  * \param flags binary flag
00265  * Converts binary flags to string flags
00266  * Returns string with flag name
00267  */
00268 extern char *ast_cdr_flags2str(int flags);
00269 
00270 extern int ast_cdr_setaccount(struct ast_channel *chan, const char *account);
00271 extern int ast_cdr_setamaflags(struct ast_channel *chan, const char *amaflags);
00272 
00273 
00274 extern int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
00275 extern int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
00276 
00277 
00278 /* Update CDR on a channel */
00279 extern int ast_cdr_update(struct ast_channel *chan);
00280 
00281 
00282 extern int ast_default_amaflags;
00283 
00284 extern char ast_default_accountcode[AST_MAX_ACCOUNT_CODE];
00285 
00286 extern struct ast_cdr *ast_cdr_append(struct ast_cdr *cdr, struct ast_cdr *newcdr);
00287 
00288 /*! Reload the configuration file cdr.conf and start/stop CDR scheduling thread */
00289 extern void ast_cdr_engine_reload(void);
00290 
00291 /*! Load the configuration file cdr.conf and possibly start the CDR scheduling thread */
00292 extern int ast_cdr_engine_init(void);
00293 
00294 /*! Submit any remaining CDRs and prepare for shutdown */
00295 extern void ast_cdr_engine_term(void);
00296 
00297 #endif /* _ASTERISK_CDR_H */

Generated on Mon Mar 20 08:25:38 2006 for Asterisk - the Open Source PBX by  doxygen 1.3.9.1