dial.h File Reference

Dialing API. More...

This graph shows which files directly or indirectly include this file:

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_channel *	ast_dial_answered (struct ast_dial *dial)
	Return channel that answered. More...
struct ast_channel *	ast_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_dial *	ast_dial_create (void)
	New dialing structure. More...
int	ast_dial_destroy (struct ast_dial *dial)
	Destroys a dialing structure. More...
struct ast_channel *	ast_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.

Typedef Documentation

ast_dial_state_callback

typedef void(* ast_dial_state_callback) (struct ast_dial *)

Definition at line 39 of file dial.h.

Enumeration Type Documentation

ast_dial_option

enum ast_dial_option

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.

                     {
   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 */
};

ast_dial_result

enum ast_dial_result

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.

                     {
   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 */
};

Function Documentation

ast_dial_answered()

struct ast_channel* ast_dial_answered

(

struct ast_dial *

dial

)

Return channel that answered.

Note

Returns the Asterisk channel that answered

Parameters

dial	Dialing structure

Definition at line 981 of file dial.c.

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

Referenced by ari_originate_dial(), dial_trunk(), page_state_callback(), and sla_handle_dial_state_event().

{
   if (!dial)
      return NULL;

   return ((dial->state == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL);
}

ast_dial_answered_steal()

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

dial	Dialing structure

Definition at line 993 of file dial.c.

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

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

{
   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;
}

ast_dial_append()

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

References ast_calloc, dial_append_common(), and NULL.

Referenced by ari_channels_handle_originate_with_id(), dial_trunk(), do_notify(), page_exec(), pbx_outgoing_attempt(), recalling_enter(), 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;

   return dial_append_common(dial, channel, tech, device, assignedids);
}

ast_dial_append_channel()

int ast_dial_append_channel	(	struct ast_dial *	dial,
		struct ast_channel *	chan
	)

Append a channel using an actual channel object.

Parameters

dial	The ast_dial to add the channel to
chan	The channel to add to the dial

Return values

-1	Failure
non-zero	The position of the channel in the list of dialed channels

Note

The chan ref is stolen with a successful return.

Definition at line 297 of file dial.c.

References ast_calloc, ast_channel_name(), ast_free, ast_strdupa, ast_dial_channel::device, dial_append_common(), NULL, ast_dial_channel::owner, and ast_dial_channel::tech.

{
   struct ast_dial_channel *channel;
   char *tech;
   char *device;
   char *dash;

   if (!dial || !chan) {
      return -1;
   }

   channel = ast_calloc(1, sizeof(*channel));
   if (!channel) {
      return -1;
   }
   channel->owner = chan;

   tech = ast_strdupa(ast_channel_name(chan));

   device = strchr(tech, '/');
   if (!device) {
      ast_free(channel);
      return -1;
   }
   *device++ = '\0';

   dash = strrchr(device, '-');
   if (dash) {
      *dash = '\0';
   }

   return dial_append_common(dial, channel, tech, device, NULL);
}

ast_dial_create()

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 225 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, NULL, ast_dial::thread, and ast_dial::timeout.

Referenced by ari_channels_handle_originate_with_id(), dial_trunk(), do_notify(), page_exec(), pbx_outgoing_attempt(), recalling_enter(), 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;
}

ast_dial_destroy()

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

dial	Dialing structure to free

Returns

Returns 0 on success, -1 on failure

Note

Destroys (free's) the given ast_dial structure

Parameters

dial	Dialing structure to free

Returns

Returns 0 on success, -1 on failure

Definition at line 1091 of file dial.c.

References ast_dial_channel::assignedid1, ast_dial_channel::assignedid2, 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, NULL, ast_dial::options, ast_dial_channel::options, ast_dial_channel::owner, and ast_dial_channel::tech.

Referenced by ari_channels_handle_originate_with_id(), ari_originate_dial(), dial_trunk(), do_notify(), monitor_dial(), page_exec(), pbx_outgoing_destroy(), recalling_exit(), run_station(), sla_handle_dial_state_event(), 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 */
      ast_hangup(channel->owner);
      channel->owner = NULL;

      /* Free structure */
      ast_free(channel->tech);
      ast_free(channel->device);
      ast_free(channel->assignedid1);
      ast_free(channel->assignedid2);

      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;
}

ast_dial_get_channel()

struct ast_channel* ast_dial_get_channel	(	struct ast_dial *	dial,
		int	num
	)

Get the dialing channel, if prerun has been executed.

Parameters

dial	Dial structure
num	Channel number to get channel of

