Asterisk - The Open Source Telephony Project  21.4.1
Typedefs | Enumerations | Functions
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_PREDIAL, AST_DIAL_OPTION_DIAL_REPLACES_SELF, AST_DIAL_OPTION_SELF_DESTROY, 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, const struct ast_assigned_ids *assignedids)
 Append a channel. More...
 
int ast_dial_append_channel (struct ast_dial *dial, struct ast_channel *chan)
 Append a channel using an actual channel object. More...
 
struct ast_dialast_dial_create (void)
 New dialing structure. More...
 
int ast_dial_destroy (struct ast_dial *dial)
 Destroys a dialing structure. More...
 
struct ast_channelast_dial_get_channel (struct ast_dial *dial, int num)
 Get the dialing channel, if prerun has been executed. More...
 
void * ast_dial_get_user_data (struct ast_dial *dial)
 Return the user data on a dial 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...
 
int ast_dial_prerun (struct ast_dial *dial, struct ast_channel *chan, struct ast_format_cap *cap)
 Request all appended channels, but do not dial. More...
 
int ast_dial_reason (struct ast_dial *dial, int num)
 Get the reason an outgoing channel has failed. 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...
 
void ast_dial_set_user_data (struct ast_dial *dial, void *user_data)
 Set user data on a dial structure. More...
 
enum ast_dial_result ast_dial_state (struct ast_dial *dial)
 Return state of dial. More...
 
const char * ast_hangup_cause_to_dial_status (int hangup_cause)
 Convert a hangup cause to a publishable dial status. More...
 

Detailed Description

Dialing API.

Definition in 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_PREDIAL 

Execute a predial subroutine before dialing

AST_DIAL_OPTION_DIAL_REPLACES_SELF 

The dial operation is a replacement for the requester

AST_DIAL_OPTION_SELF_DESTROY 

Destroy self at end of ast_dial_run

AST_DIAL_OPTION_MAX 

End terminator – must always remain last

Definition at line 42 of file dial.h.

42  {
43  AST_DIAL_OPTION_RINGING, /*!< Always indicate ringing to caller */
44  AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */
45  AST_DIAL_OPTION_MUSIC, /*!< Play music on hold instead of ringing to the calling channel */
46  AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */
47  AST_DIAL_OPTION_PREDIAL, /*!< Execute a predial subroutine before dialing */
48  AST_DIAL_OPTION_DIAL_REPLACES_SELF, /*!< The dial operation is a replacement for the requester */
49  AST_DIAL_OPTION_SELF_DESTROY, /*!< Destroy self at end of ast_dial_run */
50  AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */
51 };

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 54 of file dial.h.

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

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 977 of file dial.c.

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

Referenced by ari_originate_dial().

