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_channel.h -- Media Channel Interface
30 *
31 */
32 /**
33 * @file switch_channel.h
34 * @brief Media Channel Interface
35 * @see switch_channel
36 */
37
38 #ifndef SWITCH_CHANNEL_H
39 #define SWITCH_CHANNEL_H
40
41 #include <switch.h>
42
43 SWITCH_BEGIN_EXTERN_C struct switch_channel_timetable {
44 switch_time_t profile_created;
45 switch_time_t created;
46 switch_time_t answered;
47 switch_time_t progress;
48 switch_time_t progress_media;
49 switch_time_t hungup;
50 switch_time_t transferred;
51 switch_time_t resurrected;
52 switch_time_t bridged;
53 switch_time_t last_hold;
54 switch_time_t hold_accum;
55 struct switch_channel_timetable *next;
56 };
57
58 typedef struct switch_channel_timetable switch_channel_timetable_t;
59
60 /**
61 * @defgroup switch_channel Channel Functions
62 * @ingroup core1
63 * The switch_channel object is a private entity that belongs to a session that contains the call
64 * specific information such as the call state, variables, caller profiles and DTMF queue
65 * @{
66 */
67
68 /*!
69 \brief Get the current state of a channel in the state engine
70 \param channel channel to retrieve state from
71 \return current state of channel
72 */
73 SWITCH_DECLARE(switch_channel_state_t) switch_channel_get_state(switch_channel_t *channel);
74 SWITCH_DECLARE(switch_channel_state_t) switch_channel_get_running_state(switch_channel_t *channel);
75 SWITCH_DECLARE(int) switch_channel_check_signal(switch_channel_t *channel, switch_bool_t in_thread_only);
76
77 /*!
78 \brief Determine if a channel is ready for io
79 \param channel channel to test
80 \return true if the channel is ready
81 */
82 SWITCH_DECLARE(int) switch_channel_test_ready(switch_channel_t *channel, switch_bool_t check_ready, switch_bool_t check_media);
83
84 #define switch_channel_ready(_channel) switch_channel_test_ready(_channel, SWITCH_TRUE, SWITCH_FALSE)
85 #define switch_channel_media_ready(_channel) switch_channel_test_ready(_channel, SWITCH_TRUE, SWITCH_TRUE)
86 #define switch_channel_media_up(_channel) (switch_channel_test_flag(_channel, CF_ANSWERED) || switch_channel_test_flag(_channel, CF_EARLY_MEDIA))
87
88 #define switch_channel_up(_channel) (switch_channel_check_signal(_channel, SWITCH_TRUE) || switch_channel_get_state(_channel) < CS_HANGUP)
89 #define switch_channel_down(_channel) (switch_channel_check_signal(_channel, SWITCH_TRUE) || switch_channel_get_state(_channel) >= CS_HANGUP)
90
91 #define switch_channel_up_nosig(_channel) (switch_channel_get_state(_channel) < CS_HANGUP)
92 #define switch_channel_down_nosig(_channel) (switch_channel_get_state(_channel) >= CS_HANGUP)
93
94 #define switch_channel_media_ack(_channel) (!switch_channel_test_cap(_channel, CC_MEDIA_ACK) || switch_channel_test_flag(_channel, CF_MEDIA_ACK))
95
96 #define switch_channel_text_only(_channel) (switch_channel_test_flag(_channel, CF_HAS_TEXT) && !switch_channel_test_flag(_channel, CF_AUDIO))
97
98
99 SWITCH_DECLARE(void) switch_channel_wait_for_state(switch_channel_t *channel, switch_channel_t *other_channel, switch_channel_state_t want_state);
100 SWITCH_DECLARE(void) switch_channel_wait_for_state_timeout(switch_channel_t *other_channel, switch_channel_state_t want_state, uint32_t timeout);
101 SWITCH_DECLARE(switch_status_t) switch_channel_wait_for_flag(switch_channel_t *channel,
102 switch_channel_flag_t want_flag,
103 switch_bool_t pres, uint32_t to, switch_channel_t *super_channel);
104 SWITCH_DECLARE(switch_status_t) switch_channel_wait_for_app_flag(switch_channel_t *channel,
105 uint32_t app_flag,
106 const char *key, switch_bool_t pres, uint32_t to);
107
108 SWITCH_DECLARE(switch_channel_state_t) switch_channel_perform_set_state(switch_channel_t *channel,
109 const char *file, const char *func, int line, switch_channel_state_t state);
110
111 SWITCH_DECLARE(switch_channel_state_t) switch_channel_perform_set_running_state(switch_channel_t *channel, switch_channel_state_t state,
112 const char *file, const char *func, int line);
113 #define switch_channel_set_running_state(channel, state) switch_channel_perform_set_running_state(channel, state, __FILE__, __SWITCH_FUNC__, __LINE__)
114
115 /*!
116 \brief Set the current state of a channel
117 \param channel channel to set state of
118 \param state new state
119 \return current state of channel after application of new state
120 */
121 #define switch_channel_set_state(channel, state) switch_channel_perform_set_state(channel, __FILE__, __SWITCH_FUNC__, __LINE__, state)
122
123 /*!
124 \brief return a cause code for a given string
125 \param str the string to check
126 \return the code
127 */
128 SWITCH_DECLARE(switch_call_cause_t) switch_channel_str2cause(_In_ const char *str);
129
130 /*!
131 \brief return the cause code for a given channel
132 \param channel the channel
133 \return the code
134 */
135 SWITCH_DECLARE(switch_call_cause_t) switch_channel_get_cause(_In_ switch_channel_t *channel);
136
137 SWITCH_DECLARE(switch_call_cause_t) switch_channel_cause_q850(switch_call_cause_t cause);
138 SWITCH_DECLARE(switch_call_cause_t) switch_channel_get_cause_q850(switch_channel_t *channel);
139 SWITCH_DECLARE(switch_call_cause_t *) switch_channel_get_cause_ptr(switch_channel_t *channel);
140
141 /*!
142 \brief return a cause string for a given cause
143 \param cause the code to check
144 \return the string
145 */
146 SWITCH_DECLARE(const char *) switch_channel_cause2str(_In_ switch_call_cause_t cause);
147
148 /*!
149 \brief View the timetable of a channel
150 \param channel channel to retrieve timetable from
151 \return a pointer to the channel's timetable (created, answered, etc..)
152 */
153 SWITCH_DECLARE(switch_channel_timetable_t *) switch_channel_get_timetable(_In_ switch_channel_t *channel);
154
155 /*!
156 \brief Allocate a new channel
157 \param channel NULL pointer to allocate channel to
158 \param pool memory_pool to use for allocation
159 \return SWITCH_STATUS_SUCCESS if successful
160 */
161 SWITCH_DECLARE(switch_status_t) switch_channel_alloc(_In_ switch_channel_t **channel, _In_ switch_call_direction_t direction,
162 _In_ switch_memory_pool_t *pool);
163
164 /*!
165 \brief Connect a newly allocated channel to a session object and setup it's initial state
166 \param channel the channel to initilize
167 \param session the session to connect the channel to
168 \param state the initial state of the channel
169 \param flags the initial channel flags
170 */
171 SWITCH_DECLARE(switch_status_t) switch_channel_init(switch_channel_t *channel, switch_core_session_t *session, switch_channel_state_t state,
172 switch_channel_flag_t flag);
173
174 /*!
175 \brief Takes presence_data_cols as a parameter or as a channel variable and copies them to channel profile variables
176 \param channel the channel on which to set the channel profile variables
177 \param presence_data_cols is a colon separated list of channel variables to copy to channel profile variables
178 */
179 SWITCH_DECLARE(void) switch_channel_set_presence_data_vals(switch_channel_t *channel, const char *presence_data_cols);
180
181 /*!
182 \brief Fire A presence event for the channel
183 \param channel the channel to initilize
184 \param rpid the rpid if for the icon to use
185 \param status the status message
186 \param id presence id
187 */
188 SWITCH_DECLARE(void) switch_channel_perform_presence(switch_channel_t *channel, const char *rpid, const char *status, const char *id,
189 const char *file, const char *func, int line);
190 #define switch_channel_presence(_a, _b, _c, _d) switch_channel_perform_presence(_a, _b, _c, _d, __FILE__, __SWITCH_FUNC__, __LINE__)
191 /*!
192 \brief Uninitalize a channel
193 \param channel the channel to uninit
194 */
195 SWITCH_DECLARE(void) switch_channel_uninit(switch_channel_t *channel);
196
197 /*!
198 \brief Set the given channel's caller profile
199 \param channel channel to assign the profile to
200 \param caller_profile the profile to assign
201 */
202 SWITCH_DECLARE(void) switch_channel_set_caller_profile(switch_channel_t *channel, switch_caller_profile_t *caller_profile);
203 SWITCH_DECLARE(void) switch_channel_step_caller_profile(switch_channel_t *channel);
204
205 /*!
206 \brief Retrieve the given channel's caller profile
207 \param channel channel to retrieve the profile from
208 \return the requested profile
209 */
210 SWITCH_DECLARE(switch_caller_profile_t *) switch_channel_get_caller_profile(switch_channel_t *channel);
211
212 /*!
213 \brief Set the given channel's originator caller profile
214 \param channel channel to assign the profile to
215 \param caller_profile the profile to assign
216 */
217 SWITCH_DECLARE(void) switch_channel_set_originator_caller_profile(switch_channel_t *channel, switch_caller_profile_t *caller_profile);
218
219
220 SWITCH_DECLARE(void) switch_channel_set_hunt_caller_profile(switch_channel_t *channel, switch_caller_profile_t *caller_profile);
221
222 /*!
223 \brief Retrieve the given channel's originator caller profile
224 \param channel channel to retrieve the profile from
225 \return the requested profile
226 */
227 SWITCH_DECLARE(switch_caller_profile_t *) switch_channel_get_originator_caller_profile(switch_channel_t *channel);
228
229 /*!
230 \brief Set the given channel's originatee caller profile
231 \param channel channel to assign the profile to
232 \param caller_profile the profile to assign
233 */
234 SWITCH_DECLARE(void) switch_channel_set_originatee_caller_profile(switch_channel_t *channel, switch_caller_profile_t *caller_profile);
235
236
237 /*!
238 \brief Retrieve the given channel's originatee caller profile
239 \param channel channel to retrieve the profile from
240 \return the requested profile
241 */
242 SWITCH_DECLARE(switch_caller_profile_t *) switch_channel_get_originatee_caller_profile(switch_channel_t *channel);
243
244 /*!
245 \brief Set the given channel's origination caller profile
246 \param channel channel to assign the profile to
247 \param caller_profile the profile to assign
248 */
249 SWITCH_DECLARE(void) switch_channel_set_origination_caller_profile(switch_channel_t *channel, switch_caller_profile_t *caller_profile);
250
251 /*!
252 \brief Retrieve the given channel's origination caller profile
253 \param channel channel to retrieve the profile from
254 \return the requested profile
255 */
256 SWITCH_DECLARE(switch_caller_profile_t *) switch_channel_get_origination_caller_profile(switch_channel_t *channel);
257
258
259 /*!
260 \brief Retrieve the given channel's unique id
261 \param channel channel to retrieve the unique id from
262 \return the unique id
263 */
264 SWITCH_DECLARE(char *) switch_channel_get_uuid(switch_channel_t *channel);
265
266 /*!
267 \brief Set a variable on a given channel
268 \param channel channel to set variable on
269 \param varname the name of the variable
270 \param value the value of the variable
271 \returns SWITCH_STATUS_SUCCESS if successful
272 */
273
274 SWITCH_DECLARE(switch_status_t) switch_channel_set_profile_var(switch_channel_t *channel, const char *name, const char *val);
275
276 SWITCH_DECLARE(switch_status_t) switch_channel_set_log_tag(switch_channel_t *channel, const char *tagname, const char *tagvalue);
277 SWITCH_DECLARE(switch_status_t) switch_channel_get_log_tags(switch_channel_t *channel, switch_event_t **log_tags);
278
279 SWITCH_DECLARE(switch_status_t) switch_channel_set_variable_var_check(switch_channel_t *channel,
280 const char *varname, const char *value, switch_bool_t var_check);
281 SWITCH_DECLARE(switch_status_t) switch_channel_add_variable_var_check(switch_channel_t *channel,
282 const char *varname, const char *value, switch_bool_t var_check, switch_stack_t stack);
283 SWITCH_DECLARE(switch_status_t) switch_channel_set_variable_printf(switch_channel_t *channel, const char *varname, const char *fmt, ...);
284 SWITCH_DECLARE(switch_status_t) switch_channel_set_variable_name_printf(switch_channel_t *channel, const char *val, const char *fmt, ...);
285
286 SWITCH_DECLARE(switch_status_t) switch_channel_set_variable_partner_var_check(switch_channel_t *channel,
287 const char *varname, const char *value, switch_bool_t var_check);
288 SWITCH_DECLARE(const char *) switch_channel_get_variable_partner(switch_channel_t *channel, const char *varname);
289
290 SWITCH_DECLARE(const char *) switch_channel_get_hold_music(switch_channel_t *channel);
291 SWITCH_DECLARE(const char *) switch_channel_get_hold_music_partner(switch_channel_t *channel);
292
293 SWITCH_DECLARE(uint32_t) switch_channel_del_variable_prefix(switch_channel_t *channel, const char *prefix);
294 SWITCH_DECLARE(switch_status_t) switch_channel_transfer_variable_prefix(switch_channel_t *orig_channel, switch_channel_t *new_channel, const char *prefix);
295
296 #define switch_channel_set_variable_safe(_channel, _var, _val) switch_channel_set_variable_var_check(_channel, _var, _val, SWITCH_FALSE)
297 #define switch_channel_set_variable(_channel, _var, _val) switch_channel_set_variable_var_check(_channel, _var, _val, SWITCH_TRUE)
298 #define switch_channel_set_variable_partner(_channel, _var, _val) switch_channel_set_variable_partner_var_check(_channel, _var, _val, SWITCH_TRUE)
299
300
301 SWITCH_DECLARE(switch_status_t) switch_channel_export_variable_var_check(switch_channel_t *channel,
302 const char *varname, const char *val,
303 const char *export_varname,
304 switch_bool_t var_check);
305
306 SWITCH_DECLARE(void) switch_channel_process_export(switch_channel_t *channel, switch_channel_t *peer_channel,
307 switch_event_t *var_event, const char *export_varname);
308
309 #define switch_channel_export_variable(_channel, _varname, _value, _ev) switch_channel_export_variable_var_check(_channel, _varname, _value, _ev, SWITCH_TRUE)
310 SWITCH_DECLARE(switch_status_t) switch_channel_export_variable_printf(switch_channel_t *channel, const char *varname,
311 const char *export_varname, const char *fmt, ...);
312
313 SWITCH_DECLARE(void) switch_channel_set_scope_variables(switch_channel_t *channel, switch_event_t **event);
314 SWITCH_DECLARE(switch_status_t) switch_channel_get_scope_variables(switch_channel_t *channel, switch_event_t **event);
315
316 /*!
317 \brief Retrieve a variable from a given channel
318 \param channel channel to retrieve variable from
319 \param varname the name of the variable
320 \return the value of the requested variable
321 */
322 SWITCH_DECLARE(const char *) switch_channel_get_variable_dup(switch_channel_t *channel, const char *varname, switch_bool_t dup, int idx);
323 #define switch_channel_get_variable(_c, _v) switch_channel_get_variable_dup(_c, _v, SWITCH_TRUE, -1)
324
325 SWITCH_DECLARE(switch_status_t) switch_channel_get_variables(switch_channel_t *channel, switch_event_t **event);
326
327 SWITCH_DECLARE(switch_status_t) switch_channel_pass_callee_id(switch_channel_t *channel, switch_channel_t *other_channel);
328
switch_channel_var_false(switch_channel_t * channel,const char * variable)329 static inline int switch_channel_var_false(switch_channel_t *channel, const char *variable) {
330 return switch_false(switch_channel_get_variable_dup(channel, variable, SWITCH_FALSE, -1));
331 }
332
switch_channel_var_true(switch_channel_t * channel,const char * variable)333 static inline int switch_channel_var_true(switch_channel_t *channel, const char *variable) {
334 return switch_true(switch_channel_get_variable_dup(channel, variable, SWITCH_FALSE, -1));
335 }
336
337 /*!
338 * \brief Start iterating over the entries in the channel variable list.
339 * \param channel the channel to iterate the variables for
340 * \remark This function locks the profile mutex, use switch_channel_variable_last to unlock
341 */
342 SWITCH_DECLARE(switch_event_header_t *) switch_channel_variable_first(switch_channel_t *channel);
343
344 /*!
345 * \brief Stop iterating over channel variables.
346 * \remark Unlocks the profile mutex initially locked in switch_channel_variable_first
347 */
348 SWITCH_DECLARE(void) switch_channel_variable_last(switch_channel_t *channel);
349
350
351 SWITCH_DECLARE(void) switch_channel_restart(switch_channel_t *channel);
352
353 SWITCH_DECLARE(switch_status_t) switch_channel_caller_extension_masquerade(switch_channel_t *orig_channel, switch_channel_t *new_channel, uint32_t offset);
354
355 /*!
356 \brief Assign a caller extension to a given channel
357 \param channel channel to assign extension to
358 \param caller_extension extension to assign
359 */
360 SWITCH_DECLARE(void) switch_channel_set_caller_extension(switch_channel_t *channel, switch_caller_extension_t *caller_extension);
361
362 SWITCH_DECLARE(void) switch_channel_invert_cid(switch_channel_t *channel);
363 SWITCH_DECLARE(void) switch_channel_flip_cid(switch_channel_t *channel);
364 SWITCH_DECLARE(void) switch_channel_sort_cid(switch_channel_t *channel);
365
366 /*!
367 \brief Retrieve caller extension from a given channel
368 \param channel channel to retrieve extension from
369 \return the requested extension
370 */
371 SWITCH_DECLARE(switch_caller_extension_t *) switch_channel_get_caller_extension(switch_channel_t *channel);
372
373 /*!
374 \brief Test for presence of given flag on a given channel
375 \param channel channel to test
376 \param flag to test
377 \return TRUE if flags were present
378 */
379 SWITCH_DECLARE(uint32_t) switch_channel_test_flag(switch_channel_t *channel, switch_channel_flag_t flag);
380
381 /*!
382 \brief Set given flag(s) on a given channel
383 \param channel channel on which to set flag
384 \param flag or'd list of flags to set
385 */
386 SWITCH_DECLARE(void) switch_channel_set_flag_value(switch_channel_t *channel, switch_channel_flag_t flag, uint32_t value);
387 #define switch_channel_set_flag(_c, _f) switch_channel_set_flag_value(_c, _f, 1)
388
389 SWITCH_DECLARE(void) switch_channel_set_flag_recursive(switch_channel_t *channel, switch_channel_flag_t flag);
390
391 SWITCH_DECLARE(void) switch_channel_set_cap_value(switch_channel_t *channel, switch_channel_cap_t cap, uint32_t value);
392 #define switch_channel_set_cap(_c, _cc) switch_channel_set_cap_value(_c, _cc, 1)
393
394 SWITCH_DECLARE(void) switch_channel_clear_cap(switch_channel_t *channel, switch_channel_cap_t cap);
395 SWITCH_DECLARE(uint32_t) switch_channel_test_cap(switch_channel_t *channel, switch_channel_cap_t cap);
396 SWITCH_DECLARE(uint32_t) switch_channel_test_cap_partner(switch_channel_t *channel, switch_channel_cap_t cap);
397
398 /*!
399 \brief Set given flag(s) on a given channel's bridge partner
400 \param channel channel to derive the partner channel to set flag on
401 \param flag to set
402 \return true if the flag was set
403 */
404 SWITCH_DECLARE(switch_bool_t) switch_channel_set_flag_partner(switch_channel_t *channel, switch_channel_flag_t flag);
405
406 /*!
407 \brief Clears given flag(s) on a given channel's bridge partner
408 \param channel channel to derive the partner channel to clear flag(s) from
409 \param flag the flag to clear
410 \return true if the flag was cleared
411 */
412 SWITCH_DECLARE(switch_bool_t) switch_channel_clear_flag_partner(switch_channel_t *channel, switch_channel_flag_t flag);
413
414 SWITCH_DECLARE(uint32_t) switch_channel_test_flag_partner(switch_channel_t *channel, switch_channel_flag_t flag);
415
416 /*!
417 \brief Set given flag(s) on a given channel to be applied on the next state change
418 \param channel channel on which to set flag(s)
419 \param flag flag to set
420 */
421 SWITCH_DECLARE(void) switch_channel_set_state_flag(switch_channel_t *channel, switch_channel_flag_t flag);
422 SWITCH_DECLARE(void) switch_channel_clear_state_flag(switch_channel_t *channel, switch_channel_flag_t flag);
423
424 /*!
425 \brief Clear given flag(s) from a channel
426 \param channel channel to clear flags from
427 \param flag flag to clear
428 */
429 SWITCH_DECLARE(void) switch_channel_clear_flag(switch_channel_t *channel, switch_channel_flag_t flag);
430
431 SWITCH_DECLARE(void) switch_channel_clear_flag_recursive(switch_channel_t *channel, switch_channel_flag_t flag);
432
433 SWITCH_DECLARE(switch_status_t) switch_channel_perform_answer(switch_channel_t *channel, const char *file, const char *func, int line);
434
435 SWITCH_DECLARE(switch_status_t) switch_channel_perform_mark_answered(switch_channel_t *channel, const char *file, const char *func, int line);
436 SWITCH_DECLARE(void) switch_channel_check_zrtp(switch_channel_t *channel);
437
438 /*!
439 \brief Answer a channel (initiate/acknowledge a successful connection)
440 \param channel channel to answer
441 \return SWITCH_STATUS_SUCCESS if channel was answered successfully
442 */
443 #define switch_channel_answer(channel) switch_channel_perform_answer(channel, __FILE__, __SWITCH_FUNC__, __LINE__)
444
445 /*!
446 \brief Mark a channel answered with no indication (for outbound calls)
447 \param channel channel to mark answered
448 \return SWITCH_STATUS_SUCCESS if channel was answered successfully
449 */
450 #define switch_channel_mark_answered(channel) switch_channel_perform_mark_answered(channel, __FILE__, __SWITCH_FUNC__, __LINE__)
451
452 /*!
453 \brief Mark a channel pre_answered (early media) with no indication (for outbound calls)
454 \param channel channel to mark pre_answered
455 \return SWITCH_STATUS_SUCCESS if channel was pre_answered successfully
456 */
457 #define switch_channel_mark_pre_answered(channel) switch_channel_perform_mark_pre_answered(channel, __FILE__, __SWITCH_FUNC__, __LINE__)
458
459 SWITCH_DECLARE(switch_status_t) switch_channel_perform_acknowledge_call(switch_channel_t *channel,
460 const char *file, const char *func, int line);
461 #define switch_channel_acknowledge_call(channel) switch_channel_perform_acknowledge_call(channel, __FILE__, __SWITCH_FUNC__, __LINE__)
462
463 SWITCH_DECLARE(switch_status_t) switch_channel_perform_ring_ready_value(switch_channel_t *channel,
464 switch_ring_ready_t rv,
465 const char *file, const char *func, int line);
466 /*!
467 \brief Send Ringing message to a channel
468 \param channel channel to ring
469 \return SWITCH_STATUS_SUCCESS if successful
470 */
471 #define switch_channel_ring_ready(channel) switch_channel_perform_ring_ready_value(channel, SWITCH_RING_READY_RINGING, __FILE__, __SWITCH_FUNC__, __LINE__)
472 #define switch_channel_ring_ready_value(channel, _rv) \
473 switch_channel_perform_ring_ready_value(channel, _rv, __FILE__, __SWITCH_FUNC__, __LINE__)
474
475
476 SWITCH_DECLARE(switch_status_t) switch_channel_perform_pre_answer(switch_channel_t *channel, const char *file, const char *func, int line);
477
478 SWITCH_DECLARE(switch_status_t) switch_channel_perform_mark_pre_answered(switch_channel_t *channel, const char *file, const char *func, int line);
479
480 SWITCH_DECLARE(switch_status_t) switch_channel_perform_mark_ring_ready_value(switch_channel_t *channel,
481 switch_ring_ready_t rv,
482 const char *file, const char *func, int line);
483
484 /*!
485 \brief Indicate progress on a channel to attempt early media
486 \param channel channel to pre-answer
487 \return SWITCH_STATUS_SUCCESS
488 */
489 #define switch_channel_pre_answer(channel) switch_channel_perform_pre_answer(channel, __FILE__, __SWITCH_FUNC__, __LINE__)
490
491 /*!
492 \brief Indicate a channel is ready to provide ringback
493 \param channel channel
494 \return SWITCH_STATUS_SUCCESS
495 */
496 #define switch_channel_mark_ring_ready(channel) \
497 switch_channel_perform_mark_ring_ready_value(channel, SWITCH_RING_READY_RINGING, __FILE__, __SWITCH_FUNC__, __LINE__)
498
499 #define switch_channel_mark_ring_ready_value(channel, _rv) \
500 switch_channel_perform_mark_ring_ready_value(channel, _rv, __FILE__, __SWITCH_FUNC__, __LINE__)
501
502 /*!
503 \brief add a state handler table to a given channel
504 \param channel channel on which to add the state handler table
505 \param state_handler table of state handler functions
506 \return the index number/priority of the table negative value indicates failure
507 */
508 SWITCH_DECLARE(int) switch_channel_add_state_handler(switch_channel_t *channel, const switch_state_handler_table_t *state_handler);
509
510 /*!
511 \brief clear a state handler table from a given channel
512 \param channel channel from which to clear the state handler table
513 \param state_handler table of state handler functions
514 */
515 SWITCH_DECLARE(void) switch_channel_clear_state_handler(switch_channel_t *channel, const switch_state_handler_table_t *state_handler);
516
517 /*!
518 \brief Retrieve an state handler tablefrom a given channel at given index level
519 \param channel channel from which to retrieve the state handler table
520 \param index the index of the state handler table (start from 0)
521 \return given channel's state handler table at given index or NULL if requested index does not exist.
522 */
523 SWITCH_DECLARE(const switch_state_handler_table_t *) switch_channel_get_state_handler(switch_channel_t *channel, int index);
524
525 /*!
526 \brief Set private data on channel
527 \param channel channel on which to set data
528 \param key unique keyname to associate your private data to
529 \param private_info void pointer to private data
530 \return SWITCH_STATUS_SUCCESS if data was set
531 \remarks set NULL to delete your private data
532 */
533 SWITCH_DECLARE(switch_status_t) switch_channel_set_private(switch_channel_t *channel, const char *key, const void *private_info);
534
535 /*!
536 \brief Retrieve private from a given channel
537 \param channel channel to retrieve data from
538 \param key unique keyname to retrieve your private data
539 \return void pointer to channel's private data
540 */
541 SWITCH_DECLARE(void *) switch_channel_get_private(switch_channel_t *channel, const char *key);
542 SWITCH_DECLARE(void *) switch_channel_get_private_partner(switch_channel_t *channel, const char *key);
543
544 /*!
545 \brief Assign a name to a given channel
546 \param channel channel to assign name to
547 \param name name to assign
548 \return SWITCH_STATUS_SUCCESS if name was assigned
549 */
550 SWITCH_DECLARE(switch_status_t) switch_channel_set_name(switch_channel_t *channel, const char *name);
551
552 /*!
553 \brief Retrieve the name of a given channel
554 \param channel channel to get name of
555 \return the channel's name
556 */
557 SWITCH_DECLARE(char *) switch_channel_get_name(switch_channel_t *channel);
558
559
560 SWITCH_DECLARE(switch_channel_state_t) switch_channel_perform_hangup(switch_channel_t *channel,
561 const char *file, const char *func, int line, switch_call_cause_t hangup_cause);
562
563 /*!
564 \brief Hangup a channel flagging it's state machine to end
565 \param channel channel to hangup
566 \param hangup_cause the appropriate hangup cause
567 \return the resulting channel state.
568 */
569 #define switch_channel_hangup(channel, hangup_cause) switch_channel_perform_hangup(channel, __FILE__, __SWITCH_FUNC__, __LINE__, hangup_cause)
570
571 /*!
572 \brief Test for presence of DTMF on a given channel
573 \param channel channel to test
574 \return number of digits in the queue
575 */
576 SWITCH_DECLARE(switch_size_t) switch_channel_has_dtmf(_In_ switch_channel_t *channel);
577 SWITCH_DECLARE(switch_status_t) switch_channel_dtmf_lock(switch_channel_t *channel);
578 SWITCH_DECLARE(switch_status_t) switch_channel_try_dtmf_lock(switch_channel_t *channel);
579 SWITCH_DECLARE(switch_status_t) switch_channel_dtmf_unlock(switch_channel_t *channel);
580
581
582 /*!
583 \brief Queue DTMF on a given channel
584 \param channel channel to queue DTMF to
585 \param dtmf digit
586 \return SWITCH_STATUS_SUCCESS if successful
587 */
588 SWITCH_DECLARE(switch_status_t) switch_channel_queue_dtmf(_In_ switch_channel_t *channel, _In_ const switch_dtmf_t *dtmf);
589 SWITCH_DECLARE(switch_status_t) switch_channel_queue_dtmf_string(_In_ switch_channel_t *channel, _In_ const char *dtmf_string);
590
591 /*!
592 \brief Retrieve DTMF digits from a given channel
593 \param channel channel to retrieve digits from
594 \param dtmf digit
595 \return number of bytes read into the buffer
596 */
597 SWITCH_DECLARE(switch_status_t) switch_channel_dequeue_dtmf(_In_ switch_channel_t *channel, _In_ switch_dtmf_t *dtmf);
598 SWITCH_DECLARE(void) switch_channel_flush_dtmf(_In_ switch_channel_t *channel);
599 SWITCH_DECLARE(switch_size_t) switch_channel_dequeue_dtmf_string(_In_ switch_channel_t *channel, _Out_opt_bytecapcount_(len)
600 char *dtmf_str, _In_ switch_size_t len);
601
602 /*!
603 \brief Render the name of the provided state enum
604 \param state state to get name of
605 \return the string representation of the state
606 */
607 SWITCH_DECLARE(const char *) switch_channel_state_name(_In_ switch_channel_state_t state);
608
609 /*!
610 \brief Render the enum of the provided state name
611 \param name the name of the state
612 \return the enum value (numeric)
613 */
614 SWITCH_DECLARE(switch_channel_state_t) switch_channel_name_state(_In_ const char *name);
615
616 /*!
617 \brief Add information about a given channel to an event object
618 \param channel channel to add information about
619 \param event event to add information to
620 */
621 SWITCH_DECLARE(void) switch_channel_event_set_data(_In_ switch_channel_t *channel, _In_ switch_event_t *event);
622
623 SWITCH_DECLARE(void) switch_channel_event_set_basic_data(_In_ switch_channel_t *channel, _In_ switch_event_t *event);
624 SWITCH_DECLARE(void) switch_channel_event_set_extended_data(_In_ switch_channel_t *channel, _In_ switch_event_t *event);
625
626 /*!
627 \brief Expand varaibles in a string based on the variables in a paticular channel
628 \param channel channel to expand the variables from
629 \param in the original string
630 \return the original string if no expansion takes place otherwise a new string that must be freed
631 \note it's necessary to test if the return val is the same as the input and free the string if it is not.
632 */
633 SWITCH_DECLARE(char *) switch_channel_expand_variables_check(switch_channel_t *channel, const char *in, switch_event_t *var_list, switch_event_t *api_list, uint32_t recur);
634 #define switch_channel_expand_variables(_channel, _in) switch_channel_expand_variables_check(_channel, _in, NULL, NULL, 0)
635
636 #define switch_channel_inbound_display(_channel) ((switch_channel_direction(_channel) == SWITCH_CALL_DIRECTION_INBOUND && !switch_channel_test_flag(_channel, CF_BLEG)) || (switch_channel_direction(_channel) == SWITCH_CALL_DIRECTION_OUTBOUND && switch_channel_test_flag(_channel, CF_DIALPLAN)))
637
638 #define switch_channel_outbound_display(_channel) ((switch_channel_direction(_channel) == SWITCH_CALL_DIRECTION_INBOUND && switch_channel_test_flag(_channel, CF_BLEG)) || (switch_channel_direction(_channel) == SWITCH_CALL_DIRECTION_OUTBOUND && !switch_channel_test_flag(_channel, CF_DIALPLAN)))
639
640 SWITCH_DECLARE(char *) switch_channel_build_param_string(_In_ switch_channel_t *channel, _In_opt_ switch_caller_profile_t *caller_profile,
641 _In_opt_ const char *prefix);
642 SWITCH_DECLARE(switch_status_t) switch_channel_set_timestamps(_In_ switch_channel_t *channel);
643
644 #define switch_channel_stop_broadcast(_channel) for(;;) {if (switch_channel_test_flag(_channel, CF_BROADCAST)) {switch_channel_set_flag(_channel, CF_STOP_BROADCAST); switch_channel_set_flag(_channel, CF_BREAK); } break;}
645
646 SWITCH_DECLARE(void) switch_channel_perform_audio_sync(switch_channel_t *channel, const char *file, const char *func, int line);
647 #define switch_channel_audio_sync(_c) switch_channel_perform_audio_sync(_c, __FILE__, __SWITCH_FUNC__, __LINE__)
648 SWITCH_DECLARE(void) switch_channel_perform_video_sync(switch_channel_t *channel, const char *file, const char *func, int line);
649 #define switch_channel_video_sync(_c) switch_channel_perform_video_sync(_c, __FILE__, __SWITCH_FUNC__, __LINE__)
650
651 SWITCH_DECLARE(void) switch_channel_set_private_flag(switch_channel_t *channel, uint32_t flags);
652 SWITCH_DECLARE(void) switch_channel_clear_private_flag(switch_channel_t *channel, uint32_t flags);
653 SWITCH_DECLARE(int) switch_channel_test_private_flag(switch_channel_t *channel, uint32_t flags);
654
655 SWITCH_DECLARE(void) switch_channel_set_app_flag_key(const char *app, switch_channel_t *channel, uint32_t flags);
656 SWITCH_DECLARE(void) switch_channel_clear_app_flag_key(const char *app, switch_channel_t *channel, uint32_t flags);
657 SWITCH_DECLARE(int) switch_channel_test_app_flag_key(const char *app, switch_channel_t *channel, uint32_t flags);
658
659 #define switch_channel_set_app_flag(_c, _f) switch_channel_set_app_flag_key(__FILE__, _c, _f)
660 #define switch_channel_clear_app_flag(_c, _f) switch_channel_clear_app_flag_key(__FILE__, _c, _f)
661 #define switch_channel_test_app_flag(_c, _f) switch_channel_test_app_flag_key(__FILE__, _c, _f)
662
663 SWITCH_DECLARE(void) switch_channel_set_bridge_time(switch_channel_t *channel);
664 SWITCH_DECLARE(void) switch_channel_set_hangup_time(switch_channel_t *channel);
665 SWITCH_DECLARE(switch_call_direction_t) switch_channel_direction(switch_channel_t *channel);
666 SWITCH_DECLARE(switch_call_direction_t) switch_channel_logical_direction(switch_channel_t *channel);
667 SWITCH_DECLARE(void) switch_channel_set_direction(switch_channel_t *channel, switch_call_direction_t direction);
668
669 SWITCH_DECLARE(switch_core_session_t *) switch_channel_get_session(switch_channel_t *channel);
670 SWITCH_DECLARE(char *) switch_channel_get_flag_string(switch_channel_t *channel);
671 SWITCH_DECLARE(char *) switch_channel_get_cap_string(switch_channel_t *channel);
672 SWITCH_DECLARE(int) switch_channel_state_change_pending(switch_channel_t *channel);
673
674 SWITCH_DECLARE(void) switch_channel_perform_set_callstate(switch_channel_t *channel, switch_channel_callstate_t callstate,
675 const char *file, const char *func, int line);
676 #define switch_channel_set_callstate(channel, state) switch_channel_perform_set_callstate(channel, state, __FILE__, __SWITCH_FUNC__, __LINE__)
677 SWITCH_DECLARE(switch_channel_callstate_t) switch_channel_get_callstate(switch_channel_t *channel);
678 SWITCH_DECLARE(const char *) switch_channel_callstate2str(switch_channel_callstate_t callstate);
679 SWITCH_DECLARE(switch_channel_callstate_t) switch_channel_str2callstate(const char *str);
680 SWITCH_DECLARE(void) switch_channel_mark_hold(switch_channel_t *channel, switch_bool_t on);
681
682 /** @} */
683
684 SWITCH_DECLARE(switch_status_t) switch_channel_execute_on(switch_channel_t *channel, const char *variable_prefix);
685 SWITCH_DECLARE(switch_status_t) switch_channel_api_on(switch_channel_t *channel, const char *variable_prefix);
686 SWITCH_DECLARE(void) switch_channel_process_device_hangup(switch_channel_t *channel);
687 SWITCH_DECLARE(switch_caller_extension_t *) switch_channel_get_queued_extension(switch_channel_t *channel);
688 SWITCH_DECLARE(void) switch_channel_transfer_to_extension(switch_channel_t *channel, switch_caller_extension_t *caller_extension);
689 SWITCH_DECLARE(const char *) switch_channel_get_partner_uuid(switch_channel_t *channel);
690 SWITCH_DECLARE(const char *) switch_channel_get_partner_uuid_copy(switch_channel_t *channel, char *buf, switch_size_t blen);
691 SWITCH_DECLARE(switch_hold_record_t *) switch_channel_get_hold_record(switch_channel_t *channel);
692 SWITCH_DECLARE(void) switch_channel_state_thread_lock(switch_channel_t *channel);
693 SWITCH_DECLARE(void) switch_channel_state_thread_unlock(switch_channel_t *channel);
694 SWITCH_DECLARE(switch_status_t) switch_channel_state_thread_trylock(switch_channel_t *channel);
695 SWITCH_DECLARE(void) switch_channel_handle_cause(switch_channel_t *channel, switch_call_cause_t cause);
696 SWITCH_DECLARE(void) switch_channel_global_init(switch_memory_pool_t *pool);
697 SWITCH_DECLARE(void) switch_channel_global_uninit(void);
698 SWITCH_DECLARE(const char *) switch_channel_set_device_id(switch_channel_t *channel, const char *device_id);
699 SWITCH_DECLARE(void) switch_channel_clear_device_record(switch_channel_t *channel);
700 SWITCH_DECLARE(switch_device_record_t *) switch_channel_get_device_record(switch_channel_t *channel);
701 SWITCH_DECLARE(void) switch_channel_release_device_record(switch_device_record_t **dcdrp);
702 SWITCH_DECLARE(switch_status_t) switch_channel_bind_device_state_handler(switch_device_state_function_t function, void *user_data);
703 SWITCH_DECLARE(switch_status_t) switch_channel_unbind_device_state_handler(switch_device_state_function_t function);
704 SWITCH_DECLARE(const char *) switch_channel_device_state2str(switch_device_state_t device_state);
705 SWITCH_DECLARE(switch_status_t) switch_channel_pass_sdp(switch_channel_t *from_channel, switch_channel_t *to_channel, const char *sdp);
706
707 SWITCH_END_EXTERN_C
708 #endif
709 /* For Emacs:
710 * Local Variables:
711 * mode:c
712 * indent-tabs-mode:t
713 * tab-width:4
714 * c-basic-offset:4
715 * End:
716 * For VIM:
717 * vim:set softtabstop=4 shiftwidth=4 tabstop=4 noet:
718 */
719