Sat Apr 26 2014 22:02:46

Asterisk developer's documentation

Typedefs | Enumerations | Functions
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_MAX
}
 List of options that are applicable either globally or per dialed channel. More...
enum  ast_dial_result {
  AST_DIAL_RESULT_INVALID, AST_DIAL_RESULT_FAILED, AST_DIAL_RESULT_TRYING, AST_DIAL_RESULT_RINGING,
  AST_DIAL_RESULT_PROGRESS, AST_DIAL_RESULT_PROCEEDING, AST_DIAL_RESULT_ANSWERED, AST_DIAL_RESULT_TIMEOUT,
  AST_DIAL_RESULT_HANGUP, AST_DIAL_RESULT_UNANSWERED
}
 List of return codes for dial run API calls. More...

Functions

struct ast_channel * ast_dial_answered (struct ast_dial *dial)
 Return channel that answered.
struct ast_channel * ast_dial_answered_steal (struct ast_dial *dial)
 Steal the channel that answered.
int ast_dial_append (struct ast_dial *dial, const char *tech, const char *device)
 Append a channel.
struct ast_dial * ast_dial_create (void)
 New dialing structure.
int ast_dial_destroy (struct ast_dial *dial)
 Destroys a dialing structure.
void * ast_dial_get_user_data (struct ast_dial *dial)
 Return the user data on a dial structure.
void ast_dial_hangup (struct ast_dial *dial)
 Hangup channels.
enum ast_dial_result ast_dial_join (struct ast_dial *dial)
 Cancel async thread.
int ast_dial_option_disable (struct ast_dial *dial, int num, enum ast_dial_option option)
 Disables an option per channel.
int ast_dial_option_enable (struct ast_dial *dial, int num, enum ast_dial_option option, void *data)
 Enables an option per channel.
int ast_dial_option_global_disable (struct ast_dial *dial, enum ast_dial_option option)
 Disables an option globally.
int ast_dial_option_global_enable (struct ast_dial *dial, enum ast_dial_option option, void *data)
 Enables an option globally.
enum ast_dial_result ast_dial_run (struct ast_dial *dial, struct ast_channel *chan, int async)
 Execute dialing synchronously or asynchronously.
void ast_dial_set_global_timeout (struct ast_dial *dial, int timeout)
 Set the maximum time (globally) allowed for trying to ring phones.
void ast_dial_set_state_callback (struct ast_dial *dial, ast_dial_state_callback callback)
 Set a callback for state changes.
void ast_dial_set_timeout (struct ast_dial *dial, int num, int timeout)
 Set the maximum time (per channel) allowed for trying to ring the phone.
void ast_dial_set_user_data (struct ast_dial *dial, void *user_data)
 Set user data on a dial structure.
enum ast_dial_result ast_dial_state (struct ast_dial *dial)
 Return state of dial.

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

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_MAX 

End terminator -- must always remain last

Definition at line 39 of file dial.h.

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

List of return codes for dial run API calls.

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.

                     {
   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

struct ast_channel* ast_dial_answered ( struct ast_dial *  dial) [read]

Return channel that answered.

Note:
Returns the Asterisk channel that answered
Parameters:
dialDialing structure

Definition at line 779 of file dial.c.

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

Referenced by 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);
}
struct ast_channel* ast_dial_answered_steal ( struct ast_dial *  dial) [read]

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

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

Referenced by do_notify().

{
   struct ast_channel *chan = NULL;

   if (!dial)
      return NULL;

   if (dial->state == AST_DIAL_RESULT_ANSWERED) {
      chan = AST_LIST_FIRST(&dial->channels)->owner;
      AST_LIST_FIRST(&dial->channels)->owner = NULL;
   }

   return chan;
}
int ast_dial_append ( struct ast_dial *  dial,
const char *  tech,
const char *  device 
)

Append a channel.

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

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

{
   struct ast_dial_channel *channel = NULL;

   /* Make sure we have required arguments */
   if (!dial || !tech || !device)
      return -1;

   /* Allocate new memory for dialed channel structure */
   if (!(channel = ast_calloc(1, sizeof(*channel))))
      return -1;

   /* Record technology and device for when we actually dial */
   channel->tech = ast_strdup(tech);
   channel->device = ast_strdup(device);

   /* Grab reference number from dial structure */
   channel->num = ast_atomic_fetchadd_int(&dial->num, +1);

   /* No timeout exists... yet */
   channel->timeout = -1;

   /* Insert into channels list */
   AST_LIST_INSERT_TAIL(&dial->channels, channel, list);

   return channel->num;
}
struct ast_dial* ast_dial_create ( void  ) [read]

New dialing structure.

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

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