978 {
979  if (!dial)
980  return NULL;
981 
982  return ((dial->state == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL);
983 }
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
enum ast_dial_result state
Definition: dial.c:52
struct ast_dial::@347 channels
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 989 of file dial.c.

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

Referenced by ari_originate_dial(), pbx_outgoing_exec(), and recall_callback().

990 {
991  struct ast_channel *chan = NULL;
992 
993  if (!dial)
994  return NULL;
995 
996  if (dial->state == AST_DIAL_RESULT_ANSWERED) {
997  chan = AST_LIST_FIRST(&dial->channels)->owner;
998  AST_LIST_FIRST(&dial->channels)->owner = NULL;
999  }
1000 
1001  return chan;
1002 }
Main Channel structure associated with a channel.
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
enum ast_dial_result state
Definition: dial.c:52
struct ast_dial::@347 channels
int ast_dial_append ( struct ast_dial dial,
const char *  tech,
const char *  device,
const struct ast_assigned_ids assignedids 
)

Append a channel.

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

Definition at line 280 of file dial.c.

References ast_calloc.

Referenced by sla_ring_station().

281 {
282  struct ast_dial_channel *channel = NULL;
283 
284  /* Make sure we have required arguments */
285  if (!dial || !tech || !device)
286  return -1;
287 
288  /* Allocate new memory for dialed channel structure */
289  if (!(channel = ast_calloc(1, sizeof(*channel))))
290  return -1;
291 
292  return dial_append_common(dial, channel, tech, device, assignedids);
293 }
char * tech
Definition: dial.c:66
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
char * device
Definition: dial.c:67
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
int ast_dial_append_channel ( struct ast_dial dial,
struct ast_channel chan 
)

Append a channel using an actual channel object.

Parameters
dialThe ast_dial to add the channel to
chanThe channel to add to the dial
Return values
-1Failure
non-zeroThe position of the channel in the list of dialed channels
Note
The chan ref is stolen with a successful return.

Definition at line 295 of file dial.c.

References ast_calloc, ast_strdupa, ast_dial_channel::device, ast_dial_channel::owner, and ast_dial_channel::tech.

296 {
297  struct ast_dial_channel *channel;
298  char *tech;
299  char *device;
300  char *dash;
301 
302  if (!dial || !chan) {
303  return -1;
304  }
305 
306  channel = ast_calloc(1, sizeof(*channel));
307  if (!channel) {
308  return -1;
309  }
310  channel->owner = chan;
311 
312  tech = ast_strdupa(ast_channel_name(chan));
313 
314  device = strchr(tech, '/');
315  if (!device) {
316  ast_free(channel);
317  return -1;
318  }
319  *device++ = '\0';
320 
321  dash = strrchr(device, '-');
322  if (dash) {
323  *dash = '\0';
324  }
325 
326  return dial_append_common(dial, channel, tech, device, NULL);
327 }
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
char * tech
Definition: dial.c:66
struct ast_channel * owner
Definition: dial.c:73
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
char * device
Definition: dial.c:67
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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 223 of file dial.c.

References ast_dial::actual_timeout, ast_calloc, AST_LIST_HEAD_INIT, ast_dial::channels, ast_dial::thread, and ast_dial::timeout.

Referenced by sla_ring_station().

224 {
225  struct ast_dial *dial = NULL;
226 
227  /* Allocate new memory for structure */
228  if (!(dial = ast_calloc(1, sizeof(*dial))))
229  return NULL;
230 
231  /* Initialize list of channels */
233 
234  /* Initialize thread to NULL */
235  dial->thread = AST_PTHREADT_NULL;
236 
237  /* No timeout exists... yet */
238  dial->timeout = -1;
239  dial->actual_timeout = -1;
240 
241  /* Can't forget about the lock */
242  ast_mutex_init(&dial->lock);
243 
244  return dial;
245 }
Main dialing structure. Contains global options, channels being dialed, and more! ...
Definition: dial.c:48
pthread_t thread
Definition: dial.c:57
struct ast_dial::@347 channels
#define AST_LIST_HEAD_INIT(head)
Initializes a list head structure.
Definition: linkedlists.h:626
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
int timeout
Definition: dial.c:50
int actual_timeout
Definition: dial.c:51
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
Return values
0on success
-1on failure

Definition at line 1091 of file dial.c.

References ast_dial_channel::assignedid1, ast_dial_channel::assignedid2, AST_DIAL_OPTION_MAX, ast_hangup(), AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_dial::channels, ast_dial_channel::device, ast_dial_channel::list, ast_dial::options, ast_dial_channel::options, ast_dial_channel::owner, and ast_dial_channel::tech.

Referenced by ari_originate_dial(), monitor_dial(), pbx_outgoing_destroy(), and sla_ring_station().

1092 {
1093  int i = 0;
1094  struct ast_dial_channel *channel = NULL;
1095 
1096  if (!dial)
1097  return -1;
1098 
1099  /* Hangup and deallocate all the dialed channels */
1100  AST_LIST_LOCK(&dial->channels);
1101  AST_LIST_TRAVERSE_SAFE_BEGIN(&dial->channels, channel, list) {
1102  /* Disable any enabled options */
1103  for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
1104  if (!channel->options[i])
1105  continue;
1106  if (option_types[i].disable)
1107  option_types[i].disable(channel->options[i]);
1108  channel->options[i] = NULL;
1109  }
1110 
1111  /* Hang up channel if need be */
1112  ast_hangup(channel->owner);
1113  channel->owner = NULL;
1114 
1115  /* Free structure */
1116  ast_free(channel->tech);
1117  ast_free(channel->device);
1118  ast_free(channel->assignedid1);
1119  ast_free(channel->assignedid2);
1120 
1122  ast_free(channel);
1123  }
1125  AST_LIST_UNLOCK(&dial->channels);
1126 
1127  /* Disable any enabled options globally */
1128  for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
1129  if (!dial->options[i])
1130  continue;
1131  if (option_types[i].disable)
1132  option_types[i].disable(dial->options[i]);
1133  dial->options[i] = NULL;
1134  }
1135 
1136  /* Lock be gone! */
1137  ast_mutex_destroy(&dial->lock);
1138 
1139  /* Free structure */
1140  ast_free(dial);
1141 
1142  return 0;
1143 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
char * assignedid2
Definition: dial.c:72
#define AST_LIST_TRAVERSE_SAFE_END
Closes a safe loop traversal block.
Definition: linkedlists.h:615
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:53
struct ast_dial::@347 channels
#define AST_LIST_REMOVE_CURRENT(field)
Removes the current entry from a list during a traversal.
Definition: linkedlists.h:557
char * tech
Definition: dial.c:66
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:68
struct ast_channel * owner
Definition: dial.c:73
static const struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:199
void ast_hangup(struct ast_channel *chan)
Hang up a channel.
Definition: channel.c:2541
char * assignedid1
Definition: dial.c:71
#define AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
Loops safely over (traverses) the entries in a list.
Definition: linkedlists.h:529
struct ast_dial_channel::@348 list
char * device
Definition: dial.c:67
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
struct ast_channel* ast_dial_get_channel ( struct ast_dial dial,
int  num 
)

