Sun Sep 7 06:29:42 2008

Asterisk developer's documentation

---

Module: Dial plan applications

Applications support the dialplan. They register dynamically with ast_register_application() and unregister with ast_unregister_application(). More...

Files
file	app_adsiprog.c
	Program Asterisk ADSI Scripts into phone.
file	app_alarmreceiver.c
	Central Station Alarm receiver for Ademco Contact ID.
file	app_authenticate.c
	Execute arbitrary authenticate commands.
file	app_cdr.c
	Applications connected with CDR engine.
file	app_chanisavail.c
	Check if Channel is Available.
file	app_channelredirect.c
	ChannelRedirect application.
file	app_chanspy.c
	ChanSpy: Listen in on any channel.
file	app_controlplayback.c
	Trivial application to control playback of a sound file.
file	app_dahdibarge.c
	Zap Barge support.
file	app_dahdiras.c
	Execute an ISDN RAS.
file	app_dahdiscan.c
	Zap Scanner.
file	app_db.c
	Database access functions.
file	app_dial.c
	dial() & retrydial() - Trivial application to dial a channel and send an URL on answer
file	app_dictate.c
	Virtual Dictation Machine Application For Asterisk.
file	app_directed_pickup.c
	Directed Call Pickup Support.
file	app_directory.c
	Provide a directory of extensions.
file	app_disa.c
	DISA -- Direct Inward System Access Application.
file	app_dumpchan.c
	Application to dump channel variables.
file	app_echo.c
	Echo application -- play back what you hear to evaluate latency.
file	app_exec.c
	Exec application.
file	app_externalivr.c
	External IVR application interface.
file	app_festival.c
	Connect to festival.
file	app_flash.c
	App to flash a DAHDI trunk.
file	app_followme.c
	Find-Me Follow-Me application.
file	app_forkcdr.c
	Fork CDR application.
file	app_getcpeid.c
	Get ADSI CPE ID.
file	app_hasnewvoicemail.c
	HasVoicemail application.
file	app_ices.c
	Stream to an icecast server via ICES (see contrib/asterisk-ices.xml).
file	app_image.c
	App to transmit an image.
file	app_ivrdemo.c
	IVR Demo application.
file	app_lookupblacklist.c
	App to lookup the callerid number, and see if it is blacklisted.
file	app_lookupcidname.c
	App to set callerid name from database, based on directory number.
file	app_macro.c
	Dial plan macro Implementation.
file	app_meetme.c
	Meet me conference bridge and Shared Line Appearances.
file	app_milliwatt.c
	Digital Milliwatt Test.
file	app_mixmonitor.c
	MixMonitor() - Record a call and mix the audio during the recording.
file	app_morsecode.c
	Morsecode application.
file	app_mp3.c
	Silly application to play an MP3 file -- uses mpg123.
file	app_nbscat.c
	Silly application to play an NBScat file -- uses nbscat8k.
file	app_osplookup.c
	Open Settlement Protocol (OSP) Applications.
file	app_page.c
	page() - Paging application
file	app_parkandannounce.c
	ParkAndAnnounce application for Asterisk.
file	app_playback.c
	Trivial application to playback a sound file.
file	app_privacy.c
	Block all calls without Caller*ID, require phone # to be entered.
file	app_queue.c
	True call queues with optional send URL on answer.
file	app_random.c
	Random application.
file	app_read.c
	Trivial application to read a variable.
file	app_readfile.c
	ReadFile application -- Reads in a File for you.
file	app_realtime.c
	RealTime App.
file	app_record.c
	Trivial application to record a sound file.
file	app_sayunixtime.c
	SayUnixTime application.
file	app_senddtmf.c
	App to send DTMF digits.
file	app_sendtext.c
	App to transmit a text message.
file	app_setcallerid.c
	App to set callerid.
file	app_setcdruserfield.c
	Applictions connected with CDR engine.
file	app_settransfercapability.c
	App to set the ISDN Transfer Capability.
file	app_skel.c
	Skeleton application.
file	app_sms.c
	SMS application - ETSI ES 201 912 protocol 1 implimentation.
file	app_softhangup.c
	SoftHangup application.
file	app_speech_utils.c
	Speech Recognition Utility Applications.
file	app_stack.c
	Stack applications Gosub, Return, etc.
file	app_system.c
	Execute arbitrary system commands.
file	app_talkdetect.c
	Playback a file with audio detect.
