Codename Pineapple

Home page | Mailing list | Docs

Last updated: Sat Feb 3 05:01:30 2007

Asterisk developer's documentation :: Codename Pineapple

include » asterisk

dial.h File Reference

Detailed Description

Dialing API.

Definition in file dial.h.

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

Go to the source code of this file.

Enumerations

enum  ast_dial_option { AST_DIAL_OPTION_RINGING, AST_DIAL_OPTION_ANSWER_EXEC, 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 = 0, 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

ast_channel * ast_dial_answered (struct ast_dial *dial)
 Return channel that answered.
int ast_dial_append (struct ast_dial *dial, const char *tech, const char *device)
 Append a channel.
ast_dial * ast_dial_create (void)
 New dialing structure.
int ast_dial_destroy (struct ast_dial *dial)
 Destroys a dialing structure.
void ast_dial_hangup (struct ast_dial *dial)
 Hangup channels.
enum ast_dial_result ast_dial_join (struct ast_dial *dial)
 Cancel async thread.
int ast_dial_option_disable (struct ast_dial *dial, int num, enum ast_dial_option option)
 Disables an option per channel.
int ast_dial_option_enable (struct ast_dial *dial, int num, enum ast_dial_option option, void *data)
 Enables an option per channel.
int ast_dial_option_global_disable (struct ast_dial *dial, enum ast_dial_option option)
 Disables an option globally.
int ast_dial_option_global_enable (struct ast_dial *dial, enum ast_dial_option option, void *data)
 Enables an option globally.
enum ast_dial_result ast_dial_run (struct ast_dial *dial, struct ast_channel *chan, int async)
 Execute dialing synchronously or asynchronously.
enum ast_dial_result ast_dial_status (struct ast_dial *dial)
 Return status of dial.

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_MAX  End terminator -- must always remain last

Definition at line 37 of file dial.h.

00037                      {
00038    AST_DIAL_OPTION_RINGING,     /*!< Always indicate ringing to caller */
00039    AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */
00040    AST_DIAL_OPTION_MAX,         /*!< End terminator -- must always remain last */
00041 };

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

00044                      {
00045    AST_DIAL_RESULT_INVALID = 0, /*!< Invalid options were passed to run function */
00046    AST_DIAL_RESULT_FAILED,      /*!< Attempts to dial failed before reaching critical state */
00047    AST_DIAL_RESULT_TRYING,      /*!< Currently trying to dial */
00048    AST_DIAL_RESULT_RINGING,     /*!< Dial is presently ringing */
00049    AST_DIAL_RESULT_PROGRESS,    /*!< Dial is presently progressing */
00050    AST_DIAL_RESULT_PROCEEDING,  /*!< Dial is presently proceeding */
00051    AST_DIAL_RESULT_ANSWERED,    /*!< A channel was answered */
00052    AST_DIAL_RESULT_TIMEOUT,     /*!< Timeout was tripped, nobody answered */
00053    AST_DIAL_RESULT_HANGUP,      /*!< Caller hung up */
00054    AST_DIAL_RESULT_UNANSWERED,  /*!< Nobody answered */
00055 };

Function Documentation

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

References AST_DIAL_RESULT_ANSWERED, AST_LIST_FIRST, and ast_dial::status.

00564 {
00565    if (!dial)
00566       return NULL;
00567 
00568    return ((dial->status == AST_DIAL_RESULT_ANSWERED) ? AST_LIST_FIRST(&dial->channels)->owner : NULL);
00569 }

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

References ast_calloc, AST_LIST_INSERT_TAIL, and ast_dial::num.

00193 {
00194    struct ast_dial_channel *channel = NULL;
00195 
00196    /* Make sure we have required arguments */
00197    if (!dial || !tech || !device)
00198       return -1;
00199 
00200    /* Allocate new memory for dialed channel structure */
00201    if (!(channel = ast_calloc(1, sizeof(*channel))))
00202       return -1;
00203 
00204    /* Record technology and device for when we actually dial */
00205    channel->tech = tech;
00206    channel->device = device;
00207 
00208    /* Grab reference number from dial structure */
00209    channel->num = ast_atomic_fetchadd_int(&dial->num, +1);
00210 
00211    /* Insert into channels list */
00212    AST_LIST_INSERT_TAIL(&dial->channels, channel, list);
00213 
00214    return channel->num;
00215 }

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

References ast_calloc, AST_LIST_HEAD_INIT_NOLOCK, and AST_PTHREADT_NULL.

00172 {
00173    struct ast_dial *dial = NULL;
00174 
00175    /* Allocate new memory for structure */
00176    if (!(dial = ast_calloc(1, sizeof(*dial))))
00177       return NULL;
00178 
00179    /* Initialize list of channels */
00180    AST_LIST_HEAD_INIT_NOLOCK(&dial->channels);
00181 
00182    /* Initialize thread to NULL */
00183    dial->thread = AST_PTHREADT_NULL;
00184 
00185    return dial;
00186 }

int ast_dial_destroy (  struct ast_dial *  dial  ) 
 

Destroys a dialing structure.

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

References AST_DIAL_OPTION_MAX, ast_hangup(), AST_LIST_TRAVERSE, option_types, ast_dial_channel::options, and ast_dial_channel::owner.

00637 {
00638    int i = 0;
00639    struct ast_dial_channel *channel = NULL;
00640 
00641    if (!dial)
00642       return -1;
00643    
00644    /* Hangup and deallocate all the dialed channels */
00645    AST_LIST_TRAVERSE(&dial->channels, channel, list) {
00646       /* Disable any enabled options */
00647       for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
00648          if (!channel->options[i])
00649             continue;
00650          if (option_types[i].disable)
00651             option_types[i].disable(channel->options[i]);
00652          channel->options[i] = NULL;
00653       }
00654       /* Hang up channel if need be */
00655       if (channel->owner) {
00656          ast_hangup(channel->owner);
00657          channel->owner = NULL;
00658       }
00659       /* Free structure */
00660       free(channel);
00661    }
00662        
00663    /* Disable any enabled options globally */
00664    for (i = 0; i < AST_DIAL_OPTION_MAX; i++) {
00665       if (!dial->options[i])
00666          continue;
00667       if (option_types[i].disable)
00668          option_types[i].disable(dial->options[i]);
00669       dial->options[i] = NULL;
00670    }
00671 
00672    /* Free structure */
00673    free(dial);
00674 
00675    return 0;
00676 }