Get the dialing channel, if prerun has been executed.

Parameters
dialDial structure
numChannel number to get channel of
Returns
Pointer to channel, without reference

Definition at line 1258 of file dial.c.

References AST_LIST_EMPTY, ast_dial::channels, find_dial_channel(), and ast_dial_channel::owner.

Referenced by pbx_outgoing_state_callback().

1259 {
1260  struct ast_dial_channel *channel;
1261 
1262  if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
1263  return NULL;
1264  }
1265 
1266  return channel->owner;
1267 }
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:450
struct ast_dial::@347 channels
struct ast_channel * owner
Definition: dial.c:73
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:1162
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
void* ast_dial_get_user_data ( struct ast_dial dial)

Return the user data on a dial structure.

Parameters
dialThe dial structure

Definition at line 1279 of file dial.c.

References ast_dial::user_data.

Referenced by ari_originate_dial(), and recall_callback().

1280 {
1281  return dial->user_data;
1282 }
void * user_data
Definition: dial.c:55
void ast_dial_hangup ( struct ast_dial dial)

Hangup channels.

Note
Hangup all active channels
Parameters
dialDialing structure

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

1075 {
1076  struct ast_dial_channel *channel = NULL;
1077 
1078  if (!dial)
1079  return;
1080 
1081  AST_LIST_LOCK(&dial->channels);
1082  AST_LIST_TRAVERSE(&dial->channels, channel, list) {
1083  ast_hangup(channel->owner);
1084  channel->owner = NULL;
1085  }
1086  AST_LIST_UNLOCK(&dial->channels);
1087 
1088  return;
1089 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
struct ast_dial::@347 channels
struct ast_channel * owner
Definition: dial.c:73
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
void ast_hangup(struct ast_channel *chan)
Hang up a channel.
Definition: channel.c:2541
struct ast_dial_channel::@348 list
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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 1017 of file dial.c.

References AST_DIAL_RESULT_FAILED, AST_LIST_FIRST, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_softhangup(), AST_SOFTHANGUP_EXPLICIT, ast_dial::channels, ast_dial_channel::list, ast_dial_channel::owner, ast_dial::state, and ast_dial::thread.

Referenced by sla_ring_station().

1018 {
1019  pthread_t thread;
1020 
1021  /* If the dial structure is not running in async, return failed */
1022  if (dial->thread == AST_PTHREADT_NULL)
1023  return AST_DIAL_RESULT_FAILED;
1024 
1025  /* Record thread */
1026  thread = dial->thread;
1027 
1028  /* Boom, commence locking */
1029  ast_mutex_lock(&dial->lock);
1030 
1031  /* Stop the thread */
1032  dial->thread = AST_PTHREADT_STOP;
1033 
1034  /* If the answered channel is running an application we have to soft hangup it, can't just poke the thread */
1035  AST_LIST_LOCK(&dial->channels);
1036  if (AST_LIST_FIRST(&dial->channels)->is_running_app) {
1037  struct ast_channel *chan = AST_LIST_FIRST(&dial->channels)->owner;
1038  if (chan) {
1039  ast_channel_lock(chan);
1041  ast_channel_unlock(chan);
1042  }
1043  } else {
1044  struct ast_dial_channel *channel = NULL;
1045 
1046  /* Now we signal it with SIGURG so it will break out of it's waitfor */
1047  pthread_kill(thread, SIGURG);
1048 
1049  /* pthread_kill may not be enough, if outgoing channel has already got an answer (no more in waitfor) but is not yet running an application. Force soft hangup. */
1050  AST_LIST_TRAVERSE(&dial->channels, channel, list) {
1051  if (channel->owner) {
1053  }
1054  }
1055  }
1056  AST_LIST_UNLOCK(&dial->channels);
1057 
1058  /* Yay done with it */
1059  ast_mutex_unlock(&dial->lock);
1060 
1061  /* Finally wait for the thread to exit */
1062  pthread_join(thread, NULL);
1063 
1064  /* Yay thread is all gone */
1065  dial->thread = AST_PTHREADT_NULL;
1066 
1067  return dial->state;
1068 }
Main Channel structure associated with a channel.
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_FIRST(head)
Returns the first entry contained in a list.
Definition: linkedlists.h:421
enum ast_dial_result state
Definition: dial.c:52
int ast_softhangup(struct ast_channel *chan, int cause)
Softly hangup up a channel.
Definition: channel.c:2471
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
pthread_t thread
Definition: app_sla.c:329
pthread_t thread
Definition: dial.c:57
struct ast_dial::@347 channels
struct ast_channel * owner
Definition: dial.c:73
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
struct ast_dial_channel::@348 list
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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
Return values
0on success
-1on failure

Definition at line 1222 of file dial.c.

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

1223 {
1224  struct ast_dial_channel *channel = NULL;
1225 
1226  /* Ensure we have required arguments */
1227  if (!dial || AST_LIST_EMPTY(&dial->channels))
1228  return -1;
1229 
1230  if (!(channel = find_dial_channel(dial, num)))
1231  return -1;
1232 
1233  /* If the option is not enabled, return failure */
1234  if (!channel->options[option])
1235  return -1;
1236 
1237  /* Execute callback of option to disable it if it exists */
1238  if (option_types[option].disable)
1239  option_types[option].disable(channel->options[option]);
1240 
1241  /* Finally disable the option on the structure */
1242  channel->options[option] = NULL;
1243 
1244  return 0;
1245 }
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:450
struct ast_dial::@347 channels
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:68
static const struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:199
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:1162
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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)
Return values
0on success
-1on failure