{
   struct ast_dial *dial = NULL;

   /* Allocate new memory for structure */
   if (!(dial = ast_calloc(1, sizeof(*dial))))
      return NULL;

   /* Initialize list of channels */
   AST_LIST_HEAD_INIT(&dial->channels);

   /* Initialize thread to NULL */
   dial->thread = AST_PTHREADT_NULL;

   /* No timeout exists... yet */
   dial->timeout = -1;
   dial->actual_timeout = -1;

   /* Can't forget about the lock */
   ast_mutex_init(&dial->lock);

   return dial;
}
int ast_dial_destroy ( struct ast_dial *  dial)

Destroys a dialing structure.

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

References ast_callid_unref, 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::callid, 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().

{
   int i = 0;
   struct ast_dial_channel *channel = NULL;

   if (!dial)
      return -1;

   /* Hangup and deallocate all the dialed channels */
   AST_LIST_LOCK(&dial->channels);
   AST_LIST_TRAVERSE_SAFE_BEGIN(&dial->channels, channel, list) {
      /* Disable any enabled options */
      for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
         if (!channel->options[i])
            continue;
         if (option_types[i].disable)
            option_types[i].disable(channel->options[i]);
         channel->options[i] = NULL;
      }
      /* Hang up channel if need be */
      if (channel->owner) {
         ast_hangup(channel->owner);
         channel->owner = NULL;
      }
      /* Free structure */
      ast_free(channel->tech);
      ast_free(channel->device);
      AST_LIST_REMOVE_CURRENT(list);
      ast_free(channel);
   }
   AST_LIST_TRAVERSE_SAFE_END;
   AST_LIST_UNLOCK(&dial->channels);

   /* Disable any enabled options globally */
   for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
      if (!dial->options[i])
         continue;
      if (option_types[i].disable)
         option_types[i].disable(dial->options[i]);
      dial->options[i] = NULL;
   }

   /* Lock be gone! */
   ast_mutex_destroy(&dial->lock);

   /* Get rid of the reference to the ast_callid */
   if (dial->callid) {
      ast_callid_unref(dial->callid);
   }

   /* Free structure */
   ast_free(dial);

   return 0;
}
void* ast_dial_get_user_data ( struct ast_dial *  dial)

Return the user data on a dial structure.

Parameters:
dialThe dial structure
Returns:
A pointer to the user data

Definition at line 1083 of file dial.c.

References ast_dial::user_data.

Referenced by page_state_callback().

{
   return dial->user_data;
}
void ast_dial_hangup ( struct ast_dial *  dial)

Hangup channels.

Note:
Hangup all active channels
Parameters:
dialDialing structure

Definition at line 867 of file dial.c.

References ast_hangup(), AST_LIST_LOCK, AST_LIST_TRAVERSE, AST_LIST_UNLOCK, ast_dial::channels, ast_dial_channel::list, and ast_dial_channel::owner.

Referenced by ast_dial_run(), and page_exec().

{
   struct ast_dial_channel *channel = NULL;

   if (!dial)
      return;

   AST_LIST_LOCK(&dial->channels);
   AST_LIST_TRAVERSE(&dial->channels, channel, list) {
      if (channel->owner) {
         ast_hangup(channel->owner);
         channel->owner = NULL;
      }
   }
   AST_LIST_UNLOCK(&dial->channels);

   return;
}
enum ast_dial_result ast_dial_join ( struct ast_dial *  dial)

Cancel async thread.

Note:
Cancel a running async thread
Parameters:
dialDialing structure

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

{
   pthread_t thread;

   /* If the dial structure is not running in async, return failed */
   if (dial->thread == AST_PTHREADT_NULL)
      return AST_DIAL_RESULT_FAILED;

   /* Record thread */
   thread = dial->thread;

   /* Boom, commence locking */
   ast_mutex_lock(&dial->lock);

   /* Stop the thread */
   dial->thread = AST_PTHREADT_STOP;

   /* If the answered channel is running an application we have to soft hangup it, can't just poke the thread */
   AST_LIST_LOCK(&dial->channels);
   if (AST_LIST_FIRST(&dial->channels)->is_running_app) {
      struct ast_channel *chan = AST_LIST_FIRST(&dial->channels)->owner;
      if (chan) {
         ast_channel_lock(chan);
         ast_softhangup(chan, AST_SOFTHANGUP_EXPLICIT);
         ast_channel_unlock(chan);
      }
   } else {
      /* Now we signal it with SIGURG so it will break out of it's waitfor */
      pthread_kill(thread, SIGURG);
   }
   AST_LIST_UNLOCK(&dial->channels);

   /* Yay done with it */
   ast_mutex_unlock(&dial->lock);

   /* Finally wait for the thread to exit */
   pthread_join(thread, NULL);

   /* Yay thread is all gone */
   dial->thread = AST_PTHREADT_NULL;

   return dial->state;
}
int ast_dial_option_disable ( struct ast_dial *  dial,
int  num,
enum ast_dial_option  option 
)

