00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2008 - 2009, Digium, Inc. 00005 * 00006 * See http://www.asterisk.org for more information about 00007 * the Asterisk project. Please do not directly contact 00008 * any of the maintainers of this project for assistance; 00009 * the project provides a web site, mailing lists and IRC 00010 * channels for your use. 00011 * 00012 * This program is free software, distributed under the terms of 00013 * the GNU General Public License Version 2. See the LICENSE file 00014 * at the top of the source tree. 00015 */ 00016 00017 /*! 00018 * \file 00019 * \brief Call Event Logging API 00020 */ 00021 00022 #ifndef __AST_CEL_H__ 00023 #define __AST_CEL_H__ 00024 00025 #if defined(__cplusplus) || defined(c_plusplus) 00026 extern "C" { 00027 #endif 00028 00029 #include "asterisk/event.h" 00030 00031 /*! 00032 * \brief AMA Flags 00033 * 00034 * \note This must much up with the AST_CDR_* defines for AMA flags. 00035 */ 00036 enum ast_cel_ama_flag { 00037 AST_CEL_AMA_FLAG_NONE, 00038 AST_CEL_AMA_FLAG_OMIT, 00039 AST_CEL_AMA_FLAG_BILLING, 00040 AST_CEL_AMA_FLAG_DOCUMENTATION, 00041 /*! \brief Must be final entry */ 00042 AST_CEL_AMA_FLAG_TOTAL, 00043 }; 00044 00045 /*! 00046 * \brief CEL event types 00047 */ 00048 enum ast_cel_event_type { 00049 /*! \brief channel birth */ 00050 AST_CEL_CHANNEL_START = 1, 00051 /*! \brief channel end */ 00052 AST_CEL_CHANNEL_END = 2, 00053 /*! \brief hangup terminates connection */ 00054 AST_CEL_HANGUP = 3, 00055 /*! \brief A ringing phone is answered */ 00056 AST_CEL_ANSWER = 4, 00057 /*! \brief an app starts */ 00058 AST_CEL_APP_START = 5, 00059 /*! \brief an app ends */ 00060 AST_CEL_APP_END = 6, 00061 /*! \brief a bridge is established */ 00062 AST_CEL_BRIDGE_START = 7, 00063 /*! \brief a bridge is torn down */ 00064 AST_CEL_BRIDGE_END = 8, 00065 /*! \brief a conference is started */ 00066 AST_CEL_CONF_START = 9, 00067 /*! \brief a conference is ended */ 00068 AST_CEL_CONF_END = 10, 00069 /*! \brief a channel is parked */ 00070 AST_CEL_PARK_START = 11, 00071 /*! \brief channel out of the park */ 00072 AST_CEL_PARK_END = 12, 00073 /*! \brief a transfer occurs */ 00074 AST_CEL_BLINDTRANSFER = 13, 00075 /*! \brief a transfer occurs */ 00076 AST_CEL_ATTENDEDTRANSFER = 14, 00077 /*! \brief a transfer occurs */ 00078 AST_CEL_TRANSFER = 15, 00079 /*! \brief a 3-way conference, usually part of a transfer */ 00080 AST_CEL_HOOKFLASH = 16, 00081 /*! \brief a 3-way conference, usually part of a transfer */ 00082 AST_CEL_3WAY_START = 17, 00083 /*! \brief a 3-way conference, usually part of a transfer */ 00084 AST_CEL_3WAY_END = 18, 00085 /*! \brief channel enters a conference */ 00086 AST_CEL_CONF_ENTER = 19, 00087 /*! \brief channel exits a conference */ 00088 AST_CEL_CONF_EXIT = 20, 00089 /*! \brief a user-defined event, the event name field should be set */ 00090 AST_CEL_USER_DEFINED = 21, 00091 /*! \brief the last channel with the given linkedid is retired */ 00092 AST_CEL_LINKEDID_END = 22, 00093 /*! \brief a masquerade happened to alter the participants on a bridge */ 00094 AST_CEL_BRIDGE_UPDATE = 23, 00095 /*! \brief a directed pickup was performed on this channel */ 00096 AST_CEL_PICKUP = 24, 00097 /*! \brief this call was forwarded somewhere else */ 00098 AST_CEL_FORWARD = 25, 00099 }; 00100 00101 /*! 00102 * \brief Check to see if CEL is enabled 00103 * 00104 * \since 1.8 00105 * 00106 * \retval zero not enabled 00107 * \retval non-zero enabled 00108 */ 00109 unsigned int ast_cel_check_enabled(void); 00110 00111 /*! 00112 * \brief Allocate a CEL record 00113 * 00114 * \since 1.8 00115 * 00116 * \note The CEL record must be destroyed with ast_cel_destroy(). 00117 * 00118 * \retval non-NULL an allocated ast_cel structure 00119 * \retval NULL error 00120 */ 00121 struct ast_cel *ast_cel_alloc(void); 00122 00123 /*! 00124 * \brief Destroy a CEL record. 00125 * 00126 * \param cel the record to destroy 00127 * 00128 * \since 1.8 00129 * 00130 * \return nothing. 00131 */ 00132 void ast_cel_destroy(struct ast_cel *cel); 00133 00134 /*! 00135 * \brief Get the name of a CEL event type 00136 * 00137 * \param type the type to get the name of 00138 * 00139 * \since 1.8 00140 * 00141 * \return the string representation of the type 00142 */ 00143 const char *ast_cel_get_type_name(enum ast_cel_event_type type); 00144 00145 /*! 00146 * \brief Get the event type from a string 00147 * 00148 * \param name the event type name as a string 00149 * 00150 * \since 1.8 00151 * 00152 * \return the ast_cel_event_type given by the string 00153 */ 00154 enum ast_cel_event_type ast_cel_str_to_event_type(const char *name); 00155 00156 /*! 00157 * \brief Convert AMA flag to printable string 00158 * 00159 * \param[in] flag the flag to convert to a string 00160 * 00161 * \since 1.8 00162 * 00163 * \return the string representation of the flag 00164 */ 00165 const char *ast_cel_get_ama_flag_name(enum ast_cel_ama_flag flag); 00166 00167 /*! 00168 * \brief Check and potentially retire a Linked ID 00169 * 00170 * \param chan channel that is being destroyed or its linkedid is changing 00171 * 00172 * \since 1.8 00173 * 00174 * If at least one CEL backend is looking for CEL_LINKEDID_END 00175 * events, this function will check if the given channel is the last 00176 * active channel with that linkedid, and if it is, emit a 00177 * CEL_LINKEDID_END event. 00178 * 00179 * \return nothing 00180 */ 00181 void ast_cel_check_retire_linkedid(struct ast_channel *chan); 00182 00183 /*! 00184 * \brief Inform CEL that a new linkedid is being used 00185 * \since 11 00186 * 00187 * \retval -1 error 00188 * \retval 0 success 00189 */ 00190 int ast_cel_linkedid_ref(const char *linkedid); 00191 00192 /*! 00193 * \brief Create a fake channel from data in a CEL event 00194 * 00195 * \note 00196 * This function creates a fake channel containing the 00197 * serialized channel data in the given cel event. It should be 00198 * released with ast_channel_unref() but could be released with 00199 * ast_channel_release(). 00200 * 00201 * \param event the CEL event 00202 * 00203 * \since 1.8 00204 * 00205 * \return a channel with the data filled in, or NULL on error 00206 * 00207 * \todo This function is \b very expensive, especially given that some CEL backends 00208 * use it on \b every CEL event. This function really needs to go away at 00209 * some point. 00210 */ 00211 struct ast_channel *ast_cel_fabricate_channel_from_event(const struct ast_event *event); 00212 00213 /*! 00214 * \brief Report a channel event 00215 * 00216 * \param chan This argument is required. This is the primary channel associated with 00217 * this channel event. 00218 * \param event_type This is the type of call event being reported. 00219 * \param userdefevname This is an optional custom name for the call event. 00220 * \param extra This is an optional opaque field that will go into the "CEL_EXTRA" 00221 * information element of the call event. 00222 * \param peer2 All CEL events contain a "peer name" information element. The first 00223 * place the code will look to get a peer name is from the bridged channel to 00224 * chan. If chan has no bridged channel and peer2 is specified, then the name 00225 * of peer2 will go into the "peer name" field. If neither are available, the 00226 * peer name field will be blank. 00227 * 00228 * \since 1.8 00229 * 00230 * \pre chan and peer2 are both unlocked 00231 * 00232 * \retval 0 success 00233 * \retval non-zero failure 00234 */ 00235 int ast_cel_report_event(struct ast_channel *chan, enum ast_cel_event_type event_type, 00236 const char *userdefevname, const char *extra, struct ast_channel *peer2); 00237 00238 /*! 00239 * \brief Helper struct for getting the fields out of a CEL event 00240 */ 00241 struct ast_cel_event_record { 00242 /*! 00243 * \brief struct ABI version 00244 * \note This \b must be incremented when the struct changes. 00245 */ 00246 #define AST_CEL_EVENT_RECORD_VERSION 2 00247 /*! 00248 * \brief struct ABI version 00249 * \note This \b must stay as the first member. 00250 */ 00251 uint32_t version; 00252 enum ast_cel_event_type event_type; 00253 struct timeval event_time; 00254 const char *event_name; 00255 const char *user_defined_name; 00256 const char *caller_id_name; 00257 const char *caller_id_num; 00258 const char *caller_id_ani; 00259 const char *caller_id_rdnis; 00260 const char *caller_id_dnid; 00261 const char *extension; 00262 const char *context; 00263 const char *channel_name; 00264 const char *application_name; 00265 const char *application_data; 00266 const char *account_code; 00267 const char *peer_account; 00268 const char *unique_id; 00269 const char *linked_id; 00270 uint amaflag; 00271 const char *user_field; 00272 const char *peer; 00273 const char *extra; 00274 }; 00275 00276 /*! 00277 * \brief Fill in an ast_cel_event_record from a CEL event 00278 * 00279 * \param[in] event the CEL event 00280 * \param[out] r the ast_cel_event_record to fill in 00281 * 00282 * \since 1.8 00283 * 00284 * \retval 0 success 00285 * \retval non-zero failure 00286 */ 00287 int ast_cel_fill_record(const struct ast_event *event, struct ast_cel_event_record *r); 00288 00289 #if defined(__cplusplus) || defined(c_plusplus) 00290 } 00291 #endif 00292 00293 #endif /* __AST_CEL_H__ */