Definition at line 1181 of file dial.c.

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

1182 {
1183  struct ast_dial_channel *channel = NULL;
1184 
1185  /* Ensure we have required arguments */
1186  if (!dial || AST_LIST_EMPTY(&dial->channels))
1187  return -1;
1188 
1189  if (!(channel = find_dial_channel(dial, num)))
1190  return -1;
1191 
1192  /* If the option is already enabled, return failure */
1193  if (channel->options[option])
1194  return -1;
1195 
1196  /* Execute enable callback if it exists, if not simply make sure the value is set */
1197  if (option_types[option].enable)
1198  channel->options[option] = option_types[option].enable(data);
1199  else
1200  channel->options[option] = (void*)1;
1201 
1202  return 0;
1203 }
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:450
struct ast_dial::@347 channels
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:68
static const struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:199
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:1162
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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
Return values
0on success
-1on failure

Definition at line 1205 of file dial.c.

References ast_dial::options.

1206 {
1207  /* If the option is not enabled, return failure */
1208  if (!dial->options[option]) {
1209  return -1;
1210  }
1211 
1212  /* Execute callback of option to disable if it exists */
1213  if (option_types[option].disable)
1214  option_types[option].disable(dial->options[option]);
1215 
1216  /* Finally disable option on the structure */
1217  dial->options[option] = NULL;
1218 
1219  return 0;
1220 }
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:53
static const struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:199
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)
Return values
0on success
-1on failure