file	app_test.c
	Applications to test connection and produce report in text file.
file	app_transfer.c
	Transfer a caller.
file	app_url.c
	App to transmit a URL.
file	app_userevent.c
	UserEvent application -- send manager event.
file	app_verbose.c
	Verbose logging application.
file	app_voicemail.c
	Comedian Mail - Voicemail System.
file	app_waitforring.c
	Wait for Ring Application.
file	app_waitforsilence.c
	Wait for Silence Waits for up to 'x' milliseconds of silence, 'y' times WaitForSilence(500,2) will wait for 1/2 second of silence, twice WaitForSilence(1000,1) will wait for 1 second of silence, once WaitForSilence(300,3,10) will wait for 300ms of silence, 3 times, and return after 10sec .
file	app_while.c
	While Loop Implementation.
file	app_zapateller.c
	Playback the special information tone to get rid of telemarketers.
Functions
static int	iax2_prov_app (struct ast_channel *chan, void *data)
static int	pbx_builtin_answer (struct ast_channel *, void *)
static int	pbx_builtin_background (struct ast_channel *, void *)
static int	pbx_builtin_busy (struct ast_channel *, void *)
static int	pbx_builtin_congestion (struct ast_channel *, void *)
static int	pbx_builtin_execiftime (struct ast_channel *, void *)
static int	pbx_builtin_goto (struct ast_channel *, void *)
static int	pbx_builtin_gotoiftime (struct ast_channel *, void *)
static int	pbx_builtin_hangup (struct ast_channel *, void *)
static int	pbx_builtin_progress (struct ast_channel *, void *)
static int	pbx_builtin_resetcdr (struct ast_channel *, void *)
static int	pbx_builtin_ringing (struct ast_channel *, void *)
static int	pbx_builtin_setamaflags (struct ast_channel *, void *)
static int	pbx_builtin_wait (struct ast_channel *, void *)
static int	pbx_builtin_waitexten (struct ast_channel *, void *)

---

Detailed Description

Applications support the dialplan. They register dynamically with ast_register_application() and unregister with ast_unregister_application().

Asterisk Dial Plan Applications

See also

• Module: Dial plan functions

---

Function Documentation

static int iax2_prov_app	(	struct ast_channel *	chan,
		void *	data
	)			[static]

iax2provision

Definition at line 8829 of file chan_iax2.c.

References ast_inet_ntoa(), ast_log(), ast_strdupa, ast_strlen_zero(), ast_verbose(), iax2_provision(), iax2_tech, iaxs, LOG_NOTICE, option_verbose, PTR_TO_CALLNO, create_addr_info::sockfd, ast_channel::tech, ast_channel::tech_pvt, and VERBOSE_PREFIX_3.

Referenced by load_module().

{
   int res;
   char *sdata;
   char *opts;
   int force =0;
   unsigned short callno = PTR_TO_CALLNO(chan->tech_pvt);
   if (ast_strlen_zero(data))
      data = "default";
   sdata = ast_strdupa(data);
   opts = strchr(sdata, '|');
   if (opts)
      *opts='\0';

   if (chan->tech != &iax2_tech) {
      ast_log(LOG_NOTICE, "Can't provision a non-IAX device!\n");
      return -1;
   } 
   if (!callno || !iaxs[callno] || !iaxs[callno]->addr.sin_addr.s_addr) {
      ast_log(LOG_NOTICE, "Can't provision something with no IP?\n");
      return -1;
   }
   res = iax2_provision(&iaxs[callno]->addr, iaxs[callno]->sockfd, NULL, sdata, force);
   if (option_verbose > 2)
      ast_verbose(VERBOSE_PREFIX_3 "Provisioned IAXY at '%s' with '%s'= %d\n", 
      ast_inet_ntoa(iaxs[callno]->addr.sin_addr),
      sdata, res);
   return res;
}

static int pbx_builtin_answer	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5411 of file pbx.c.

References ast_channel::_state, ast_answer(), ast_safe_sleep(), AST_STATE_UP, and ast_strlen_zero().

{
   int delay = 0;
   int res;

   if (chan->_state == AST_STATE_UP)
      delay = 0;
   else if (!ast_strlen_zero(data))
      delay = atoi(data);

   res = ast_answer(chan);
   if (res)
      return res;

   if (delay)
      res = ast_safe_sleep(chan, delay);

   return res;
}

static int pbx_builtin_background	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5644 of file pbx.c.

