Wed Aug 20 06:40:26 2008

Asterisk developer's documentation

---

features.h File Reference

Call Parking and Pickup API Includes code and algorithms from the Zapata library. More...

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

Go to the source code of this file.

Data Structures
struct	ast_call_feature
	main call feature structure More...
Defines
#define	FEATURE_APP_ARGS_LEN   256
#define	FEATURE_APP_LEN   64
#define	FEATURE_EXTEN_LEN   32
#define	FEATURE_MAX_LEN   11
#define	FEATURE_SNAME_LEN   32
Functions
int	ast_bridge_call (struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config)
	Bridge a call, optionally allowing redirection.
int	ast_masq_park_call (struct ast_channel *rchan, struct ast_channel *host, int timeout, int *extout)
	Park a call via a masqueraded channel.
int	ast_park_call (struct ast_channel *chan, struct ast_channel *host, int timeout, int *extout)
	Park a call and read back parked location.
char *	ast_parking_ext (void)
	Determine system parking extension Returns the call parking extension for drivers that provide special call parking help.
int	ast_pickup_call (struct ast_channel *chan)
	Pickup a call.
char *	ast_pickup_ext (void)
	Determine system call pickup extension.
void	ast_register_feature (struct ast_call_feature *feature)
	register new feature into feature_set
void	ast_unregister_feature (struct ast_call_feature *feature)
	unregister feature from feature_set

---

Detailed Description

Call Parking and Pickup API Includes code and algorithms from the Zapata library.

Definition in file features.h.

---

Define Documentation

#define FEATURE_APP_ARGS_LEN   256

Definition at line 29 of file features.h.

Referenced by load_config().

#define FEATURE_APP_LEN   64

Definition at line 28 of file features.h.

Referenced by load_config().

#define FEATURE_EXTEN_LEN   32

Definition at line 31 of file features.h.

Referenced by load_config().

#define FEATURE_MAX_LEN   11

Definition at line 27 of file features.h.

Referenced by ast_bridge_call().

#define FEATURE_SNAME_LEN   32

Definition at line 30 of file features.h.

Referenced by load_config().

---

Function Documentation

int ast_bridge_call	(	struct ast_channel *	chan,
		struct ast_channel *	peer,
		struct ast_bridge_config *	config
	)

Bridge a call, optionally allowing redirection.

Definition at line 1265 of file res_features.c.

References ast_channel::appl, ast_answer(), ast_cdr_appenduserfield(), ast_cdr_setuserfield(), ast_channel_bridge(), ast_dtmf_stream(), ast_frfree(), ast_log(), ast_strlen_zero(), ast_channel::cdr, config, ast_channel::data, FEATURE_MAX_LEN, free, LOG_DEBUG, monitor_app, monitor_ok, ast_channel::name, pbx_builtin_getvar_helper(), pbx_builtin_setvar_helper(), pbx_exec(), pbx_findapp(), set_config_flags(), and ast_cdr::userfield.

Referenced by ast_bridge_call_thread(), builtin_atxfer(), dial_exec_full(), park_exec(), and try_calling().

