Wed Jan 8 2020 09:50:11

Asterisk developer's documentation


dial.h File Reference

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_channelast_dial_answered (struct ast_dial *dial)
 Return channel that answered. More...
 
struct ast_channelast_dial_answered_steal (struct ast_dial *dial)
 Steal the channel that answered. More...
 
int ast_dial_append (struct ast_dial *dial, const char *tech, const char *device)
 Append a channel. More...
 
struct ast_dialast_dial_create (void)
 New dialing structure. More...
 
int ast_dial_destroy (struct ast_dial *dial)
 Destroys a dialing structure. More...
 
void ast_dial_hangup (struct ast_dial *dial)
 Hangup channels. More...
 
enum ast_dial_result ast_dial_join (struct ast_dial *dial)
 Cancel async thread. More...
 
int ast_dial_option_disable (struct ast_dial *dial, int num, enum ast_dial_option option)
 Disables an option per channel. More...
 
int ast_dial_option_enable (struct ast_dial *dial, int num, enum ast_dial_option option, void *data)
 Enables an option per channel. More...
 
int ast_dial_option_global_disable (struct ast_dial *dial, enum ast_dial_option option)
 Disables an option globally. More...
 
int ast_dial_option_global_enable (struct ast_dial *dial, enum ast_dial_option option, void *data)
 Enables an option globally. More...
 
enum ast_dial_result ast_dial_run (struct ast_dial *dial, struct ast_channel *chan, int async)
 Execute dialing synchronously or asynchronously. More...
 
void ast_dial_set_global_timeout (struct ast_dial *dial, int timeout)
 Set the maximum time (globally) allowed for trying to ring phones. More...
 
void ast_dial_set_state_callback (struct ast_dial *dial, ast_dial_state_callback callback)
 Set a callback for state changes. More...
 
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. More...
 
enum ast_dial_result ast_dial_state (struct ast_dial *dial)
 Return state of dial. More...
 

Detailed Description

Dialing API.

Definition in file dial.h.

Typedef Documentation

typedef void(* ast_dial_state_callback)(struct ast_dial *)

Definition at line 36 of file dial.h.

Enumeration Type Documentation

List of options that are applicable either globally or per dialed channel.

Enumerator
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

Definition at line 39 of file dial.h.

39  {
40  AST_DIAL_OPTION_RINGING, /*!< Always indicate ringing to caller */
41  AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */
42  AST_DIAL_OPTION_MUSIC, /*!< Play music on hold instead of ringing to the calling channel */
43  AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */
44  AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */
45 };

List of return codes for dial run API calls.

Enumerator
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

Definition at line 48 of file dial.h.

48  {
49  AST_DIAL_RESULT_INVALID, /*!< Invalid options were passed to run function */
50  AST_DIAL_RESULT_FAILED, /*!< Attempts to dial failed before reaching critical state */
51  AST_DIAL_RESULT_TRYING, /*!< Currently trying to dial */
52  AST_DIAL_RESULT_RINGING, /*!< Dial is presently ringing */
53  AST_DIAL_RESULT_PROGRESS, /*!< Dial is presently progressing */
54  AST_DIAL_RESULT_PROCEEDING, /*!< Dial is presently proceeding */
55  AST_DIAL_RESULT_ANSWERED, /*!< A channel was answered */
56  AST_DIAL_RESULT_TIMEOUT, /*!< Timeout was tripped, nobody answered */
57  AST_DIAL_RESULT_HANGUP, /*!< Caller hung up */
58  AST_DIAL_RESULT_UNANSWERED, /*!< Nobody answered */
59 };

Function Documentation

struct ast_channel* ast_dial_answered ( struct ast_dial dial)

Return channel that answered.

Note
Returns the Asterisk channel that answered
Parameters
dialDialing structure

Definition at line 754 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().