Returns

Pointer to channel, without reference

Definition at line 1282 of file dial.c.

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

Referenced by ari_channels_handle_originate_with_id(), pbx_outgoing_attempt(), pbx_outgoing_state_callback(), and recalling_enter().

{
   struct ast_dial_channel *channel;

   if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
      return NULL;
   }

   return channel->owner;
}

ast_dial_get_user_data()

void* ast_dial_get_user_data

(

struct ast_dial *

dial

)

Return the user data on a dial structure.

Parameters

dial	The dial structure

Returns

A pointer to the user data

Definition at line 1303 of file dial.c.

References ast_dial::user_data.

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

{
   return dial->user_data;
}

ast_dial_hangup()

void ast_dial_hangup

(

struct ast_dial *

dial

)

Hangup channels.

Note

Hangup all active channels

Parameters

dial	Dialing structure

Definition at line 1069 of file dial.c.

References ast_hangup(), AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_dial::channels, ast_dial_channel::list, NULL, 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) {
      ast_hangup(channel->owner);
      channel->owner = NULL;
   }
   AST_LIST_UNLOCK(&dial->channels);

   return;
}

ast_dial_join()

enum ast_dial_result ast_dial_join

(

struct ast_dial *

dial

)

Cancel async thread.

Note

Cancel a running async thread

Parameters

dial	Dialing structure

Definition at line 1021 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, NULL, ast_dial::state, and ast_dial::thread.

Referenced by dial_trunk(), page_exec(), recalling_exit(), run_station(), sla_handle_dial_state_event(), 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;
}

ast_dial_option_disable()

int ast_dial_option_disable	(	struct ast_dial *	dial,
		int	num,
		enum ast_dial_option	option
	)

Disables an option per channel.

Parameters

dial	Dial structure
num	Channel number to disable option on
option	Option to disable

Returns

Returns 0 on success, -1 on failure

Definition at line 1246 of file dial.c.

References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::disable, find_dial_channel(), NULL, 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;
}

ast_dial_option_enable()

int ast_dial_option_enable	(	struct ast_dial *	dial,
		int	num,
		enum ast_dial_option	option,
		void *	data
	)

Enables an option per channel.

Parameters

dial	Dial structure
num	Channel number to enable option on
option	Option to enable
data	Data to pass to this option (not always needed)

Returns

Returns 0 on success, -1 on failure

Definition at line 1194 of file dial.c.

References AST_LIST_EMPTY, ast_dial::channels, ast_option_types::enable, find_dial_channel(), NULL, 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;
}

ast_dial_option_global_disable()

int ast_dial_option_global_disable	(	struct ast_dial *	dial,
		enum ast_dial_option	option
	)

Disables an option globally.

Parameters

dial	Dial structure to disable option on
option	Option to disable

Returns

Returns 0 on success, -1 on failure

Definition at line 1223 of file dial.c.

References ast_option_types::disable, NULL, 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;
}

ast_dial_option_global_enable()

int ast_dial_option_global_enable	(	struct ast_dial *	dial,
		enum ast_dial_option	option,
		void *	data
	)

Enables an option globally.

Parameters

dial	Dial structure to enable option on
option	Option to enable
data	Data to pass to this option (not always needed)

Returns

Returns 0 on success, -1 on failure

Definition at line 1151 of file dial.c.

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

Referenced by do_notify(), page_exec(), and pbx_outgoing_attempt().

{
   /* 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;
}

ast_dial_prerun()

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

dial	Dialing structure
chan	Optional dialing channel
cap	Optional requested capabilities

Return values

-1	failure 0 success

Definition at line 433 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.

Referenced by ari_channels_handle_originate_with_id(), pbx_outgoing_attempt(), and recalling_enter().

{
   struct ast_dial_channel *channel;
   int res = -1;
   char *predial_string = dial->options[AST_DIAL_OPTION_PREDIAL];

   AST_LIST_LOCK(&dial->channels);
   AST_LIST_TRAVERSE(&dial->channels, channel, list) {
      if ((res = begin_dial_prerun(channel, chan, cap, predial_string))) {
         break;
      }
   }
   AST_LIST_UNLOCK(&dial->channels);

   return res;
}

ast_dial_reason()

int ast_dial_reason	(	struct ast_dial *	dial,
		int	num
	)

Get the reason an outgoing channel has failed.

Parameters

dial	Dial structure
num	Channel number to get the reason from

Returns

Numerical cause code

Definition at line 1271 of file dial.c.

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

Referenced by pbx_outgoing_attempt().

{
   struct ast_dial_channel *channel;

   if (!dial || AST_LIST_EMPTY(&dial->channels) || !(channel = find_dial_channel(dial, num))) {
      return -1;
   }

   return channel->cause;
}

ast_dial_run()

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 939 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, ast_read_threadstorage_callid(), async_dial(), begin_dial(), ast_dial::callid, ast_dial::channels, monitor_dial(), NULL, ast_dial::state, and ast_dial::thread.

Referenced by ari_originate_dial(), dial_trunk(), do_notify(), page_exec(), pbx_outgoing_exec(), recalling_enter(), and sla_ring_station().

{
   enum ast_dial_result res = AST_DIAL_RESULT_TRYING;

   /* Ensure required arguments are passed */
   if (!dial) {
      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, async))
      return AST_DIAL_RESULT_FAILED;

   /* If we are running async spawn a thread and send it away... otherwise block here */
   if (async) {
      /* reference be released at dial destruction if it isn't NULL */
      dial->callid = ast_read_threadstorage_callid();
      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;
}