{
   /* Copy voice back and forth between the two channels.  Give the peer
      the ability to transfer calls with '#<extension' syntax. */
   struct ast_frame *f;
   struct ast_channel *who;
   char chan_featurecode[FEATURE_MAX_LEN + 1]="";
   char peer_featurecode[FEATURE_MAX_LEN + 1]="";
   int res;
   int diff;
   int hasfeatures=0;
   int hadfeatures=0;
   struct ast_option_header *aoh;
   struct ast_bridge_config backup_config;
   char *monitor_exec;

   memset(&backup_config, 0, sizeof(backup_config));

   config->start_time = ast_tvnow();

   if (chan && peer) {
      pbx_builtin_setvar_helper(chan, "BRIDGEPEER", peer->name);
      pbx_builtin_setvar_helper(peer, "BRIDGEPEER", chan->name);
   } else if (chan)
      pbx_builtin_setvar_helper(chan, "BLINDTRANSFER", NULL);

   if (monitor_ok) {
      if (!monitor_app) { 
         if (!(monitor_app = pbx_findapp("Monitor")))
            monitor_ok=0;
      }
      if (monitor_app) {
         if ((monitor_exec = pbx_builtin_getvar_helper(chan, "AUTO_MONITOR"))) 
            pbx_exec(chan, monitor_app, monitor_exec, 1);
         else if ((monitor_exec = pbx_builtin_getvar_helper(peer, "AUTO_MONITOR")))
            pbx_exec(peer, monitor_app, monitor_exec, 1);
      }
   }
   
   set_config_flags(chan, peer, config);
   config->firstpass = 1;

   /* Answer if need be */
   if (ast_answer(chan))
      return -1;
   peer->appl = "Bridged Call";
   peer->data = chan->name;

   /* copy the userfield from the B-leg to A-leg if applicable */
   if (chan->cdr && peer->cdr && !ast_strlen_zero(peer->cdr->userfield)) {
      char tmp[256];
      if (!ast_strlen_zero(chan->cdr->userfield)) {
         snprintf(tmp, sizeof(tmp), "%s;%s", chan->cdr->userfield, peer->cdr->userfield);
         ast_cdr_appenduserfield(chan, tmp);
      } else
         ast_cdr_setuserfield(chan, peer->cdr->userfield);
      /* free the peer's cdr without ast_cdr_free complaining */
      free(peer->cdr);
      peer->cdr = NULL;
   }
   for (;;) {
      res = ast_channel_bridge(chan, peer, config, &f, &who);

      if (config->feature_timer) {
         /* Update time limit for next pass */
         diff = ast_tvdiff_ms(ast_tvnow(), config->start_time);
         config->feature_timer -= diff;
         if (hasfeatures) {
            /* Running on backup config, meaning a feature might be being
               activated, but that's no excuse to keep things going 
               indefinitely! */
            if (backup_config.feature_timer && ((backup_config.feature_timer -= diff) <= 0)) {
               ast_log(LOG_DEBUG, "Timed out, realtime this time!\n");
               config->feature_timer = 0;
               who = chan;
               if (f)
                  ast_frfree(f);
               f = NULL;
               res = 0;
            } else if (config->feature_timer <= 0) {
               /* Not *really* out of time, just out of time for
                  digits to come in for features. */
               ast_log(LOG_DEBUG, "Timed out for feature!\n");
               if (!ast_strlen_zero(peer_featurecode)) {
                  ast_dtmf_stream(chan, peer, peer_featurecode, 0);
                  memset(peer_featurecode, 0, sizeof(peer_featurecode));
               }
               if (!ast_strlen_zero(chan_featurecode)) {
                  ast_dtmf_stream(peer, chan, chan_featurecode, 0);
                  memset(chan_featurecode, 0, sizeof(chan_featurecode));
               }
               if (f)
                  ast_frfree(f);
               hasfeatures = !ast_strlen_zero(chan_featurecode) || !ast_strlen_zero(peer_featurecode);
               if (!hasfeatures) {
                  /* Restore original (possibly time modified) bridge config */
                  memcpy(config, &backup_config, sizeof(struct ast_bridge_config));
                  memset(&backup_config, 0, sizeof(backup_config));
               }
               hadfeatures = hasfeatures;
               /* Continue as we were */
               continue;
            } else if (!f) {
               /* The bridge returned without a frame and there is a feature in progress.
                * However, we don't think the feature has quite yet timed out, so just
                * go back into the bridge. */
               continue;
            }
         } else {
            if (config->feature_timer <=0) {
               /* We ran out of time */
               config->feature_timer = 0;
               who = chan;
               if (f)
                  ast_frfree(f);
               f = NULL;
               res = 0;
            }
         }
      }
      if (res < 0) {
         ast_log(LOG_WARNING, "Bridge failed on channels %s and %s\n", chan->name, peer->name);
         return -1;
      }
      
      if (!f || ((f->frametype == AST_FRAME_CONTROL) && ((f->subclass == AST_CONTROL_HANGUP) || (f->subclass == AST_CONTROL_BUSY) || 
         (f->subclass == AST_CONTROL_CONGESTION)))) {
            res = -1;
            break;
      }
      if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_RINGING)) {
         if (who == chan)
            ast_indicate(peer, AST_CONTROL_RINGING);
         else
            ast_indicate(chan, AST_CONTROL_RINGING);
      }
      if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == -1)) {
         if (who == chan)
            ast_indicate(peer, -1);
         else
            ast_indicate(chan, -1);
      }
      if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_FLASH)) {
         if (who == chan)
            ast_indicate(peer, AST_CONTROL_FLASH);
         else
            ast_indicate(chan, AST_CONTROL_FLASH);
      }
      if ((f->frametype == AST_FRAME_CONTROL) && (f->subclass == AST_CONTROL_OPTION)) {
         aoh = f->data;
         /* Forward option Requests */
         if (aoh && (aoh->flag == AST_OPTION_FLAG_REQUEST)) {
            if (who == chan)
               ast_channel_setoption(peer, ntohs(aoh->option), aoh->data, f->datalen - sizeof(struct ast_option_header), 0);
            else
               ast_channel_setoption(chan, ntohs(aoh->option), aoh->data, f->datalen - sizeof(struct ast_option_header), 0);
         }
      }
      /* check for '*', if we find it it's time to disconnect */
      if (f && (f->frametype == AST_FRAME_DTMF)) {
         char *featurecode;
         int sense;
         struct ast_channel *other;

         hadfeatures = hasfeatures;
         /* This cannot overrun because the longest feature is one shorter than our buffer */
         if (who == chan) {
            other = peer;
            sense = FEATURE_SENSE_CHAN;
            featurecode = chan_featurecode;
         } else  {
            other = chan;
            sense = FEATURE_SENSE_PEER;
            featurecode = peer_featurecode;
         }
         featurecode[strlen(featurecode)] = f->subclass;
         /* Get rid of the frame before we start doing "stuff" with the channels */
         ast_frfree(f);
         f = NULL;
         config->feature_timer = backup_config.feature_timer;
         res = ast_feature_interpret(chan, peer, config, featurecode, sense);
         switch(res) {
         case FEATURE_RETURN_PASSDIGITS:
            ast_dtmf_stream(other, who, featurecode, 0);
            /* Fall through */
         case FEATURE_RETURN_SUCCESS:
            memset(featurecode, 0, sizeof(chan_featurecode));
            break;
         }
         if (res >= FEATURE_RETURN_PASSDIGITS) {
            res = 0;
         } else 
            break;
         hasfeatures = !ast_strlen_zero(chan_featurecode) || !ast_strlen_zero(peer_featurecode);
         if (hadfeatures && !hasfeatures) {
            /* Restore backup */
            memcpy(config, &backup_config, sizeof(struct ast_bridge_config));
            memset(&backup_config, 0, sizeof(struct ast_bridge_config));
         } else if (hasfeatures) {
            if (!hadfeatures) {
               /* Backup configuration */
               memcpy(&backup_config, config, sizeof(struct ast_bridge_config));
               /* Setup temporary config options */
               config->play_warning = 0;
               ast_clear_flag(&(config->features_caller), AST_FEATURE_PLAY_WARNING);
               ast_clear_flag(&(config->features_callee), AST_FEATURE_PLAY_WARNING);
               config->warning_freq = 0;
               config->warning_sound = NULL;
               config->end_sound = NULL;
               config->start_sound = NULL;
               config->firstpass = 0;
            }
            config->start_time = ast_tvnow();
            config->feature_timer = featuredigittimeout;
            ast_log(LOG_DEBUG, "Set time limit to %ld\n", config->feature_timer);
         }
      }
      if (f)
         ast_frfree(f);
   }
   return res;
}