void ast_dial_hangup (  struct ast_dial *  dial  ) 
 

Hangup channels.

Note:
Hangup all active channels
Parameters:
dial Dialing structure

Definition at line 614 of file dial.c.

References ast_hangup(), AST_LIST_TRAVERSE, and ast_dial_channel::owner.

Referenced by ast_dial_run().

00615 {
00616    struct ast_dial_channel *channel = NULL;
00617 
00618    if (!dial)
00619       return;
00620    
00621    AST_LIST_TRAVERSE(&dial->channels, channel, list) {
00622       if (channel->owner) {
00623          ast_hangup(channel->owner);
00624          channel->owner = NULL;
00625       }
00626    }
00627 
00628    return;
00629 }

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

References AST_DIAL_RESULT_FAILED, AST_PTHREADT_NULL, AST_PTHREADT_STOP, and ast_dial::status.

00585 {
00586    pthread_t thread;
00587 
00588    /* If the dial structure is not running in async, return failed */
00589    if (dial->thread == AST_PTHREADT_NULL)
00590       return AST_DIAL_RESULT_FAILED;
00591 
00592    /* Record thread */
00593    thread = dial->thread;
00594 
00595    /* Stop the thread */
00596    dial->thread = AST_PTHREADT_STOP;
00597 
00598    /* Now we signal it with SIGURG so it will break out of it's waitfor */
00599    pthread_kill(thread, SIGURG);
00600 
00601    /* Finally wait for the thread to exit */
00602    pthread_join(thread, NULL);
00603 
00604    /* Yay thread is all gone */
00605    dial->thread = AST_PTHREADT_NULL;
00606 
00607    return dial->status;
00608 }

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

References AST_LIST_EMPTY, AST_LIST_LAST, AST_LIST_TRAVERSE, ast_option_types::disable, ast_dial_channel::num, option_types, and ast_dial_channel::options.