755 {
756  if (!dial)
757  return NULL;
758 
759  return ((dial->state == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL);
760 }
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:420
struct ast_dial::@252 channels
enum ast_dial_result state
Definition: dial.c:51
struct ast_channel* ast_dial_answered_steal ( struct ast_dial dial)

Steal the channel that answered.

Note
Returns the Asterisk channel that answered and removes it from the dialing structure
Parameters
dialDialing structure

Definition at line 766 of file dial.c.

References AST_DIAL_RESULT_ANSWERED, AST_LIST_FIRST, ast_dial::channels, and ast_dial::state.

Referenced by do_notify().

767 {
768  struct ast_channel *chan = NULL;
769 
770  if (!dial)
771  return NULL;
772 
773  if (dial->state == AST_DIAL_RESULT_ANSWERED) {
774  chan = AST_LIST_FIRST(&dial->channels)->owner;
775  AST_LIST_FIRST(&dial->channels)->owner = NULL;
776  }
777 
778  return chan;
779 }
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:420
struct ast_dial::@252 channels
enum ast_dial_result state
Definition: dial.c:51
int ast_dial_append ( struct ast_dial dial,
const char *  tech,
const char *  device 
)

Append a channel.

Note
Appends a channel to a dialing structure
Returns
Returns channel reference number on success, -1 on failure

Definition at line 229 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(), do_notify(), page_exec(), and sla_ring_station().

230 {
231  struct ast_dial_channel *channel = NULL;
232 
233  /* Make sure we have required arguments */
234  if (!dial || !tech || !device)
235  return -1;
236 
237  /* Allocate new memory for dialed channel structure */
238  if (!(channel = ast_calloc(1, sizeof(*channel))))
239  return -1;
240 
241  /* Record technology and device for when we actually dial */
242  channel->tech = ast_strdup(tech);
243  channel->device = ast_strdup(device);
244 
245  /* Grab reference number from dial structure */
246  channel->num = ast_atomic_fetchadd_int(&dial->num, +1);
247 
248  /* No timeout exists... yet */
249  channel->timeout = -1;
250 
251  /* Insert into channels list */
252  AST_LIST_INSERT_TAIL(&dial->channels, channel, list);
253 
254  return channel->num;
255 }
#define ast_strdup(a)
Definition: astmm.h:109
struct ast_dial::@252 channels
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return * the previous value of *p. This can be used to handle reference co...
Definition: lock.h:603
int num
Definition: dial.c:48
char * tech
Definition: dial.c:63
#define AST_LIST_INSERT_TAIL(head, elm, field)
Appends a list entry to the tail of a list.
Definition: linkedlists.h:716
struct ast_dial_channel::@253 list
#define ast_calloc(a, b)
Definition: astmm.h:82
char * device
Definition: dial.c:64
int timeout
Definition: dial.c:62
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
struct ast_dial* ast_dial_create ( void  )

New dialing structure.

Note
Create a dialing structure
Returns
Returns a calloc'd ast_dial structure, NULL on failure

Definition at line 201 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(), do_notify(), page_exec(), and sla_ring_station().

202 {
203  struct ast_dial *dial = NULL;
204 
205  /* Allocate new memory for structure */
206  if (!(dial = ast_calloc(1, sizeof(*dial))))
207  return NULL;
208 
209  /* Initialize list of channels */
211 
212  /* Initialize thread to NULL */
213  dial->thread = AST_PTHREADT_NULL;
214 
215  /* No timeout exists... yet */
216  dial->timeout = -1;
217  dial->actual_timeout = -1;
218 
219  /* Can't forget about the lock */
220  ast_mutex_init(&dial->lock);
221 
222  return dial;
223 }
Main dialing structure. Contains global options, channels being dialed, and more! ...
Definition: dial.c:47
struct ast_dial::@252 channels
pthread_t thread
Definition: dial.c:55
#define AST_PTHREADT_NULL
Definition: lock.h:65
ast_mutex_t lock
Definition: dial.c:54
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:611
#define ast_calloc(a, b)
Definition: astmm.h:82
int timeout
Definition: dial.c:49
int actual_timeout
Definition: dial.c:50
#define ast_mutex_init(pmutex)
Definition: lock.h:152
int ast_dial_destroy ( struct ast_dial dial)

Destroys a dialing structure.

Note
Cancels dialing and destroys (free's) the given ast_dial structure
Parameters
dialDialing structure to free
Returns
Returns 0 on success, -1 on failure
Note
Destroys (free's) the given ast_dial structure
Parameters
dialDialing structure to free
Returns
Returns 0 on success, -1 on failure

Definition at line 866 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, ast_dial::options, ast_dial_channel::options, ast_dial_channel::owner, and ast_dial_channel::tech.

Referenced by dial_trunk(), do_notify(), page_exec(), run_station(), sla_handle_dial_state_event(), sla_hangup_stations(), sla_ring_station(), and sla_stop_ringing_station().

867 {
868  int i = 0;
869  struct ast_dial_channel *channel = NULL;
870 
871  if (!dial)
872  return -1;
873 
874  /* Hangup and deallocate all the dialed channels */
875  AST_LIST_LOCK(&dial->channels);
876  AST_LIST_TRAVERSE_SAFE_BEGIN(&dial->channels, channel, list) {
877  /* Disable any enabled options */
878  for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
879  if (!channel->options[i])
880  continue;
881  if (option_types[i].disable)
882  option_types[i].disable(channel->options[i]);
883  channel->options[i] = NULL;
884  }
885  /* Hang up channel if need be */
886  if (channel->owner) {
887  ast_hangup(channel->owner);
888  channel->owner = NULL;
889  }
890  /* Free structure */
891  ast_free(channel->tech);
892  ast_free(channel->device);
894  ast_free(channel);
895  }
897  AST_LIST_UNLOCK(&dial->channels);
898 
899  /* Disable any enabled options globally */
900  for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
901  if (!dial->options[i])
902  continue;
903  if (option_types[i].disable)
904  option_types[i].disable(dial->options[i]);
905  dial->options[i] = NULL;
906  }
907 
908  /* Lock be gone! */
909  ast_mutex_destroy(&dial->lock);
910 
911  /* Free structure */
912  ast_free(dial);
913 
914  return 0;
915 }
int ast_hangup(struct ast_channel *chan)
Hang up a channel.
Definition: channel.c:2804
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
struct ast_dial::@252 channels
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:600
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:52
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:554
char * tech
Definition: dial.c:63
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:65
struct ast_channel * owner
Definition: dial.c:68
ast_mutex_t lock
Definition: dial.c:54
#define ast_free(a)
Definition: astmm.h:97
struct ast_dial_channel::@253 list
static struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:180
ast_dial_option_cb_disable disable
Definition: dial.c:171
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:528
#define ast_mutex_destroy(a)
Definition: lock.h:154
char * device
Definition: dial.c:64
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
void ast_dial_hangup ( struct ast_dial dial)

Hangup channels.

Note
Hangup all active channels
Parameters
dialDialing structure

Definition at line 842 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().

843 {
844  struct ast_dial_channel *channel = NULL;
845 
846  if (!dial)
847  return;
848 
849  AST_LIST_LOCK(&dial->channels);
850  AST_LIST_TRAVERSE(&dial->channels, channel, list) {
851  if (channel->owner) {
852  ast_hangup(channel->owner);
853  channel->owner = NULL;
854  }
855  }
856  AST_LIST_UNLOCK(&dial->channels);
857 
858  return;
859 }
int ast_hangup(struct ast_channel *chan)
Hang up a channel.
Definition: channel.c:2804
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
struct ast_dial::@252 channels
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
struct ast_channel * owner
Definition: dial.c:68
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
struct ast_dial_channel::@253 list
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
enum ast_dial_result ast_dial_join ( struct ast_dial dial)

Cancel async thread.

Note
Cancel a running async thread
Parameters
dialDialing structure

Definition at line 794 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, ast_dial::channels, ast_dial::lock, ast_dial::state, and ast_dial::thread.

Referenced by dial_trunk(), page_exec(), run_station(), sla_handle_dial_state_event(), sla_hangup_stations(), sla_ring_station(), and sla_stop_ringing_station().

795 {
796  pthread_t thread;
797 
798  /* If the dial structure is not running in async, return failed */
799  if (dial->thread == AST_PTHREADT_NULL)
800  return AST_DIAL_RESULT_FAILED;
801 
802  /* Record thread */
803  thread = dial->thread;
804 
805  /* Boom, commence locking */
806  ast_mutex_lock(&dial->lock);
807 
808  /* Stop the thread */
809  dial->thread = AST_PTHREADT_STOP;
810 
811  /* If the answered channel is running an application we have to soft hangup it, can't just poke the thread */
812  AST_LIST_LOCK(&dial->channels);
813  if (AST_LIST_FIRST(&dial->channels)->is_running_app) {
814  struct ast_channel *chan = AST_LIST_FIRST(&dial->channels)->owner;
815  if (chan) {
816  ast_channel_lock(chan);
818  ast_channel_unlock(chan);
819  }
820  } else {
821  /* Now we signal it with SIGURG so it will break out of it's waitfor */
822  pthread_kill(thread, SIGURG);
823  }
824  AST_LIST_UNLOCK(&dial->channels);
825 
826  /* Yay done with it */
827  ast_mutex_unlock(&dial->lock);
828 
829  /* Finally wait for the thread to exit */
830  pthread_join(thread, NULL);
831 
832  /* Yay thread is all gone */
833  dial->thread = AST_PTHREADT_NULL;
834 
835  return dial->state;
836 }
pthread_t thread
Definition: app_meetme.c:962
#define ast_channel_lock(chan)
Definition: channel.h:2466
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:39
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:420
struct ast_dial::@252 channels
enum ast_dial_result state
Definition: dial.c:51
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:139
#define ast_mutex_lock(a)
Definition: lock.h:155
pthread_t thread
Definition: dial.c:55
#define AST_PTHREADT_NULL
Definition: lock.h:65
int ast_softhangup(struct ast_channel *chan, int reason)
Softly hangup up a channel.
Definition: channel.c:2746
ast_mutex_t lock
Definition: dial.c:54
#define ast_channel_unlock(chan)
Definition: channel.h:2467
#define AST_PTHREADT_STOP
Definition: lock.h:66
#define ast_mutex_unlock(a)
Definition: lock.h:156
int ast_dial_option_disable ( struct ast_dial dial,
int  num,
enum ast_dial_option  option 
)

Disables an option per channel.

Parameters
dialDial structure
numChannel number to disable option on
optionOption to disable
Returns
Returns 0 on success, -1 on failure

Definition at line 1018 of file dial.c.

References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::disable, find_dial_channel(), and ast_dial_channel::options.

1019 {
1020  struct ast_dial_channel *channel = NULL;
1021 
1022  /* Ensure we have required arguments */
1023  if (!dial || AST_LIST_EMPTY(&dial->channels))
1024  return -1;
1025 
1026  if (!(channel = find_dial_channel(dial, num)))
1027  return -1;
1028 
1029  /* If the option is not enabled, return failure */
1030  if (!channel->options[option])
1031  return -1;
1032 
1033  /* Execute callback of option to disable it if it exists */
1034  if (option_types[option].disable)
1035  option_types[option].disable(channel->options[option]);
1036 
1037  /* Finally disable the option on the structure */
1038  channel->options[option] = NULL;
1039 
1040  return 0;
1041 }
struct ast_dial::@252 channels
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:65
static struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:180
static struct ast_dial_channel * find_dial_channel(struct ast_dial *dial, int num)
Helper function for finding a channel in a dial structure based on number.
Definition: dial.c:940
ast_dial_option_cb_disable disable
Definition: dial.c:171
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
int ast_dial_option_enable ( struct ast_dial dial,
int  num,
enum ast_dial_option  option,
void *  data 
)

Enables an option per channel.

Parameters
dialDial structure
numChannel number to enable option on
optionOption to enable
dataData to pass to this option (not always needed)
Returns
Returns 0 on success, -1 on failure

Definition at line 966 of file dial.c.

References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::enable, find_dial_channel(), and ast_dial_channel::options.

967 {
968  struct ast_dial_channel *channel = NULL;
969 
970  /* Ensure we have required arguments */
971  if (!dial || AST_LIST_EMPTY(&dial->channels))
972  return -1;
973 
974  if (!(channel = find_dial_channel(dial, num)))
975  return -1;
976 
977  /* If the option is already enabled, return failure */
978  if (channel->options[option])
979  return -1;
980 
981  /* Execute enable callback if it exists, if not simply make sure the value is set */
982  if (option_types[option].enable)
983  channel->options[option] = option_types[option].enable(data);
984  else
985  channel->options[option] = (void*)1;
986 
987  return 0;
988 }
struct ast_dial::@252 channels
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:65
ast_dial_option_cb_enable enable
Definition: dial.c:170
static struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:180
static struct ast_dial_channel * find_dial_channel(struct ast_dial *dial, int num)
Helper function for finding a channel in a dial structure based on number.
Definition: dial.c:940
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
int ast_dial_option_global_disable ( struct ast_dial dial,
enum ast_dial_option  option 
)

Disables an option globally.

Parameters
dialDial structure to disable option on
optionOption to disable
Returns
Returns 0 on success, -1 on failure

Definition at line 995 of file dial.c.

References ast_option_types::disable, and ast_dial::options.

996 {
997  /* If the option is not enabled, return failure */
998  if (!dial->options[option]) {
999  return -1;
1000  }
1001 
1002  /* Execute callback of option to disable if it exists */
1003  if (option_types[option].disable)
1004  option_types[option].disable(dial->options[option]);
1005 
1006  /* Finally disable option on the structure */
1007  dial->options[option] = NULL;
1008 
1009  return 0;
1010 }
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:52
static struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:180
ast_dial_option_cb_disable disable
Definition: dial.c:171
int ast_dial_option_global_enable ( struct ast_dial dial,
enum ast_dial_option  option,
void *  data 
)

Enables an option globally.

Parameters
dialDial structure to enable option on
optionOption to enable
dataData to pass to this option (not always needed)
Returns
Returns 0 on success, -1 on failure

Definition at line 923 of file dial.c.

References ast_option_types::enable, and ast_dial::options.

Referenced by do_notify(), and page_exec().

924 {
925  /* If the option is already enabled, return failure */
926  if (dial->options[option])
927  return -1;
928 
929  /* Execute enable callback if it exists, if not simply make sure the value is set */
930  if (option_types[option].enable)
931  dial->options[option] = option_types[option].enable(data);
932  else
933  dial->options[option] = (void*)1;
934 
935  return 0;
936 }
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:52
ast_dial_option_cb_enable enable
Definition: dial.c:170
static struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:180
enum ast_dial_result ast_dial_run ( struct ast_dial dial,
struct ast_channel chan,
int  async 
)

Execute dialing synchronously or asynchronously.

Note
Dials channels in a dial structure.
Returns
Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED).