int ast_masq_park_call	(	struct ast_channel *	rchan,
		struct ast_channel *	host,
		int	timeout,
		int *	extout
	)

Park a call via a masqueraded channel.

Parameters:

	rchan	the real channel to be parked
	host	the channel to have the parking read to Masquerade the channel rchan into a new, empty channel which is then parked with ast_park_call
	timeout	is a timeout in milliseconds
	extout	is a parameter to an int that will hold the parked location, or NULL if you want

Definition at line 401 of file res_features.c.

References ast_channel_alloc(), ast_channel_masquerade(), ast_frfree(), ast_log(), ast_park_call(), ast_read(), ast_channel::context, ast_channel::exten, LOG_WARNING, ast_channel::name, ast_channel::priority, ast_channel::readformat, and ast_channel::writeformat.

Referenced by mgcp_ss(), parkandannounce_exec(), rpt_exec(), skinny_ss(), and ss_thread().

{
   struct ast_channel *chan;
   struct ast_frame *f;

   /* Make a new, fake channel that we'll use to masquerade in the real one */
   chan = ast_channel_alloc(0);
   if (chan) {
      /* Let us keep track of the channel name */
      snprintf(chan->name, sizeof (chan->name), "Parked/%s",rchan->name);

      /* Make formats okay */
      chan->readformat = rchan->readformat;
      chan->writeformat = rchan->writeformat;
      ast_channel_masquerade(chan, rchan);

      /* Setup the extensions and such */
      ast_copy_string(chan->context, rchan->context, sizeof(chan->context));
      ast_copy_string(chan->exten, rchan->exten, sizeof(chan->exten));
      chan->priority = rchan->priority;

      /* Make the masq execute */
      f = ast_read(chan);
      if (f)
         ast_frfree(f);
      ast_park_call(chan, peer, timeout, extout);
   } else {
      ast_log(LOG_WARNING, "Unable to create parked channel\n");
      return -1;
   }
   return 0;
}