Definition at line 1145 of file dial.c.

References ast_dial::options.

1146 {
1147  /* If the option is already enabled, return failure */
1148  if (dial->options[option])
1149  return -1;
1150 
1151  /* Execute enable callback if it exists, if not simply make sure the value is set */
1152  if (option_types[option].enable)
1153  dial->options[option] = option_types[option].enable(data);
1154  else
1155  dial->options[option] = (void*)1;
1156 
1157  return 0;
1158 }
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:53
static const struct ast_option_types option_types[]
Map options to respective handlers (enable/disable).
Definition: dial.c:199
int ast_dial_prerun ( struct ast_dial dial,
struct ast_channel chan,
struct ast_format_cap cap 
)

Request all appended channels, but do not dial.

Parameters
dialDialing structure
chanOptional dialing channel
capOptional requested capabilities
Return values
-1failure
0success

Definition at line 431 of file dial.c.

References AST_DIAL_OPTION_PREDIAL, AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, begin_dial_prerun(), ast_dial::channels, ast_dial_channel::list, and ast_dial::options.

432 {
433  struct ast_dial_channel *channel;
434  int res = -1;
435  char *predial_string = dial->options[AST_DIAL_OPTION_PREDIAL];
436 
437  AST_LIST_LOCK(&dial->channels);
438  AST_LIST_TRAVERSE(&dial->channels, channel, list) {
439  if ((res = begin_dial_prerun(channel, chan, cap, predial_string))) {
440  break;
441  }
442  }
443  AST_LIST_UNLOCK(&dial->channels);
444 
445  return res;
446 }
#define AST_LIST_LOCK(head)
Locks a list.
Definition: linkedlists.h:40
#define AST_LIST_UNLOCK(head)
Attempts to unlock a list.
Definition: linkedlists.h:140
void * options[AST_DIAL_OPTION_MAX]
Definition: dial.c:53
struct ast_dial::@347 channels
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:491
static int begin_dial_prerun(struct ast_dial_channel *channel, struct ast_channel *chan, struct ast_format_cap *cap, const char *predial_string)
Helper function that requests all channels.
Definition: dial.c:330
struct ast_dial_channel::@348 list
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
int ast_dial_reason ( struct ast_dial dial,
int  num 
)

Get the reason an outgoing channel has failed.

Parameters
dialDial structure
numChannel number to get the reason from
Returns
Numerical cause code

Definition at line 1247 of file dial.c.

References AST_LIST_EMPTY, ast_dial_channel::cause, ast_dial::channels, and find_dial_channel().

1248 {
1249  struct ast_dial_channel *channel;
1250 
1251  if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
1252  return -1;
1253  }
1254 
1255  return channel->cause;
1256 }
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:450
struct ast_dial::@347 channels
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:1162
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
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 935 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_read_threadstorage_callid(), async_dial(), begin_dial(), ast_dial::callid, ast_dial::channels, monitor_dial(), ast_dial::state, and ast_dial::thread.

Referenced by ari_originate_dial(), pbx_outgoing_exec(), and sla_ring_station().