References ast_channel::_state, ast_answer(), AST_APP_ARG, ast_app_parse_options(), AST_DECLARE_APP_ARGS, AST_DIGIT_ANY, ast_log(), AST_STANDARD_APP_ARGS, AST_STATE_UP, ast_stopstream(), ast_strdupa, ast_streamfile(), ast_strlen_zero(), ast_test_flag, ast_waitstream(), ast_waitstream_exten(), BACKGROUND_MATCHEXTEN, BACKGROUND_NOANSWER, BACKGROUND_PLAYBACK, BACKGROUND_SKIP, ast_channel::context, ast_channel::exten, ast_flags::flags, LOG_WARNING, parse(), ast_channel::priority, and strsep().

{
   int res = 0;
   struct ast_flags flags = {0};
   char *parse;
   AST_DECLARE_APP_ARGS(args,
      AST_APP_ARG(filename);
      AST_APP_ARG(options);
      AST_APP_ARG(lang);
      AST_APP_ARG(context);
   );

   if (ast_strlen_zero(data)) {
      ast_log(LOG_WARNING, "Background requires an argument (filename)\n");
      return -1;
   }

   parse = ast_strdupa(data);

   AST_STANDARD_APP_ARGS(args, parse);

   if (ast_strlen_zero(args.lang))
      args.lang = (char *)chan->language; /* XXX this is const */

   if (ast_strlen_zero(args.context))
      args.context = chan->context;

   if (args.options) {
      if (!strcasecmp(args.options, "skip"))
         flags.flags = BACKGROUND_SKIP;
      else if (!strcasecmp(args.options, "noanswer"))
         flags.flags = BACKGROUND_NOANSWER;
      else
         ast_app_parse_options(background_opts, &flags, NULL, args.options);
   }

   /* Answer if need be */
   if (chan->_state != AST_STATE_UP) {
      if (ast_test_flag(&flags, BACKGROUND_SKIP)) {
         return 0;
      } else if (!ast_test_flag(&flags, BACKGROUND_NOANSWER)) {
         res = ast_answer(chan);
      }
   }

   if (!res) {
      char *back = args.filename;
      char *front;
      ast_stopstream(chan);      /* Stop anything playing */
      /* Stream the list of files */
      while (!res && (front = strsep(&back, "&")) ) {
         if ( (res = ast_streamfile(chan, front, args.lang)) ) {
            ast_log(LOG_WARNING, "ast_streamfile failed on %s for %s\n", chan->name, (char*)data);
            res = 0;
            break;
         }
         if (ast_test_flag(&flags, BACKGROUND_PLAYBACK)) {
            res = ast_waitstream(chan, "");
         } else if (ast_test_flag(&flags, BACKGROUND_MATCHEXTEN)) {
            res = ast_waitstream_exten(chan, args.context);
         } else {
            res = ast_waitstream(chan, AST_DIGIT_ANY);
         }
         ast_stopstream(chan);
      }
   }
   if (args.context != chan->context && res) {
      snprintf(chan->exten, sizeof(chan->exten), "%c", res);
      ast_copy_string(chan->context, args.context, sizeof(chan->context));
      chan->priority = 0;
      res = 0;
   }
   return res;
}

static int pbx_builtin_busy	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5383 of file pbx.c.

References ast_channel::_state, AST_CONTROL_BUSY, ast_indicate(), ast_setstate(), AST_STATE_BUSY, AST_STATE_UP, and wait_for_hangup().

{
   ast_indicate(chan, AST_CONTROL_BUSY);
   /* Don't change state of an UP channel, just indicate
      busy in audio */
   if (chan->_state != AST_STATE_UP)
      ast_setstate(chan, AST_STATE_BUSY);
   wait_for_hangup(chan, data);
   return -1;
}

static int pbx_builtin_congestion	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5397 of file pbx.c.

References ast_channel::_state, AST_CONTROL_CONGESTION, ast_indicate(), ast_setstate(), AST_STATE_BUSY, AST_STATE_UP, and wait_for_hangup().

{
   ast_indicate(chan, AST_CONTROL_CONGESTION);
   /* Don't change state of an UP channel, just indicate
      congestion in audio */
   if (chan->_state != AST_STATE_UP)
      ast_setstate(chan, AST_STATE_BUSY);
   wait_for_hangup(chan, data);
   return -1;
}

static int pbx_builtin_execiftime	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5524 of file pbx.c.

