Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:48:19 2009

## Asterisk developer's documentation

# app_waitforring.c File Reference

Wait for Ring Application. More...

`#include <stdlib.h>`
`#include <stdio.h>`
`#include <string.h>`
`#include <unistd.h>`
`#include <sys/types.h>`
`#include "asterisk.h"`
`#include "asterisk/file.h"`
`#include "asterisk/logger.h"`
`#include "asterisk/channel.h"`
`#include "asterisk/pbx.h"`
`#include "asterisk/module.h"`
`#include "asterisk/options.h"`
`#include "asterisk/lock.h"`

Include dependency graph for app_waitforring.c:

Go to the source code of this file.

## Functions

char * | description (void)
| Provides a description of the module.
char * | key ()
| Returns the ASTERISK_GPL_KEY.
int | load_module (void)
| Initialize the module.
int | unload_module (void)
| Cleanup all module structures, sockets, etc.
int | usecount (void)
| Provides a usecount.
static int | waitforring_exec (struct ast_channel *chan, void *data)

## Variables

static char * | app = "WaitForRing"
static char * | desc
| LOCAL_USER_DECL
| STANDARD_LOCAL_USER
static char * | synopsis = "Wait for Ring Application"
static char * | tdesc = "Waits until first ring after time"

## Detailed Description

Wait for Ring Application.

Definition in file app_waitforring.c.

## Function Documentation

char* description | ( | void |  | ) |

Provides a description of the module.

Returns:
  a short description of your module

Definition at line 139 of file app_waitforring.c.

    00140 {
    00141    return tdesc;
    00142 }

char* key | ( | void |  | ) |

Returns the ASTERISK_GPL_KEY.

This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does not return the EXACT message:

     char *key(void) {
             return ASTERISK_GPL_KEY;
     }

Returns:
  ASTERISK_GPL_KEY

Definition at line 151 of file app_waitforring.c.

References ASTERISK_GPL_KEY.

    00152 {
    00153    return ASTERISK_GPL_KEY;
    00154 }

int load_module | ( | void |  | ) |

Initialize the module.

This function is called at module load time. Put all code in here that needs to set up your module's hardware, software, registrations, etc.

Returns:
  This function should return 0 on success and non-zero on failure. If the module is not loaded successfully, Asterisk will call its unload_module() function.

Initialize the Agents module. This function is being called by Asterisk when loading the module. Among other thing it registers applications, cli commands and reads the cofiguration file.

Returns:
  int Always 0.

TE STUFF END

Definition at line 134 of file app_waitforring.c.

References ast_register_application(), and waitforring_exec().

    00135 {
    00136    return ast_register_application(app, waitforring_exec, synopsis, desc);
    00137 }

int unload_module | ( | void |  | ) |

Cleanup all module structures, sockets, etc.

This is called at exit. Any registrations and memory allocations need to be unregistered and free'd here. Nothing else will do these for you (until exit).

Returns:
  Zero on success, or non-zero on error.

Definition at line 123 of file app_waitforring.c.

References ast_unregister_application(), and STANDARD_HANGUP_LOCALUSERS.

    00124 {
    00125    int res;
    00126
    00127    res = ast_unregister_application(app);
    00128
    00129    STANDARD_HANGUP_LOCALUSERS;
    00130
    00131    return res;
    00132 }

int usecount | ( | void |  | ) |

Provides a usecount.

This function will be called by various parts of asterisk. Basically, all it has to do is to return a usecount when called. You will need to maintain your usecount within the module somewhere. The usecount should be how many channels provided by this module are in use.

Returns:
  The module's usecount.

Definition at line 144 of file app_waitforring.c.

References STANDARD_USECOUNT.

    00145 {
    00146    int res;
    00147    STANDARD_USECOUNT(res);
    00148    return res;
    00149 }

static int waitforring_exec | ( | struct ast_channel * | chan,
|  | void * | data |
| ) |  |  | `[static]`

Definition at line 59 of file app_waitforring.c.

References AST_CONTROL_RING, AST_FRAME_CONTROL, ast_frfree(), ast_log(), ast_read(), ast_verbose(), ast_waitfor(), ast_frame::frametype, LOCAL_USER_ADD, LOCAL_USER_REMOVE, LOG_WARNING, option_verbose, ast_frame::subclass, and VERBOSE_PREFIX_3.

Referenced by load_module().

    00060 {
    00061    struct localuser *u;
    00062    struct ast_frame *f;
    00063    int res = 0;
    00064    int ms;
    00065
    00066    if (!data || (sscanf(data, "%30d", &ms) != 1)) {
    00067                 ast_log(LOG_WARNING, "WaitForRing requires an argument (minimum seconds)\n");
    00068       return 0;
    00069    }
    00070
    00071    LOCAL_USER_ADD(u);
    00072
    00073    ms *= 1000;
    00074    while(ms > 0) {
    00075       ms = ast_waitfor(chan, ms);
    00076       if (ms < 0) {
    00077          res = ms;
    00078          break;
    00079       }
    00080       if (ms > 0) {
    00081          f = ast_read(chan);
    00082          if (!f) {
    00083             res = -1;
    00084             break;
    00085          }
    00086          if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_RING)) {
    00087             if (option_verbose > 2)
    00088                ast_verbose(VERBOSE_PREFIX_3 "Got a ring but still waiting for timeout\n");
    00089          }
    00090          ast_frfree(f);
    00091       }
    00092    }
    00093    /* Now we're really ready for the ring */
    00094    if (!res) {
    00095       ms = 99999999;
    00096       while(ms > 0) {
    00097          ms = ast_waitfor(chan, ms);
    00098          if (ms < 0) {
    00099             res = ms;
    00100             break;
    00101          }
    00102          if (ms > 0) {
    00103             f = ast_read(chan);
    00104             if (!f) {
    00105                res = -1;
    00106                break;
    00107             }
    00108             if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_RING)) {
    00109                if (option_verbose > 2)
    00110                   ast_verbose(VERBOSE_PREFIX_3 "Got a ring after the timeout\n");
    00111                ast_frfree(f);
    00112                break;
    00113             }
    00114             ast_frfree(f);
    00115          }
    00116       }
    00117    }
    00118    LOCAL_USER_REMOVE(u);
    00119
    00120    return res;
    00121 }

## Variable Documentation

char* app = "WaitForRing"`[static]`

Definition at line 53 of file app_waitforring.c.

char* desc`[static]`

Initial value:

     "  WaitForRing(timeout)\n"
    "Returns 0 after waiting at least timeout seconds. and\n"
    "only after the next ring has completed.  Returns 0 on\n"
    "success or -1 on hangup\n"

Definition at line 48 of file app_waitforring.c.

LOCAL_USER_DECL

Definition at line 57 of file app_waitforring.c.

STANDARD_LOCAL_USER

Definition at line 55 of file app_waitforring.c.

char* synopsis = "Wait for Ring Application"`[static]`

Definition at line 44 of file app_waitforring.c.

char* tdesc = "Waits until first ring after time"`[static]`

Definition at line 46 of file app_waitforring.c.