936 {
938 
939  /* Ensure required arguments are passed */
940  if (!dial) {
941  ast_debug(1, "invalid #1\n");
943  }
944 
945  /* If there are no channels to dial we can't very well try to dial them */
946  if (AST_LIST_EMPTY(&dial->channels)) {
947  ast_debug(1, "invalid #2\n");
949  }
950 
951  /* Dial each requested channel */
952  if (!begin_dial(dial, chan, async))
953  return AST_DIAL_RESULT_FAILED;
954 
955  /* If we are running async spawn a thread and send it away... otherwise block here */
956  if (async) {
957  /* reference be released at dial destruction if it isn't NULL */
960  /* Try to create a thread */
961  if (ast_pthread_create(&dial->thread, NULL, async_dial, dial)) {
962  /* Failed to create the thread - hangup all dialed channels and return failed */
963  ast_dial_hangup(dial);
965  }
966  } else {
967  res = monitor_dial(dial, chan);
968  }
969 
970  return res;
971 }
void ast_dial_hangup(struct ast_dial *dial)
Hangup channels.
Definition: dial.c:1074
enum ast_dial_result state
Definition: dial.c:52
static int begin_dial(struct ast_dial *dial, struct ast_channel *chan, int async)
Helper function that does the beginning dialing per dial structure.
Definition: dial.c:481
ast_callid ast_read_threadstorage_callid(void)
extracts the callerid from the thread
Definition: logger.c:2298
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:450
ast_callid callid
Definition: dial.c:58
pthread_t thread
Definition: dial.c:57
ast_dial_result
List of return codes for dial run API calls.
Definition: dial.h:54
struct ast_dial::@347 channels
#define ast_debug(level,...)
Log a DEBUG message.
static void * async_dial(void *data)
Dial async thread function.
Definition: dial.c:918
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:766
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

Definition at line 1284 of file dial.c.

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

1285 {
1286  dial->timeout = timeout;
1287 
1288  if (dial->timeout > 0 && (dial->actual_timeout > dial->timeout || dial->actual_timeout == -1))
1289  dial->actual_timeout = dial->timeout;
1290 
1291  return;
1292 }
int timeout
Definition: dial.c:50
int actual_timeout
Definition: dial.c:51
int timeout
Definition: dial.c:65
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

Definition at line 1269 of file dial.c.

References ast_dial::state_callback.

Referenced by sla_ring_station().

1270 {
1271  dial->state_callback = callback;
1272 }
ast_dial_state_callback state_callback
Definition: dial.c:54
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

Definition at line 1294 of file dial.c.

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

1295 {
1296  struct ast_dial_channel *channel = NULL;
1297 
1298  if (!(channel = find_dial_channel(dial, num)))
1299  return;
1300 
1301  channel->timeout = timeout;
1302 
1303  if (channel->timeout > 0 && (dial->actual_timeout > channel->timeout || dial->actual_timeout == -1))
1304  dial->actual_timeout = channel->timeout;
1305 
1306  return;
1307 }
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:1162
int actual_timeout
Definition: dial.c:51
int timeout
Definition: dial.c:65
Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more!
Definition: dial.c:63
void ast_dial_set_user_data ( struct ast_dial dial,
void *  user_data 
)

Set user data on a dial structure.

Parameters
dialThe dial structure to set a user data pointer on
user_dataThe user data pointer

Definition at line 1274 of file dial.c.

References ast_dial::user_data.

1275 {
1276  dial->user_data = user_data;
1277 }
void * user_data
Definition: dial.c:55
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 1008 of file dial.c.

References ast_dial::state.

Referenced by pbx_outgoing_state_callback(), and recall_callback().

1009 {
1010  return dial->state;
1011 }
enum ast_dial_result state
Definition: dial.c:52
const char* ast_hangup_cause_to_dial_status ( int  hangup_cause)

Convert a hangup cause to a publishable dial status.

Since
12

Definition at line 749 of file dial.c.

Referenced by monitor_dial().

750 {
751  switch(hangup_cause) {
752  case AST_CAUSE_BUSY:
753  return "BUSY";
754  case AST_CAUSE_CONGESTION:
755  return "CONGESTION";
756  case AST_CAUSE_NO_ROUTE_DESTINATION:
757  case AST_CAUSE_UNREGISTERED:
758  return "CHANUNAVAIL";
759  case AST_CAUSE_NO_ANSWER:
760  default:
761  return "NOANSWER";
762  }
763 }