References app, ast_build_timing(), ast_check_timing(), ast_log(), ast_strdupa, ast_strlen_zero(), LOG_WARNING, pbx_exec(), pbx_findapp(), s, S_OR, and strsep().

{
   char *s, *appname;
   struct ast_timing timing;
   struct ast_app *app;
   static const char *usage = "ExecIfTime requires an argument:\n  <time range>|<days of week>|<days of month>|<months>?<appname>[|<appargs>]";

   if (ast_strlen_zero(data)) {
      ast_log(LOG_WARNING, "%s\n", usage);
      return -1;
   }

   appname = ast_strdupa(data);

   s = strsep(&appname,"?");  /* Separate the timerange and application name/data */
   if (!appname) {   /* missing application */
      ast_log(LOG_WARNING, "%s\n", usage);
      return -1;
   }

   if (!ast_build_timing(&timing, s)) {
      ast_log(LOG_WARNING, "Invalid Time Spec: %s\nCorrect usage: %s\n", s, usage);
      return -1;
   }

   if (!ast_check_timing(&timing))  /* outside the valid time window, just return */
      return 0;

   /* now split appname|appargs */
   if ((s = strchr(appname, '|')))
      *s++ = '\0';

   if ((app = pbx_findapp(appname))) {
      return pbx_exec(chan, app, S_OR(s, ""));
   } else {
      ast_log(LOG_WARNING, "Cannot locate application %s\n", appname);
      return -1;
   }
}

static int pbx_builtin_goto	(	struct ast_channel *	chan,
		void *	data
	)			[static]

Goto

Definition at line 5722 of file pbx.c.

References ast_parseable_goto(), ast_verbose(), ast_channel::context, ast_channel::exten, option_verbose, ast_channel::priority, and VERBOSE_PREFIX_3.

Referenced by pbx_builtin_gotoif(), and pbx_builtin_gotoiftime().

{
   int res = ast_parseable_goto(chan, data);
   if (!res && (option_verbose > 2))
      ast_verbose( VERBOSE_PREFIX_3 "Goto (%s,%s,%d)\n", chan->context,chan->exten, chan->priority+1);
   return res;
}

static int pbx_builtin_gotoiftime	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5498 of file pbx.c.

References ast_build_timing(), ast_check_timing(), ast_log(), ast_strdupa, ast_strlen_zero(), LOG_WARNING, pbx_builtin_goto(), s, and strsep().

{
   int res=0;
   char *s, *ts;
   struct ast_timing timing;

   if (ast_strlen_zero(data)) {
      ast_log(LOG_WARNING, "GotoIfTime requires an argument:\n  <time range>|<days of week>|<days of month>|<months>?[[context|]extension|]priority\n");
      return -1;
   }

   ts = s = ast_strdupa(data);

   /* Separate the Goto path */
   strsep(&ts,"?");

   /* struct ast_include include contained garbage here, fixed by zeroing it on get_timerange */
   if (ast_build_timing(&timing, s) && ast_check_timing(&timing))
      res = pbx_builtin_goto(chan, ts);
   
   return res;
}

static int pbx_builtin_hangup	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5468 of file pbx.c.

References AST_CAUSE_NORMAL_CLEARING, ast_log(), ast_str2cause(), ast_strlen_zero(), ast_channel::hangupcause, and LOG_NOTICE.

{
   if (!ast_strlen_zero(data)) {
      int cause;
      char *endptr;

      if ((cause = ast_str2cause(data)) > -1) {
         chan->hangupcause = cause;
         return -1;
      }
      
      cause = strtol((const char *) data, &endptr, 10);
      if (cause != 0 || (data != endptr)) {
         chan->hangupcause = cause;
         return -1;
      }
         
      ast_log(LOG_NOTICE, "Invalid cause given to Hangup(): \"%s\"\n", (char *) data);
   }

   if (!chan->hangupcause) {
      chan->hangupcause = AST_CAUSE_NORMAL_CLEARING;
   }

   return -1;
}

static int pbx_builtin_progress	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5365 of file pbx.c.

References AST_CONTROL_PROGRESS, and ast_indicate().

{
   ast_indicate(chan, AST_CONTROL_PROGRESS);
   return 0;
}

static int pbx_builtin_resetcdr	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5440 of file pbx.c.

References ast_app_parse_options(), ast_cdr_reset(), ast_strdupa, ast_strlen_zero(), ast_channel::cdr, and ast_flags::flags.