ast_dial_set_global_timeout()

void ast_dial_set_global_timeout	(	struct ast_dial *	dial,
		int	timeout
	)

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

Parameters

dial	The dial structure to apply the time limit to
timeout	Maximum time allowed in milliseconds

Returns

nothing

Parameters

dial	The dial structure to apply the time limit to
timeout	Maximum time allowed

Returns

nothing

Definition at line 1313 of file dial.c.

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

Referenced by ari_channels_handle_originate_with_id(), do_notify(), page_exec(), and pbx_outgoing_attempt().

{
   dial->timeout = timeout;

   if (dial->timeout > 0 && (dial->actual_timeout > dial->timeout || dial->actual_timeout == -1))
      dial->actual_timeout = dial->timeout;

   return;
}

ast_dial_set_state_callback()

void ast_dial_set_state_callback	(	struct ast_dial *	dial,
		ast_dial_state_callback	callback
	)

Set a callback for state changes.

Parameters

dial	The dial structure to watch for state changes
callback	the callback

Returns

nothing

Definition at line 1293 of file dial.c.

References ast_dial::state_callback.

Referenced by page_exec(), pbx_outgoing_attempt(), recalling_enter(), and sla_ring_station().

{
   dial->state_callback = callback;
}

ast_dial_set_timeout()

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

dial	The dial structure the channel belongs to
num	Channel number to set timeout on
timeout	Maximum time allowed in milliseconds

Returns

nothing

Parameters

dial	The dial structure the channel belongs to
num	Channel number to set timeout on
timeout	Maximum time allowed

Returns

nothing

Definition at line 1329 of file dial.c.

References ast_dial::actual_timeout, find_dial_channel(), NULL, 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;
}

ast_dial_set_user_data()

void ast_dial_set_user_data	(	struct ast_dial *	dial,
		void *	user_data
	)

Set user data on a dial structure.

Parameters

dial	The dial structure to set a user data pointer on
user_data	The user data pointer

Returns

nothing

Definition at line 1298 of file dial.c.

References ast_dial::user_data.

Referenced by ari_channels_handle_originate_with_id(), page_exec(), and recalling_enter().

{
   dial->user_data = user_data;
}

ast_dial_state()

enum ast_dial_result ast_dial_state

(

struct ast_dial *

dial

)

Return state of dial.

Note

Returns the state of the dial attempt

Parameters

dial	Dialing structure

Definition at line 1012 of file dial.c.

References ast_dial::state.

Referenced by dial_trunk(), page_state_callback(), pbx_outgoing_state_callback(), recall_callback(), and sla_handle_dial_state_event().

{
   return dial->state;
}

ast_hangup_cause_to_dial_status()

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

References AST_CAUSE_BUSY, AST_CAUSE_CONGESTION, AST_CAUSE_NO_ANSWER, AST_CAUSE_NO_ROUTE_DESTINATION, and AST_CAUSE_UNREGISTERED.

Referenced by monitor_dial(), try_calling(), and wait_for_answer().

{
   switch(hangup_cause) {
   case AST_CAUSE_BUSY:
      return "BUSY";
   case AST_CAUSE_CONGESTION:
      return "CONGESTION";
   case AST_CAUSE_NO_ROUTE_DESTINATION:
   case AST_CAUSE_UNREGISTERED:
      return "CHANUNAVAIL";
   case AST_CAUSE_NO_ANSWER:
   default:
      return "NOANSWER";
   }
}