Definition at line 714 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(), do_notify(), page_exec(), and sla_ring_station().

715 {
717 
718  /* Ensure required arguments are passed */
719  if (!dial || (!chan && !async)) {
720  ast_debug(1, "invalid #1\n");
722  }
723 
724  /* If there are no channels to dial we can't very well try to dial them */
725  if (AST_LIST_EMPTY(&dial->channels)) {
726  ast_debug(1, "invalid #2\n");
728  }
729 
730  /* Dial each requested channel */
731  if (!begin_dial(dial, chan))
732  return AST_DIAL_RESULT_FAILED;
733 
734  /* If we are running async spawn a thread and send it away... otherwise block here */
735  if (async) {
737  /* Try to create a thread */
738  if (ast_pthread_create(&dial->thread, NULL, async_dial, dial)) {
739  /* Failed to create the thread - hangup all dialed channels and return failed */
740  ast_dial_hangup(dial);
742  }
743  } else {
744  res = monitor_dial(dial, chan);
745  }
746 
747  return res;
748 }
static int begin_dial(struct ast_dial *dial, struct ast_channel *chan)
Helper function that does the beginning dialing per dial structure.
Definition: dial.c:311
struct ast_dial::@252 channels
void ast_dial_hangup(struct ast_dial *dial)
Hangup channels.
Definition: dial.c:842
enum ast_dial_result state
Definition: dial.c:51
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
pthread_t thread
Definition: dial.c:55
#define ast_debug(level,...)
Log a DEBUG message.
Definition: logger.h:236
ast_dial_result
List of return codes for dial run API calls.
Definition: dial.h:48
static void * async_dial(void *data)
Dial async thread function.
Definition: dial.c:700
#define ast_pthread_create(a, b, c, d)
Definition: utils.h:418
static enum ast_dial_result monitor_dial(struct ast_dial *dial, struct ast_channel *chan)
Helper function that basically keeps tabs on dialing attempts.
Definition: dial.c:551
void ast_dial_set_global_timeout ( struct ast_dial dial,
int  timeout 
)

