Home page | Mailing list | Docs

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

Asterisk developer's documentation :: Codename Pineapple

---

features.h File Reference

---

Detailed Description

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

Definition in file features.h.

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_MOH_LEN   80
#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

---

Define Documentation

#define FEATURE_APP_ARGS_LEN   256

Definition at line 29 of file features.h.

#define FEATURE_APP_LEN   64

Definition at line 28 of file features.h.

#define FEATURE_EXTEN_LEN   32

Definition at line 31 of file features.h.

#define FEATURE_MAX_LEN   11

Definition at line 27 of file features.h. Referenced by ast_bridge_call().

#define FEATURE_MOH_LEN   80

Definition at line 32 of file features.h.

#define FEATURE_SNAME_LEN   32

Definition at line 30 of file features.h.

---

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. append the event to featurecode. we rely on the string being zero-filled, and not overflowing it. Todo: XXX how do we guarantee the latter ? Definition at line 1289 of file res_features.c. References ast_channel::appl, ast_answer(), ast_cdr_appenduserfield(), ast_cdr_setuserfield(), ast_channel_bridge(), ast_channel_setoption(), ast_clear_flag, AST_CONTROL_BUSY, AST_CONTROL_CONGESTION, AST_CONTROL_FLASH, AST_CONTROL_HANGUP, AST_CONTROL_OPTION, AST_CONTROL_RINGING, ast_dtmf_stream(), ast_feature_interpret(), AST_FEATURE_PLAY_WARNING, AST_FRAME_CONTROL, AST_FRAME_DTMF, AST_FRAME_DTMF_BEGIN, ast_frfree(), ast_indicate(), ast_log(), AST_OPTION_FLAG_REQUEST, ast_strdupa, ast_strlen_zero(), ast_channel::cdr, config, ast_channel::data, ast_frame::data, ast_option_header::data, ast_frame::datalen, FEATURE_MAX_LEN, FEATURE_RETURN_PASSDIGITS, FEATURE_RETURN_SUCCESS, FEATURE_SENSE_CHAN, FEATURE_SENSE_PEER, ast_option_header::flag, ast_frame::frametype, free, LOG_DEBUG, LOG_WARNING, monitor_app, ast_option_header::option, option_debug, pbx_builtin_getvar_helper(), pbx_builtin_setvar_helper(), pbx_exec(), pbx_findapp(), set_config_flags(), ast_frame::subclass, and ast_cdr::userfield. Referenced by ast_bridge_call_thread(), builtin_atxfer(), and park_exec(). { /* 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; 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) { const char *monitor_exec; struct ast_channel *src = NULL; if (!monitor_app) { if (!(monitor_app = pbx_findapp("Monitor"))) monitor_ok=0; } if ((monitor_exec = pbx_builtin_getvar_helper(chan, "AUTO_MONITOR"))) src = chan; else if ((monitor_exec = pbx_builtin_getvar_helper(peer, "AUTO_MONITOR"))) src = peer; if (monitor_app && src) { char *tmp = ast_strdupa(monitor_exec); pbx_exec(src, monitor_app, tmp); } } 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 (;;) { struct ast_channel *other; /* used later */ 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)) { if (option_debug) 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. */ if (option_debug) 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; } /* many things should be sent to the 'other' channel */ other = (who == chan) ? peer : chan; if (f->frametype == AST_FRAME_CONTROL) { if (f->subclass == AST_CONTROL_RINGING) ast_indicate(other, AST_CONTROL_RINGING); else if (f->subclass == -1) ast_indicate(other, -1); else if (f->subclass == AST_CONTROL_FLASH) ast_indicate(other, AST_CONTROL_FLASH); else if (f->subclass == AST_CONTROL_OPTION) { aoh = f->data; /* Forward option Requests */ if (aoh && aoh->flag == AST_OPTION_FLAG_REQUEST) ast_channel_setoption(other, ntohs(aoh->option), aoh->data, f->datalen - sizeof(struct ast_option_header), 0); } } else if (f->frametype == AST_FRAME_DTMF_BEGIN) { /* eat it */ } else if (f->frametype == AST_FRAME_DTMF) { char *featurecode; int sense; hadfeatures = hasfeatures; /* This cannot overrun because the longest feature is one shorter than our buffer */ if (who == chan) { sense = FEATURE_SENSE_CHAN; featurecode = chan_featurecode; } else { sense = FEATURE_SENSE_PEER; featurecode = peer_featurecode; } /*! append the event to featurecode. we rely on the string being zero-filled, and * not overflowing it. * \todo XXX how do we guarantee the latter ? */ 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; if (option_debug) 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 439 of file res_features.c. References ast_channel_alloc(), ast_channel_masquerade(), ast_frfree(), ast_log(), ast_park_call(), ast_read(), AST_STATE_DOWN, ast_channel::context, ast_channel::exten, LOG_WARNING, ast_channel::priority, ast_channel::readformat, set_c_e_p(), and ast_channel::writeformat. Referenced by manager_park(), mgcp_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 */ if (!(chan = ast_channel_alloc(0, AST_STATE_DOWN, 0, 0, "Parked/%s",rchan->name))) { ast_log(LOG_WARNING, "Unable to create parked channel\n"); return -1; } /* Make formats okay */ chan->readformat = rchan->readformat; chan->writeformat = rchan->writeformat; ast_channel_masquerade(chan, rchan); /* Setup the extensions and such */ set_c_e_p(chan, rchan->context, rchan->exten, rchan->priority); /* Make the masq execute */ f = ast_read(chan); if (f) ast_frfree(f); ast_park_call(chan, peer, timeout, extout); return 0; }

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

