1 /* 2 * FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 3 * Copyright (C) 2005-2014, Anthony Minessale II <anthm@freeswitch.org> 4 * 5 * Version: MPL 1.1 6 * 7 * The contents of this file are subject to the Mozilla Public License Version 8 * 1.1 (the "License"); you may not use this file except in compliance with 9 * the License. You may obtain a copy of the License at 10 * http://www.mozilla.org/MPL/ 11 * 12 * Software distributed under the License is distributed on an "AS IS" basis, 13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 14 * for the specific language governing rights and limitations under the 15 * License. 16 * 17 * The Original Code is FreeSWITCH Modular Media Switching Software Library / Soft-Switch Application 18 * 19 * The Initial Developer of the Original Code is 20 * Anthony Minessale II <anthm@freeswitch.org> 21 * Portions created by the Initial Developer are Copyright (C) 22 * the Initial Developer. All Rights Reserved. 23 * 24 * Contributor(s): 25 * 26 * Anthony Minessale II <anthm@freeswitch.org> 27 * 28 * 29 * switch_caller.h -- Caller Identification 30 * 31 */ 32 /** 33 * @file switch_caller.h 34 * @brief Caller Identification 35 * @see caller 36 */ 37 /** 38 * @defgroup caller Caller Identity / Dialplan 39 * @ingroup core1 40 * 41 * This module implements a caller profile which is a group of information about a connected endpoint 42 * such as common caller id and other useful information such as ip address and destination number. 43 * A connected session's channel has up to 3 profiles: It's own, that of the session who spawned it 44 * and that of the session it has spawned. 45 * 46 * In addition, this module implements an abstract interface for extensions and applications. 47 * A connected session's channel has one extension object which may have one or more applications 48 * linked into a stack which will be executed in order by the session's state machine when the 49 * current state is CS_EXECUTE. 50 * @{ 51 */ 52 53 #ifndef SWITCH_CALLER_H 54 #define SWITCH_CALLER_H 55 56 #include <switch.h> 57 58 SWITCH_BEGIN_EXTERN_C 59 60 #define profile_dup(a,b,p) if (!zstr(a)) { b = switch_core_strdup(p, a); } else { b = SWITCH_BLANK_STRING; } 61 #define profile_dup_clean(a,b,p) if (!zstr(a)) { b = switch_var_clean_string(switch_clean_string(switch_core_strdup(p, a)));} else { b = SWITCH_BLANK_STRING; } 62 63 typedef struct profile_node_s { 64 char *var; 65 char *val; 66 struct profile_node_s *next; 67 } profile_node_t; 68 69 70 71 /*! \brief Call Specific Data 72 */ 73 struct switch_caller_profile { 74 /*! The Call's User Name */ 75 const char *username; 76 /*! The name of the dialplan */ 77 const char *dialplan; 78 /*! Caller ID Name */ 79 const char *caller_id_name; 80 /*! Caller ID Number */ 81 const char *caller_id_number; 82 /*! Original Caller ID Name */ 83 const char *orig_caller_id_name; 84 /*! Original Caller ID Number */ 85 const char *orig_caller_id_number; 86 /*! Callee ID Name */ 87 const char *callee_id_name; 88 /*! Callee ID Number */ 89 const char *callee_id_number; 90 uint8_t caller_ton; 91 uint8_t caller_numplan; 92 /*! Caller Network Address (when applicable) */ 93 const char *network_addr; 94 /*! ANI (when applicable) */ 95 const char *ani; 96 uint8_t ani_ton; 97 uint8_t ani_numplan; 98 /*! ANI II (when applicable) */ 99 const char *aniii; 100 /*! RDNIS */ 101 const char *rdnis; 102 uint8_t rdnis_ton; 103 uint8_t rdnis_numplan; 104 /*! Destination Number */ 105 char *destination_number; 106 uint8_t destination_number_ton; 107 uint8_t destination_number_numplan; 108 /*! channel type */ 109 const char *source; 110 /*! channel name */ 111 char *chan_name; 112 /*! unique id */ 113 char *uuid; 114 /*! context */ 115 const char *context; 116 /*! profile index */ 117 const char *profile_index; 118 /*! flags */ 119 switch_caller_profile_flag_t flags; 120 struct switch_caller_profile *originator_caller_profile; 121 struct switch_caller_profile *originatee_caller_profile; 122 struct switch_caller_profile *origination_caller_profile; 123 struct switch_caller_profile *hunt_caller_profile; 124 struct switch_channel_timetable *times; 125 struct switch_channel_timetable *old_times; 126 struct switch_caller_extension *caller_extension; 127 switch_memory_pool_t *pool; 128 struct switch_caller_profile *next; 129 switch_call_direction_t direction; 130 switch_call_direction_t logical_direction; 131 profile_node_t *soft; 132 char *uuid_str; 133 char *clone_of; 134 char *transfer_source; 135 }; 136 137 /*! \brief An Abstract Representation of a dialplan Application */ 138 struct switch_caller_application { 139 /*! The name of the registered application to call */ 140 char *application_name; 141 /*! An optional argument string to pass to the application */ 142 char *application_data; 143 /*! A function pointer to the application */ 144 switch_application_function_t application_function; 145 struct switch_caller_application *next; 146 }; 147 148 /*! \brief An Abstract Representation of a dialplan extension */ 149 struct switch_caller_extension { 150 /*! The name of the extension */ 151 char *extension_name; 152 /*! The number of the extension */ 153 char *extension_number; 154 /*! Pointer to the current application for this extension */ 155 switch_caller_application_t *current_application; 156 /*! Pointer to the last application for this extension */ 157 switch_caller_application_t *last_application; 158 /*! Pointer to the entire stack of applications for this extension */ 159 switch_caller_application_t *applications; 160 struct switch_caller_profile *children; 161 struct switch_caller_extension *next; 162 }; 163 164 /*! 165 \brief Create a new extension with desired parameters 166 \param session session associated with the extension (bound by scope) 167 \param extension_name extension name 168 \param extension_number extension number 169 \return a new extension object allocated from the session's memory pool 170 */ 171 SWITCH_DECLARE(switch_caller_extension_t *) switch_caller_extension_new(_In_ switch_core_session_t *session, 172 _In_z_ const char *extension_name, _In_z_ const char *extension_number); 173 174 SWITCH_DECLARE(switch_status_t) switch_caller_extension_clone(switch_caller_extension_t **new_ext, switch_caller_extension_t *orig, 175 switch_memory_pool_t *pool); 176 177 /*! 178 \brief Add an application (instruction) to the given extension 179 \param session session associated with the extension (bound by scope) 180 \param caller_extension extension to add the application to 181 \param application_name the name of the application 182 \param extra_data optional argument to the application 183 */ 184 SWITCH_DECLARE(void) switch_caller_extension_add_application(_In_ switch_core_session_t *session, 185 _In_ switch_caller_extension_t *caller_extension, 186 _In_z_ const char *application_name, _In_z_ const char *extra_data); 187 188 /*! 189 \brief Add an application (instruction) to the given extension 190 \param session session associated with the extension (bound by scope) 191 \param caller_extension extension to add the application to 192 \param application_name the name of the application 193 \param fmt optional argument to the application (printf format string) 194 */ 195 SWITCH_DECLARE(void) switch_caller_extension_add_application_printf(_In_ switch_core_session_t *session, 196 _In_ switch_caller_extension_t *caller_extension, 197 _In_z_ const char *application_name, _In_z_ const char *fmt, ...); 198 199 200 /*! 201 \brief Get the value of a field in a caller profile based on it's name 202 \param caller_profile The caller profile 203 \param name the name 204 \note this function is meant for situations where the name paramater is the contents of the variable 205 */ 206 _Check_return_ _Ret_opt_z_ SWITCH_DECLARE(const char *) switch_caller_get_field_by_name(_In_ switch_caller_profile_t *caller_profile, 207 _In_z_ const char *name); 208 209 /*! 210 \brief Create a new caller profile object 211 \param pool memory pool to use 212 \param username tne username of the caller 213 \param dialplan name of the dialplan module in use 214 \param caller_id_name caller ID name 215 \param caller_id_number caller ID number 216 \param network_addr network address 217 \param ani ANI information 218 \param aniii ANI II information 219 \param rdnis RDNIS 220 \param source the source 221 \param context a logical context 222 \param destination_number destination number 223 \return a new profile object allocated from the session's memory pool 224 */ 225 SWITCH_DECLARE(switch_caller_profile_t *) switch_caller_profile_new(_In_ switch_memory_pool_t *pool, 226 _In_opt_z_ const char *username, 227 _In_opt_z_ const char *dialplan, 228 _In_opt_z_ const char *caller_id_name, 229 _In_opt_z_ const char *caller_id_number, 230 _In_opt_z_ const char *network_addr, 231 _In_opt_z_ const char *ani, 232 _In_opt_z_ const char *aniii, 233 _In_opt_z_ const char *rdnis, 234 _In_opt_z_ const char *source, 235 _In_opt_z_ const char *context, _In_opt_z_ const char *destination_number); 236 237 /*! 238 \brief Clone an existing caller profile object 239 \param session session associated with the profile (bound by scope) 240 \param tocopy the existing profile 241 */ 242 SWITCH_DECLARE(switch_caller_profile_t *) switch_caller_profile_clone(_In_ switch_core_session_t *session, _In_ switch_caller_profile_t *tocopy); 243 244 /*! 245 \brief Duplicate an existing caller profile object 246 \param pool pool to duplicate with 247 \param tocopy the existing profile 248 */ 249 SWITCH_DECLARE(switch_caller_profile_t *) switch_caller_profile_dup(_In_ switch_memory_pool_t *pool, _In_ switch_caller_profile_t *tocopy); 250 251 /*! 252 \brief Add headers to an existing event in regards to a specific profile 253 \param caller_profile the desired profile 254 \param prefix a prefix string to all of the field names (for uniqueness) 255 \param event the event to add the information to 256 */ 257 258 SWITCH_DECLARE(void) switch_caller_profile_event_set_data(_In_ switch_caller_profile_t *caller_profile, 259 _In_opt_z_ const char *prefix, _In_ switch_event_t *event); 260 261 SWITCH_END_EXTERN_C 262 /** @} */ 263 #endif 264 /* For Emacs: 265 * Local Variables: 266 * mode:c 267 * indent-tabs-mode:t 268 * tab-width:4 269 * c-basic-offset:4 270 * End: 271 * For VIM: 272 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet: 273 */ 274