Set the maximum time (globally) allowed for trying to ring phones.

Parameters
dialThe dial structure to apply the time limit to
timeoutMaximum time allowed in milliseconds
Returns
nothing
Parameters
dialThe dial structure to apply the time limit to
timeoutMaximum time allowed
Returns
nothing

Definition at line 1053 of file dial.c.

References ast_dial::actual_timeout, and ast_dial::timeout.

Referenced by do_notify(), and page_exec().

1054 {
1055  dial->timeout = timeout;
1056 
1057  if (dial->timeout > 0 && (dial->actual_timeout > dial->timeout || dial->actual_timeout == -1))
1058  dial->actual_timeout = dial->timeout;
1059 
1060  return;
1061 }
int timeout
Definition: dial.c:49
int actual_timeout
Definition: dial.c:50
int timeout
Definition: dial.c:62
void ast_dial_set_state_callback ( struct ast_dial dial,
ast_dial_state_callback  callback 
)

Set a callback for state changes.

Parameters
dialThe dial structure to watch for state changes
callbackthe callback
Returns
nothing

Definition at line 1043 of file dial.c.

References ast_dial::state_callback.

Referenced by sla_ring_station().

1044 {
1045  dial->state_callback = callback;
1046 }
ast_dial_state_callback state_callback
Definition: dial.c:53
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.