int ast_park_call	(	struct ast_channel *	chan,
		struct ast_channel *	host,
		int	timeout,
		int *	extout
	)

Park a call and read back parked location.

Parameters:

	chan	the channel to actually be parked
	host	the channel which will have the parked location read to Park the channel chan, and read back the parked location to the host. If the call is not picked up within a specified period of time, then the call will return to the last step that it was in (in terms of exten, priority and context)
	timeout	is a timeout in milliseconds
	extout	is a parameter to an int that will hold the parked location, or NULL if you want

Definition at line 278 of file res_features.c.

References adsi_announce_park(), adsi_available(), adsi_unload_session(), ast_channel::appl, ast_add_extension2(), ast_context_create(), ast_context_find(), AST_CONTROL_HOLD, ast_indicate(), ast_log(), AST_MAX_EXTENSION, ast_moh_start(), ast_mutex_lock(), ast_mutex_unlock(), ast_say_digits(), ast_strlen_zero(), ast_verbose(), parkeduser::chan, ast_channel::cid, ast_callerid::cid_name, ast_callerid::cid_num, parkeduser::context, ast_channel::context, ast_channel::data, EVENT_FLAG_CALL, exten, parkeduser::exten, ast_channel::exten, free, FREE, LOG_ERROR, LOG_WARNING, ast_channel::macrocontext, ast_channel::macroexten, ast_channel::macropriority, malloc, manager_event(), ast_channel::name, parkeduser::next, parkeduser::notquiteyet, option_verbose, parkinglot, parkeduser::parkingnum, parkeduser::parkingtime, parkeduser::peername, parkeduser::priority, ast_channel::priority, parkeduser::start, strdup, and VERBOSE_PREFIX_2.

Referenced by ast_masq_park_call(), builtin_blindtransfer(), iax_park_thread(), park_call_exec(), and sip_park_thread().