Disables an option per channel.

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

Definition at line 1048 of file dial.c.

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

{
   struct ast_dial_channel *channel = NULL;

   /* Ensure we have required arguments */
   if (!dial || AST_LIST_EMPTY(&dial->channels))
      return -1;

   if (!(channel = find_dial_channel(dial, num)))
      return -1;

   /* If the option is not enabled, return failure */
   if (!channel->options[option])
      return -1;

   /* Execute callback of option to disable it if it exists */
   if (option_types[option].disable)
      option_types[option].disable(channel->options[option]);

   /* Finally disable the option on the structure */
   channel->options[option] = NULL;

   return 0;
}
int ast_dial_option_enable ( struct ast_dial *  dial,
int  num,
enum ast_dial_option  option,
void *  data 
)

Enables an option per channel.

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

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

{
   struct ast_dial_channel *channel = NULL;

   /* Ensure we have required arguments */
   if (!dial || AST_LIST_EMPTY(&dial->channels))
      return -1;

   if (!(channel = find_dial_channel(dial, num)))
      return -1;

   /* If the option is already enabled, return failure */
   if (channel->options[option])
      return -1;

   /* Execute enable callback if it exists, if not simply make sure the value is set */
   if (option_types[option].enable)
      channel->options[option] = option_types[option].enable(data);
   else
      channel->options[option] = (void*)1;

   return 0;
}
int ast_dial_option_global_disable ( struct ast_dial *  dial,
enum ast_dial_option  option 
)

Disables an option globally.

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

Definition at line 1025 of file dial.c.

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

{
   /* If the option is not enabled, return failure */
   if (!dial->options[option]) {
      return -1;
   }

   /* Execute callback of option to disable if it exists */
   if (option_types[option].disable)
      option_types[option].disable(dial->options[option]);

   /* Finally disable option on the structure */
   dial->options[option] = NULL;

   return 0;
}
int ast_dial_option_global_enable ( struct ast_dial *  dial,
enum ast_dial_option  option,
void *  data 
)

Enables an option globally.

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

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

Referenced by do_notify(), and page_exec().

{
   /* If the option is already enabled, return failure */
   if (dial->options[option])
      return -1;

   /* Execute enable callback if it exists, if not simply make sure the value is set */
   if (option_types[option].enable)
      dial->options[option] = option_types[option].enable(data);
   else
      dial->options[option] = (void*)1;

   return 0;
}
enum ast_dial_result ast_dial_run ( struct ast_dial *  dial,
struct ast_channel *  chan,
int  async 
)

Execute dialing synchronously or asynchronously.

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

Definition at line 737 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(), ast_dial::state, and ast_dial::thread.

Referenced by dial_trunk(), do_notify(), page_exec(), and sla_ring_station().

{
   enum ast_dial_result res = AST_DIAL_RESULT_TRYING;

   /* Ensure required arguments are passed */
   if (!dial || (!chan && !async)) {
      ast_debug(1, "invalid #1\n");
      return AST_DIAL_RESULT_INVALID;
   }

   /* If there are no channels to dial we can't very well try to dial them */
   if (AST_LIST_EMPTY(&dial->channels)) {
      ast_debug(1, "invalid #2\n");
      return AST_DIAL_RESULT_INVALID;
   }

   /* Dial each requested channel */
   if (!begin_dial(dial, chan))
      return AST_DIAL_RESULT_FAILED;

   /* If we are running async spawn a thread and send it away... otherwise block here */
   if (async) {
      /* 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;
}
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 1093 of file dial.c.

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

Referenced by do_notify(), and page_exec().

{
   dial->timeout = timeout;

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

   return;
}
void ast_dial_set_state_callback ( struct ast_dial *  dial,
ast_dial_state_callback  callback 
)

Set a callback for state changes.

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

Definition at line 1073 of file dial.c.

References ast_dial::state_callback.

Referenced by page_exec(), and sla_ring_station().

{
   dial->state_callback = callback;
}
void ast_dial_set_timeout ( struct ast_dial *  dial,
int  num,
int  timeout 
)

Set the maximum time (per channel) allowed for trying to ring the phone.

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

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

{
   struct ast_dial_channel *channel = NULL;

   if (!(channel = find_dial_channel(dial, num)))
      return;

   channel->timeout = timeout;

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

   return;
}
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
Returns:
nothing

Definition at line 1078 of file dial.c.

References ast_dial::user_data.

Referenced by page_exec().

{
   dial->user_data = user_data;
}
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 810 of file dial.c.

References ast_dial::state.

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

{
   return dial->state;
}