Dialing API. More...
Go to the source code of this file.
Typedefs | |
typedef void(* | ast_dial_state_callback )(struct ast_dial *) |
Enumerations | |
enum | ast_dial_option { AST_DIAL_OPTION_RINGING, AST_DIAL_OPTION_ANSWER_EXEC, AST_DIAL_OPTION_MUSIC, AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, AST_DIAL_OPTION_MAX } |
List of options that are applicable either globally or per dialed channel. More... | |
enum | ast_dial_result { AST_DIAL_RESULT_INVALID, AST_DIAL_RESULT_FAILED, AST_DIAL_RESULT_TRYING, AST_DIAL_RESULT_RINGING, AST_DIAL_RESULT_PROGRESS, AST_DIAL_RESULT_PROCEEDING, AST_DIAL_RESULT_ANSWERED, AST_DIAL_RESULT_TIMEOUT, AST_DIAL_RESULT_HANGUP, AST_DIAL_RESULT_UNANSWERED } |
List of return codes for dial run API calls. More... | |
Functions | |
struct ast_channel * | ast_dial_answered (struct ast_dial *dial) |
Return channel that answered. | |
struct ast_channel * | ast_dial_answered_steal (struct ast_dial *dial) |
Steal the channel that answered. | |
int | ast_dial_append (struct ast_dial *dial, const char *tech, const char *device) |
Append a channel. | |
struct ast_dial * | ast_dial_create (void) |
New dialing structure. | |
int | ast_dial_destroy (struct ast_dial *dial) |
Destroys a dialing structure. | |
void | ast_dial_hangup (struct ast_dial *dial) |
Hangup channels. | |
enum ast_dial_result | ast_dial_join (struct ast_dial *dial) |
Cancel async thread. | |
int | ast_dial_option_disable (struct ast_dial *dial, int num, enum ast_dial_option option) |
Disables an option per channel. | |
int | ast_dial_option_enable (struct ast_dial *dial, int num, enum ast_dial_option option, void *data) |
Enables an option per channel. | |
int | ast_dial_option_global_disable (struct ast_dial *dial, enum ast_dial_option option) |
Disables an option globally. | |
int | ast_dial_option_global_enable (struct ast_dial *dial, enum ast_dial_option option, void *data) |
Enables an option globally. | |
enum ast_dial_result | ast_dial_run (struct ast_dial *dial, struct ast_channel *chan, int async) |
Execute dialing synchronously or asynchronously. | |
void | ast_dial_set_global_timeout (struct ast_dial *dial, int timeout) |
Set the maximum time (globally) allowed for trying to ring phones. | |
void | ast_dial_set_state_callback (struct ast_dial *dial, ast_dial_state_callback callback) |
Set a callback for state changes. | |
void | ast_dial_set_timeout (struct ast_dial *dial, int num, int timeout) |
Set the maximum time (per channel) allowed for trying to ring the phone. | |
enum ast_dial_result | ast_dial_state (struct ast_dial *dial) |
Return state of dial. |
Dialing API.
Definition in file dial.h.
typedef void(* ast_dial_state_callback)(struct ast_dial *) |
enum ast_dial_option |
List of options that are applicable either globally or per dialed channel.
Definition at line 39 of file dial.h.
{ AST_DIAL_OPTION_RINGING, /*!< Always indicate ringing to caller */ AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */ AST_DIAL_OPTION_MUSIC, /*!< Play music on hold instead of ringing to the calling channel */ AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */ AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */ };
enum ast_dial_result |
List of return codes for dial run API calls.
Definition at line 48 of file dial.h.
{ AST_DIAL_RESULT_INVALID, /*!< Invalid options were passed to run function */ AST_DIAL_RESULT_FAILED, /*!< Attempts to dial failed before reaching critical state */ AST_DIAL_RESULT_TRYING, /*!< Currently trying to dial */ AST_DIAL_RESULT_RINGING, /*!< Dial is presently ringing */ AST_DIAL_RESULT_PROGRESS, /*!< Dial is presently progressing */ AST_DIAL_RESULT_PROCEEDING, /*!< Dial is presently proceeding */ AST_DIAL_RESULT_ANSWERED, /*!< A channel was answered */ AST_DIAL_RESULT_TIMEOUT, /*!< Timeout was tripped, nobody answered */ AST_DIAL_RESULT_HANGUP, /*!< Caller hung up */ AST_DIAL_RESULT_UNANSWERED, /*!< Nobody answered */ };
struct ast_channel* ast_dial_answered | ( | struct ast_dial * | dial | ) | [read] |
Return channel that answered.
dial | Dialing structure |
Definition at line 738 of file dial.c.
References AST_DIAL_RESULT_ANSWERED, AST_LIST_FIRST, ast_dial::channels, and ast_dial::state.
Referenced by dial_trunk(), and sla_handle_dial_state_event().
{ if (!dial) return NULL; return ((dial->state == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL); }
struct ast_channel* ast_dial_answered_steal | ( | struct ast_dial * | dial | ) | [read] |
Steal the channel that answered.
dial | Dialing structure |
Definition at line 750 of file dial.c.
References AST_DIAL_RESULT_ANSWERED, AST_LIST_FIRST, chan, ast_dial::channels, and ast_dial::state.
{ struct ast_channel *chan = NULL; if (!dial) return NULL; if (dial->state == AST_DIAL_RESULT_ANSWERED) { chan = AST_LIST_FIRST(&dial->channels)->owner; AST_LIST_FIRST(&dial->channels)->owner = NULL; } return chan; }
int ast_dial_append | ( | struct ast_dial * | dial, |
const char * | tech, | ||
const char * | device | ||
) |
Append a channel.
Definition at line 226 of file dial.c.
References ast_atomic_fetchadd_int(), ast_calloc, AST_LIST_INSERT_TAIL, ast_strdup, ast_dial::channels, ast_dial_channel::device, ast_dial_channel::list, ast_dial::num, ast_dial_channel::num, ast_dial_channel::tech, and ast_dial_channel::timeout.
Referenced by dial_trunk(), page_exec(), and sla_ring_station().
{ struct ast_dial_channel *channel = NULL; /* Make sure we have required arguments */ if (!dial || !tech || !device) return -1; /* Allocate new memory for dialed channel structure */ if (!(channel = ast_calloc(1, sizeof(*channel)))) return -1; /* Record technology and device for when we actually dial */ channel->tech = ast_strdup(tech); channel->device = ast_strdup(device); /* Grab reference number from dial structure */ channel->num = ast_atomic_fetchadd_int(&dial->num, +1); /* No timeout exists... yet */ channel->timeout = -1; /* Insert into channels list */ AST_LIST_INSERT_TAIL(&dial->channels, channel, list); return channel->num; }
struct ast_dial* ast_dial_create | ( | void | ) | [read] |
New dialing structure.
Definition at line 198 of file dial.c.
References ast_dial::actual_timeout, ast_calloc, AST_LIST_HEAD_INIT, ast_mutex_init(), AST_PTHREADT_NULL, ast_dial::channels, ast_dial::lock, ast_dial::thread, and ast_dial::timeout.
Referenced by dial_trunk(), page_exec(), and sla_ring_station().
{ struct ast_dial *dial = NULL; /* Allocate new memory for structure */ if (!(dial = ast_calloc(1, sizeof(*dial)))) return NULL; /* Initialize list of channels */ AST_LIST_HEAD_INIT(&dial->channels); /* Initialize thread to NULL */ dial->thread = AST_PTHREADT_NULL; /* No timeout exists... yet */ dial->timeout = -1; dial->actual_timeout = -1; /* Can't forget about the lock */ ast_mutex_init(&dial->lock); return dial; }
int ast_dial_destroy | ( | struct ast_dial * | dial | ) |
Destroys a dialing structure.
dial | Dialing structure to free |
dial | Dialing structure to free |
Definition at line 850 of file dial.c.
References AST_DIAL_OPTION_MAX, ast_free, ast_hangup(), AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_mutex_destroy(), ast_dial::channels, ast_dial_channel::device, ast_option_types::disable, ast_dial_channel::list, ast_dial::lock, option_types, ast_dial::options, ast_dial_channel::options, ast_dial_channel::owner, and ast_dial_channel::tech.
Referenced by dial_trunk(), page_exec(), run_station(), sla_hangup_stations(), sla_ring_station(), and sla_stop_ringing_station().
{ int i = 0; struct ast_dial_channel *channel = NULL; if (!dial) return -1; /* Hangup and deallocate all the dialed channels */ AST_LIST_LOCK(&dial->channels); AST_LIST_TRAVERSE_SAFE_BEGIN(&dial->channels, channel, list) { /* Disable any enabled options */ for (i = 0; i < AST_DIAL_OPTION_MAX; i++) { if (!channel->options[i]) continue; if (option_types[i].disable) option_types[i].disable(channel->options[i]); channel->options[i] = NULL; } /* Hang up channel if need be */ if (channel->owner) { ast_hangup(channel->owner); channel->owner = NULL; } /* Free structure */ ast_free(channel->tech); ast_free(channel->device); AST_LIST_REMOVE_CURRENT(list); ast_free(channel); } AST_LIST_TRAVERSE_SAFE_END; AST_LIST_UNLOCK(&dial->channels); /* Disable any enabled options globally */ for (i = 0; i < AST_DIAL_OPTION_MAX; i++) { if (!dial->options[i]) continue; if (option_types[i].disable) option_types[i].disable(dial->options[i]); dial->options[i] = NULL; } /* Lock be gone! */ ast_mutex_destroy(&dial->lock); /* Free structure */ ast_free(dial); return 0; }
void ast_dial_hangup | ( | struct ast_dial * | dial | ) |
Hangup channels.
dial | Dialing structure |
Definition at line 826 of file dial.c.
References ast_hangup(), AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_dial::channels, ast_dial_channel::list, and ast_dial_channel::owner.
Referenced by ast_dial_run(), and page_exec().
{ struct ast_dial_channel *channel = NULL; if (!dial) return; AST_LIST_LOCK(&dial->channels); AST_LIST_TRAVERSE(&dial->channels, channel, list) { if (channel->owner) { ast_hangup(channel->owner); channel->owner = NULL; } } AST_LIST_UNLOCK(&dial->channels); return; }
enum ast_dial_result ast_dial_join | ( | struct ast_dial * | dial | ) |
Cancel async thread.
dial | Dialing structure |
Definition at line 778 of file dial.c.
References ast_channel_lock, ast_channel_unlock, AST_DIAL_RESULT_FAILED, AST_LIST_FIRST, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_mutex_lock(), ast_mutex_unlock(), AST_PTHREADT_NULL, AST_PTHREADT_STOP, ast_softhangup(), AST_SOFTHANGUP_EXPLICIT, chan, ast_dial::channels, ast_dial::lock, ast_dial::state, and ast_dial::thread.
Referenced by dial_trunk(), page_exec(), run_station(), sla_hangup_stations(), sla_ring_station(), and sla_stop_ringing_station().
{ pthread_t thread; /* If the dial structure is not running in async, return failed */ if (dial->thread == AST_PTHREADT_NULL) return AST_DIAL_RESULT_FAILED; /* Record thread */ thread = dial->thread; /* Boom, commence locking */ ast_mutex_lock(&dial->lock); /* Stop the thread */ dial->thread = AST_PTHREADT_STOP; /* If the answered channel is running an application we have to soft hangup it, can't just poke the thread */ AST_LIST_LOCK(&dial->channels); if (AST_LIST_FIRST(&dial->channels)->is_running_app) { struct ast_channel *chan = AST_LIST_FIRST(&dial->channels)->owner; if (chan) { ast_channel_lock(chan); ast_softhangup(chan, AST_SOFTHANGUP_EXPLICIT); ast_channel_unlock(chan); } } else { /* Now we signal it with SIGURG so it will break out of it's waitfor */ pthread_kill(thread, SIGURG); } AST_LIST_UNLOCK(&dial->channels); /* Yay done with it */ ast_mutex_unlock(&dial->lock); /* Finally wait for the thread to exit */ pthread_join(thread, NULL); /* Yay thread is all gone */ dial->thread = AST_PTHREADT_NULL; return dial->state; }
int ast_dial_option_disable | ( | struct ast_dial * | dial, |
int | num, | ||
enum ast_dial_option | option | ||
) |
Disables an option per channel.
dial | Dial structure |
num | Channel number to disable option on |
option | Option to disable |
Definition at line 1002 of file dial.c.
References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::disable, find_dial_channel(), option_types, and ast_dial_channel::options.
{ struct ast_dial_channel *channel = NULL; /* Ensure we have required arguments */ if (!dial || AST_LIST_EMPTY(&dial->channels)) return -1; if (!(channel = find_dial_channel(dial, num))) return -1; /* If the option is not enabled, return failure */ if (!channel->options[option]) return -1; /* Execute callback of option to disable it if it exists */ if (option_types[option].disable) option_types[option].disable(channel->options[option]); /* Finally disable the option on the structure */ channel->options[option] = NULL; return 0; }
int ast_dial_option_enable | ( | struct ast_dial * | dial, |
int | num, | ||
enum ast_dial_option | option, | ||
void * | data | ||
) |
Enables an option per channel.
dial | Dial structure |
num | Channel number to enable option on |
option | Option to enable |
data | Data to pass to this option (not always needed) |
Definition at line 950 of file dial.c.
References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::enable, find_dial_channel(), option_types, and ast_dial_channel::options.
{ struct ast_dial_channel *channel = NULL; /* Ensure we have required arguments */ if (!dial || AST_LIST_EMPTY(&dial->channels)) return -1; if (!(channel = find_dial_channel(dial, num))) return -1; /* If the option is already enabled, return failure */ if (channel->options[option]) return -1; /* Execute enable callback if it exists, if not simply make sure the value is set */ if (option_types[option].enable) channel->options[option] = option_types[option].enable(data); else channel->options[option] = (void*)1; return 0; }
int ast_dial_option_global_disable | ( | struct ast_dial * | dial, |
enum ast_dial_option | option | ||
) |
Disables an option globally.
dial | Dial structure to disable option on |
option | Option to disable |
Definition at line 979 of file dial.c.
References ast_option_types::disable, option_types, and ast_dial::options.
{ /* If the option is not enabled, return failure */ if (!dial->options[option]) { return -1; } /* Execute callback of option to disable if it exists */ if (option_types[option].disable) option_types[option].disable(dial->options[option]); /* Finally disable option on the structure */ dial->options[option] = NULL; return 0; }
int ast_dial_option_global_enable | ( | struct ast_dial * | dial, |
enum ast_dial_option | option, | ||
void * | data | ||
) |
Enables an option globally.
dial | Dial structure to enable option on |
option | Option to enable |
data | Data to pass to this option (not always needed) |
Definition at line 907 of file dial.c.
References ast_option_types::enable, option_types, and ast_dial::options.
Referenced by page_exec().
{ /* If the option is already enabled, return failure */ if (dial->options[option]) return -1; /* Execute enable callback if it exists, if not simply make sure the value is set */ if (option_types[option].enable) dial->options[option] = option_types[option].enable(data); else dial->options[option] = (void*)1; return 0; }
enum ast_dial_result ast_dial_run | ( | struct ast_dial * | dial, |
struct ast_channel * | chan, | ||
int | async | ||
) |
Execute dialing synchronously or asynchronously.
Definition at line 698 of file dial.c.
References ast_debug, ast_dial_hangup(), AST_DIAL_RESULT_FAILED, AST_DIAL_RESULT_INVALID, AST_DIAL_RESULT_TRYING, AST_LIST_EMPTY, ast_pthread_create, async_dial(), begin_dial(), ast_dial::channels, monitor_dial(), ast_dial::state, and ast_dial::thread.
Referenced by dial_trunk(), page_exec(), and sla_ring_station().
{ enum ast_dial_result res = AST_DIAL_RESULT_TRYING; /* Ensure required arguments are passed */ if (!dial || (!chan && !async)) { ast_debug(1, "invalid #1\n"); return AST_DIAL_RESULT_INVALID; } /* If there are no channels to dial we can't very well try to dial them */ if (AST_LIST_EMPTY(&dial->channels)) { ast_debug(1, "invalid #2\n"); return AST_DIAL_RESULT_INVALID; } /* Dial each requested channel */ if (!begin_dial(dial, chan)) return AST_DIAL_RESULT_FAILED; /* If we are running async spawn a thread and send it away... otherwise block here */ if (async) { dial->state = AST_DIAL_RESULT_TRYING; /* Try to create a thread */ if (ast_pthread_create(&dial->thread, NULL, async_dial, dial)) { /* Failed to create the thread - hangup all dialed channels and return failed */ ast_dial_hangup(dial); res = AST_DIAL_RESULT_FAILED; } } else { res = monitor_dial(dial, chan); } return res; }
void ast_dial_set_global_timeout | ( | struct ast_dial * | dial, |
int | timeout | ||
) |
Set the maximum time (globally) allowed for trying to ring phones.
dial | The dial structure to apply the time limit to |
timeout | Maximum time allowed in milliseconds |
dial | The dial structure to apply the time limit to |
timeout | Maximum time allowed |
Definition at line 1037 of file dial.c.
References ast_dial::actual_timeout, and ast_dial::timeout.
Referenced by page_exec().
{ dial->timeout = timeout; if (dial->timeout > 0 && (dial->actual_timeout > dial->timeout || dial->actual_timeout == -1)) dial->actual_timeout = dial->timeout; return; }
void ast_dial_set_state_callback | ( | struct ast_dial * | dial, |
ast_dial_state_callback | callback | ||
) |
Set a callback for state changes.
dial | The dial structure to watch for state changes |
callback | the callback |
Definition at line 1027 of file dial.c.
References ast_dial::state_callback.
Referenced by sla_ring_station().
{ dial->state_callback = callback; }
void ast_dial_set_timeout | ( | struct ast_dial * | dial, |
int | num, | ||
int | timeout | ||
) |
Set the maximum time (per channel) allowed for trying to ring the phone.
dial | The dial structure the channel belongs to |
num | Channel number to set timeout on |
timeout | Maximum time allowed in milliseconds |
dial | The dial structure the channel belongs to |
num | Channel number to set timeout on |
timeout | Maximum time allowed |
Definition at line 1053 of file dial.c.
References ast_dial::actual_timeout, find_dial_channel(), ast_dial::timeout, and ast_dial_channel::timeout.
{ struct ast_dial_channel *channel = NULL; if (!(channel = find_dial_channel(dial, num))) return; channel->timeout = timeout; if (channel->timeout > 0 && (dial->actual_timeout > channel->timeout || dial->actual_timeout == -1)) dial->actual_timeout = channel->timeout; return; }
enum ast_dial_result ast_dial_state | ( | struct ast_dial * | dial | ) |
Return state of dial.
dial | Dialing structure |
Definition at line 769 of file dial.c.
References ast_dial::state.
Referenced by dial_trunk(), and sla_handle_dial_state_event().
{ return dial->state; }