{
   struct parkeduser *pu, *cur;
   int i,x,parking_range;
   char exten[AST_MAX_EXTENSION];
   struct ast_context *con;

   pu = malloc(sizeof(struct parkeduser));
   if (!pu) {
      ast_log(LOG_WARNING, "Out of memory\n");
      return -1;
   }
   memset(pu, 0, sizeof(struct parkeduser));
   ast_mutex_lock(&parking_lock);
   parking_range = parking_stop - parking_start+1;
   for (i = 0; i < parking_range; i++) {
      x = (i + parking_offset) % parking_range + parking_start;
      cur = parkinglot;
      while(cur) {
         if (cur->parkingnum == x) 
            break;
         cur = cur->next;
      }
      if (!cur)
         break;
   }

   if (!(i < parking_range)) {
      ast_log(LOG_WARNING, "No more parking spaces\n");
      free(pu);
      ast_mutex_unlock(&parking_lock);
      return -1;
   }
   if (parkfindnext) 
      parking_offset = x - parking_start + 1;
   chan->appl = "Parked Call";
   chan->data = NULL; 

   pu->chan = chan;
   /* Start music on hold */
   if (chan != peer) {
      ast_indicate(pu->chan, AST_CONTROL_HOLD);
      ast_moh_start(pu->chan, NULL);
   }
   pu->start = ast_tvnow();
   pu->parkingnum = x;
   if (timeout > 0)
      pu->parkingtime = timeout;
   else
      pu->parkingtime = parkingtime;
   if (extout)
      *extout = x;
   if (peer) 
      ast_copy_string(pu->peername, peer->name, sizeof(pu->peername));

   /* Remember what had been dialed, so that if the parking
      expires, we try to come back to the same place */
   if (!ast_strlen_zero(chan->macrocontext))
      ast_copy_string(pu->context, chan->macrocontext, sizeof(pu->context));
   else
      ast_copy_string(pu->context, chan->context, sizeof(pu->context));
   if (!ast_strlen_zero(chan->macroexten))
      ast_copy_string(pu->exten, chan->macroexten, sizeof(pu->exten));
   else
      ast_copy_string(pu->exten, chan->exten, sizeof(pu->exten));
   if (chan->macropriority)
      pu->priority = chan->macropriority;
   else
      pu->priority = chan->priority;
   pu->next = parkinglot;
   parkinglot = pu;
   /* If parking a channel directly, don't quiet yet get parking running on it */
   if (peer == chan) 
      pu->notquiteyet = 1;
   ast_mutex_unlock(&parking_lock);
   /* Wake up the (presumably select()ing) thread */
   pthread_kill(parking_thread, SIGURG);
   if (option_verbose > 1) 
      ast_verbose(VERBOSE_PREFIX_2 "Parked %s on %d. Will timeout back to extension [%s] %s, %d in %d seconds\n", pu->chan->name, pu->parkingnum, pu->context, pu->exten, pu->priority, (pu->parkingtime/1000));

   manager_event(EVENT_FLAG_CALL, "ParkedCall",
      "Exten: %d\r\n"
      "Channel: %s\r\n"
      "From: %s\r\n"
      "Timeout: %ld\r\n"
      "CallerID: %s\r\n"
      "CallerIDName: %s\r\n"
      ,pu->parkingnum, pu->chan->name, peer ? peer->name : ""
      ,(long)pu->start.tv_sec + (long)(pu->parkingtime/1000) - (long)time(NULL)
      ,(pu->chan->cid.cid_num ? pu->chan->cid.cid_num : "<unknown>")
      ,(pu->chan->cid.cid_name ? pu->chan->cid.cid_name : "<unknown>")
      );

   if (peer) {
      if (adsipark && adsi_available(peer)) {
         adsi_announce_park(peer, pu->parkingnum);
      }
      if (adsipark && adsi_available(peer)) {
         adsi_unload_session(peer);
      }
   }
   con = ast_context_find(parking_con);
   if (!con) {
      con = ast_context_create(NULL, parking_con, registrar);
      if (!con) {
         ast_log(LOG_ERROR, "Parking context '%s' does not exist and unable to create\n", parking_con);
      }
   }
   if (peer) 
      ast_say_digits(peer, pu->parkingnum, "", peer->language);
   if (con) {
      snprintf(exten, sizeof(exten), "%d", x);
      ast_add_extension2(con, 1, exten, 1, NULL, NULL, parkedcall, strdup(exten), FREE, registrar);
   }
   if (pu->notquiteyet) {
      /* Wake up parking thread if we're really done */
      ast_moh_start(pu->chan, NULL);
      pu->notquiteyet = 0;
      pthread_kill(parking_thread, SIGURG);
   }
   return 0;
}

char* ast_parking_ext

(

void

)

Determine system parking extension Returns the call parking extension for drivers that provide special call parking help.