00769 {
00770    struct ast_dial_channel *channel = NULL;
00771 
00772    /* Ensure we have required arguments */
00773    if (!dial || AST_LIST_EMPTY(&dial->channels))
00774       return -1;
00775 
00776    /* Look for channel, we can sort of cheat and predict things - the last channel in the list will probably be what they want */
00777    if (AST_LIST_LAST(&dial->channels)->num != num) {
00778       AST_LIST_TRAVERSE(&dial->channels, channel, list) {
00779          if (channel->num == num)
00780             break;
00781       }
00782    } else {
00783       channel = AST_LIST_LAST(&dial->channels);
00784    }
00785 
00786    /* If none found, return failure */
00787    if (!channel)
00788       return -1;
00789 
00790    /* If the option is not enabled, return failure */
00791    if (!channel->options[option])
00792       return -1;
00793 
00794    /* Execute callback of option to disable it if it exists */
00795    if (option_types[option].disable)
00796       option_types[option].disable(channel->options[option]);
00797 
00798    /* Finally disable the option on the structure */
00799    channel->options[option] = NULL;
00800 
00801    return 0;
00802 }

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

References AST_LIST_EMPTY, AST_LIST_LAST, AST_LIST_TRAVERSE, ast_option_types::enable, ast_dial_channel::num, option_types, and ast_dial_channel::options.

00707 {
00708    struct ast_dial_channel *channel = NULL;
00709 
00710    /* Ensure we have required arguments */
00711    if (!dial || AST_LIST_EMPTY(&dial->channels))
00712       return -1;
00713    
00714    /* Look for channel, we can sort of cheat and predict things - the last channel in the list will probably be what they want */
00715    if (AST_LIST_LAST(&dial->channels)->num != num) {
00716       AST_LIST_TRAVERSE(&dial->channels, channel, list) {
00717          if (channel->num == num)
00718             break;
00719       }
00720    } else {
00721       channel = AST_LIST_LAST(&dial->channels);
00722    }
00723 
00724    /* If none found, return failure */
00725    if (!channel)
00726       return -1;
00727 
00728    /* If the option is already enabled, return failure */
00729    if (channel->options[option])
00730       return -1;
00731 
00732         /* Execute enable callback if it exists, if not simply make sure the value is set */
00733    if (option_types[option].enable)
00734       channel->options[option] = option_types[option].enable(data);
00735    else
00736       channel->options[option] = (void*)1;
00737 
00738    return 0;
00739 }

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

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

00747 {
00748         /* If the option is not enabled, return failure */
00749         if (!dial->options[option])
00750                 return -1;
00751 
00752    /* Execute callback of option to disable if it exists */
00753    if (option_types[option].disable)
00754       option_types[option].disable(dial->options[option]);
00755 
00756    /* Finally disable option on the structure */
00757    dial->options[option] = NULL;
00758 
00759         return 0;
00760 }

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

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

00685 {
00686    /* If the option is already enabled, return failure */
00687    if (dial->options[option])
00688       return -1;
00689 
00690    /* Execute enable callback if it exists, if not simply make sure the value is set */
00691    if (option_types[option].enable)
00692       dial->options[option] = option_types[option].enable(data);
00693    else
00694       dial->options[option] = (void*)1;
00695 
00696    return 0;
00697 }

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

References 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(), and monitor_dial().

00529 {
00530    enum ast_dial_result res = AST_DIAL_RESULT_TRYING;
00531 
00532    /* Ensure required arguments are passed */
00533    if (!dial || !chan)
00534       return AST_DIAL_RESULT_INVALID;
00535 
00536    /* If there are no channels to dial we can't very well try to dial them */
00537    if (AST_LIST_EMPTY(&dial->channels))
00538       return AST_DIAL_RESULT_INVALID;
00539 
00540    /* Dial each requested channel */
00541    if (!begin_dial(dial, chan))
00542       return AST_DIAL_RESULT_FAILED;
00543 
00544    /* If we are running async spawn a thread and send it away... otherwise block here */
00545    if (async) {
00546       /* Try to create a thread */
00547       if (ast_pthread_create(&dial->thread, NULL, async_dial, dial)) {
00548          /* Failed to create the thread - hangup all dialed channels and return failed */
00549          ast_dial_hangup(dial);
00550          res = AST_DIAL_RESULT_FAILED;
00551       }
00552    } else {
00553       res = monitor_dial(dial, chan);
00554    }
00555 
00556    return res;
00557 }

enum ast_dial_result ast_dial_status (  struct ast_dial *  dial  ) 
 

Return status of dial.

Note:
Returns the status of the dial attempt
Parameters:
dial Dialing structure

Definition at line 575 of file dial.c.

References ast_dial::status.

00576 {
00577    return dial->status;
00578 }

Asterisk is a trademark for Digium, inc.. | Edvina.net | Asterisk.org | This documentation was generated with Doxygen