Parameters
dialThe dial structure the channel belongs to
numChannel number to set timeout on
timeoutMaximum time allowed in milliseconds
Returns
nothing
Parameters
dialThe dial structure the channel belongs to
numChannel number to set timeout on
timeoutMaximum time allowed
Returns
nothing

Definition at line 1069 of file dial.c.

References ast_dial::actual_timeout, find_dial_channel(), ast_dial::timeout, and ast_dial_channel::timeout.

1070 {
1071  struct ast_dial_channel *channel = NULL;
1072 
1073  if (!(channel = find_dial_channel(dial, num)))
1074  return;
1075 
1076  channel->timeout = timeout;
1077 
1078  if (channel->timeout > 0 && (dial->actual_timeout > channel->timeout || dial->actual_timeout == -1))
1079  dial->actual_timeout = channel->timeout;
1080 
1081  return;
1082 }
static struct ast_dial_channel * find_dial_channel(struct ast_dial *dial, int num)
Helper function for finding a channel in a dial structure based on number.
Definition: dial.c:940
int actual_timeout
Definition: dial.c:50
int timeout
Definition: dial.c:62
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:60
enum ast_dial_result ast_dial_state ( struct ast_dial dial)

Return state of dial.

Note
Returns the state of the dial attempt
Parameters
dialDialing structure

Definition at line 785 of file dial.c.

References ast_dial::state.

Referenced by dial_trunk(), and sla_handle_dial_state_event().

786 {
787  return dial->state;
788 }
enum ast_dial_result state
Definition: dial.c:51