Definition at line 163 of file res_features.c.

Referenced by builtin_blindtransfer(), dp_lookup(), get_refer_info(), handle_request_refer(), load_config(), mgcp_ss(), skinny_ss(), socket_read(), and ss_thread().

{
   return parking_ext;
}

int ast_pickup_call

(

struct ast_channel *

chan

)

Pickup a call.

Definition at line 1928 of file res_features.c.

References ast_channel::_state, ast_answer(), ast_channel_masquerade(), ast_channel_walk_locked(), AST_CONTROL_ANSWER, ast_log(), ast_mutex_unlock(), ast_queue_control(), AST_STATE_RING, AST_STATE_RINGING, ast_channel::callgroup, ast_channel::lock, LOG_DEBUG, LOG_WARNING, ast_channel::name, option_debug, ast_channel::pbx, and ast_channel::pickupgroup.

Referenced by cb_events(), handle_request_invite(), mgcp_ss(), monitor_handle_notowned(), skinny_ss(), and ss_thread().

{
   struct ast_channel *cur = NULL;
   int res = -1;

   while ( (cur = ast_channel_walk_locked(cur)) != NULL) {
      if (!cur->pbx && 
         (cur != chan) &&
         (chan->pickupgroup & cur->callgroup) &&
         ((cur->_state == AST_STATE_RINGING) ||
          (cur->_state == AST_STATE_RING))) {
            break;
      }
      ast_mutex_unlock(&cur->lock);
   }
   if (cur) {
      if (option_debug)
         ast_log(LOG_DEBUG, "Call pickup on chan '%s' by '%s'\n",cur->name, chan->name);
      res = ast_answer(chan);
      if (res)
         ast_log(LOG_WARNING, "Unable to answer '%s'\n", chan->name);
      res = ast_queue_control(chan, AST_CONTROL_ANSWER);
      if (res)
         ast_log(LOG_WARNING, "Unable to queue answer on '%s'\n", chan->name);
      res = ast_channel_masquerade(cur, chan);
      if (res)
         ast_log(LOG_WARNING, "Unable to masquerade '%s' into '%s'\n", chan->name, cur->name);     /* Done */
      ast_mutex_unlock(&cur->lock);
   } else   {
      if (option_debug)
         ast_log(LOG_DEBUG, "No call pickup possible...\n");
   }
   return res;
}

char* ast_pickup_ext

(

void

)

Determine system call pickup extension.

Definition at line 168 of file res_features.c.

Referenced by cb_events(), get_destination(), handle_request_invite(), handle_showfeatures(), mgcp_ss(), monitor_handle_notowned(), skinny_ss(), and ss_thread().

{
   return pickup_ext;
}

void ast_register_feature

(

struct ast_call_feature *

feature

)

register new feature into feature_set

Parameters:

feature

an ast_call_feature object which contains a keysequence and a callback function which is called when this keysequence is pressed during a call.

Definition at line 876 of file res_features.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_log(), ast_verbose(), LOG_NOTICE, option_verbose, ast_call_feature::sname, and VERBOSE_PREFIX_2.

Referenced by load_config().

{
   if (!feature) {
      ast_log(LOG_NOTICE,"You didn't pass a feature!\n");
         return;
   }
  
   AST_LIST_LOCK(&feature_list);
   AST_LIST_INSERT_HEAD(&feature_list,feature,feature_entry);
   AST_LIST_UNLOCK(&feature_list);

   if (option_verbose >= 2) 
      ast_verbose(VERBOSE_PREFIX_2 "Registered Feature '%s'\n",feature->sname);
}

void ast_unregister_feature

(

struct ast_call_feature *

feature

)

unregister feature from feature_set

Parameters:

feature

the ast_call_feature object which was registered before

Definition at line 892 of file res_features.c.

References AST_LIST_LOCK, AST_LIST_REMOVE, AST_LIST_UNLOCK, and free.

{
   if (!feature) return;

   AST_LIST_LOCK(&feature_list);
   AST_LIST_REMOVE(&feature_list,feature,feature_entry);
   AST_LIST_UNLOCK(&feature_list);
   free(feature);
}

---