Park a call and read back parked location. Note: We put the user in the parking list, then wake up the parking thread to be sure it looks after these channels too Definition at line 311 of file res_features.c. References ast_calloc, ast_exists_extension(), ast_log(), ast_mutex_lock(), ast_strlen_zero(), LOG_WARNING, parkeduser::next, parkinglot, parkeduser::parkingnum, and pbx_builtin_getvar_helper(). Referenced by ast_masq_park_call(), builtin_blindtransfer(), builtin_parkcall(), iax_park_thread(), park_call_exec(), and sip_park_thread(). { struct parkeduser *pu, *cur; int i, x = -1, parking_range; struct ast_context *con; const char *parkingexten; /* Allocate memory for parking data */ if (!(pu = ast_calloc(1, sizeof(*pu)))) return -1; /* Lock parking lot */ ast_mutex_lock(&parking_lock); /* Check for channel variable PARKINGEXTEN */ parkingexten = pbx_builtin_getvar_helper(chan, "PARKINGEXTEN"); if (!ast_strlen_zero(parkingexten)) { if (ast_exists_extension(NULL, parking_con, parkingexten, 1, NULL)) { ast_log(LOG_WARNING, "Requested parking extension already exists: %s@%s\n", parkingexten, parking_con); return 0; /* Continue execution if possible */ } ast_copy_string(pu->parkingexten, parkingexten, sizeof(pu->parkingexten)); } else { /* Select parking space within range */ 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; } /* Set pointer for next parking */ if (parkfindnext) parking_offset = x - parking_start + 1; } chan->appl = "Parked Call"; chan->data = NULL; pu->chan = chan; /* Put the parked channel on hold if we have two different channels */ if (chan != peer) { ast_indicate_data(pu->chan, AST_CONTROL_HOLD, S_OR(parkmohclass, NULL), !ast_strlen_zero(parkmohclass) ? strlen(parkmohclass) + 1 : 0); } pu->start = ast_tvnow(); pu->parkingnum = x; pu->parkingtime = (timeout > 0) ? timeout : 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 */ ast_copy_string(pu->context, S_OR(chan->macrocontext, chan->context), sizeof(pu->context)); ast_copy_string(pu->exten, S_OR(chan->macroexten, chan->exten), sizeof(pu->exten)); pu->priority = chan->macropriority ? chan->macropriority : 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@%s. Will timeout back to extension [%s] %s, %d in %d seconds\n", pu->chan->name, pu->parkingnum, parking_con, pu->context, pu->exten, pu->priority, (pu->parkingtime/1000)); if (pu->parkingnum != -1) snprintf(pu->parkingexten, sizeof(pu->parkingexten), "%d", x); manager_event(EVENT_FLAG_CALL, "ParkedCall", "Exten: %s\r\n" "Channel: %s\r\n" "From: %s\r\n" "Timeout: %ld\r\n" "CallerIDNum: %s\r\n" "CallerIDName: %s\r\n", pu->parkingexten, pu->chan->name, peer ? peer->name : "", (long)pu->start.tv_sec + (long)(pu->parkingtime/1000) - (long)time(NULL), S_OR(pu->chan->cid.cid_num, "<unknown>"), S_OR(pu->chan->cid.cid_name, "<unknown>") ); if (peer && adsipark && ast_adsi_available(peer)) { adsi_announce_park(peer, pu->parkingexten); /* Only supports parking numbers */ ast_adsi_unload_session(peer); } con = ast_context_find(parking_con); if (!con) con = ast_context_create(NULL, parking_con, registrar); if (!con) /* Still no context? Bad */ ast_log(LOG_ERROR, "Parking context '%s' does not exist and unable to create\n", parking_con); else { /* Add extension to context */ if (!ast_add_extension2(con, 1, pu->parkingexten, 1, NULL, NULL, parkedcall, strdup(pu->parkingexten), ast_free, registrar)) notify_metermaids(pu->parkingexten, parking_con); } /* Tell the peer channel the number of the parking space */ if (peer && pu->parkingnum != -1) /* Only say number if it's a number */ ast_say_digits(peer, pu->parkingnum, "", peer->language); if (pu->notquiteyet) { /* Wake up parking thread if we're really done */ ast_indicate_data(pu->chan, AST_CONTROL_HOLD, S_OR(parkmohclass, NULL), !ast_strlen_zero(parkmohclass) ? strlen(parkmohclass) + 1 : 0); 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 157 of file res_features.c. Referenced by builtin_blindtransfer(), dp_lookup(), handle_request_refer(), mgcp_ss(), socket_process(), and ss_thread(). { return parking_ext; }

int ast_pickup_call (  struct ast_channel *  chan  )

Pickup a call. Definition at line 2045 of file res_features.c. References ast_channel::_state, ast_answer(), ast_channel_masquerade(), ast_channel_unlock, ast_channel_walk_locked(), AST_CONTROL_ANSWER, ast_log(), ast_queue_control(), AST_STATE_RING, AST_STATE_RINGING, ast_channel::callgroup, LOG_DEBUG, LOG_WARNING, option_debug, ast_channel::pbx, and ast_channel::pickupgroup. Referenced by cb_events(), handle_request_invite(), mgcp_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_channel_unlock(cur); } 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_channel_unlock(cur); } 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 162 of file res_features.c. Referenced by cb_events(), get_destination(), handle_request_invite(), handle_showfeatures(), mgcp_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 883 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. { 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 899 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); }

---

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