{
   char *args;
   struct ast_flags flags = { 0 };

   if (!ast_strlen_zero(data)) {
      args = ast_strdupa(data);
      ast_app_parse_options(resetcdr_opts, &flags, NULL, args);
   }

   ast_cdr_reset(chan->cdr, &flags);

   return 0;
}

static int pbx_builtin_ringing	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5374 of file pbx.c.

References AST_CONTROL_RINGING, and ast_indicate().

{
   ast_indicate(chan, AST_CONTROL_RINGING);
   return 0;
}

static int pbx_builtin_setamaflags	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5458 of file pbx.c.

References ast_cdr_setamaflags().

{
   /* Copy the AMA Flags as specified */
   ast_cdr_setamaflags(chan, data ? data : "");
   return 0;
}

static int pbx_builtin_wait	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5567 of file pbx.c.

References ast_safe_sleep(), and s.

{
   double s;
   int ms;

   /* Wait for "n" seconds */
   if (data && (s = atof(data)) > 0) {
      ms = s * 1000.0;
      return ast_safe_sleep(chan, ms);
   }
   return 0;
}

static int pbx_builtin_waitexten	(	struct ast_channel *	,
		void *
	)			[static]

Definition at line 5583 of file pbx.c.

References AST_APP_ARG, ast_app_parse_options(), AST_CONTROL_HOLD, AST_CONTROL_UNHOLD, AST_DECLARE_APP_ARGS, ast_exists_extension(), ast_indicate(), ast_indicate_data(), ast_log(), AST_SOFTHANGUP_TIMEOUT, AST_STANDARD_APP_ARGS, ast_strdupa, ast_strlen_zero(), ast_test_flag, ast_verbose(), ast_waitfordigit(), ast_flags::flags, LOG_WARNING, option_verbose, parse(), set_ext_pri(), VERBOSE_PREFIX_3, and WAITEXTEN_MOH.

{
   int ms, res;
   double sec;
   struct ast_flags flags = {0};
   char *opts[1] = { NULL };
   char *parse;
   AST_DECLARE_APP_ARGS(args,
      AST_APP_ARG(timeout);
      AST_APP_ARG(options);
   );

   if (!ast_strlen_zero(data)) {
      parse = ast_strdupa(data);
      AST_STANDARD_APP_ARGS(args, parse);
   } else
      memset(&args, 0, sizeof(args));

   if (args.options)
      ast_app_parse_options(waitexten_opts, &flags, opts, args.options);
   
   if (ast_test_flag(&flags, WAITEXTEN_MOH) && !opts[0] ) {
      ast_log(LOG_WARNING, "The 'm' option has been specified for WaitExten without a class.\n"); 
   } else if (ast_test_flag(&flags, WAITEXTEN_MOH))
      ast_indicate_data(chan, AST_CONTROL_HOLD, opts[0], strlen(opts[0]));

   /* Wait for "n" seconds */
   if (args.timeout && (sec = atof(args.timeout)) > 0.0)
      ms = 1000 * sec;
   else if (chan->pbx)
      ms = chan->pbx->rtimeout * 1000;
   else
      ms = 10000;
   res = ast_waitfordigit(chan, ms);
   if (!res) {
      if (ast_exists_extension(chan, chan->context, chan->exten, chan->priority + 1, chan->cid.cid_num)) {
         if (option_verbose > 2)
            ast_verbose(VERBOSE_PREFIX_3 "Timeout on %s, continuing...\n", chan->name);
      } else if (chan->_softhangup == AST_SOFTHANGUP_TIMEOUT) {
         if (option_verbose > 2)
            ast_verbose(VERBOSE_PREFIX_3 "Call timeout on %s, checking for 'T'\n", chan->name);
         res = -1;
      } else if (ast_exists_extension(chan, chan->context, "t", 1, chan->cid.cid_num)) {
         if (option_verbose > 2)
            ast_verbose(VERBOSE_PREFIX_3 "Timeout on %s, going to 't'\n", chan->name);
         set_ext_pri(chan, "t", 0); /* 0 will become 1, next time through the loop */
      } else {
         ast_log(LOG_WARNING, "Timeout but no rule 't' in context '%s'\n", chan->context);
         res = -1;
      }
   }

   if (ast_test_flag(&flags, WAITEXTEN_MOH))
      ast_indicate(chan, AST_CONTROL_UNHOLD);

   return res;
}

---