Module ext_ast_interface

Copyright © 2005-2006 Ericsson

• Description
• Data Types
• Function Index
• Function Details

Version: 1.0

Behaviour: gen_server.

Authors: Freek Sanders (freekisanders@gmail.com) [web site: http://www.freeksanders.tk].

Description

This module is the center of the communication between the Asterisk opensource PBX and the ExtENS network simulator. It contains information about all calls, legs and resources in the form of records.

Call

A point where telephone callers are connected to each other, but also to resources.

A telephone caller or callee, i.o.w. one end of a telephone conversation.

A external program which performs actions on a call, or directly on a leg. These actions include playing and recording sound, as well as receiving dtmf events.

The first thing is to startup the Idefisk system through 'run_idefisk.sh' in the main directory. After this, the flow of events can be started by either:

1. A incoming call from Asterisk. This causes the system to create a call and a leg, and to alert the extens_module (see ext_ast_interface:update_ext_module/1) to the incoming call.
2. Extens who calls create_call (see ext_ast_interface:create_call/1) to create a new call record. After creating a call, Extens can then create one or more legs (see ext_ast_interface:create_leg/2) and route these (see ext_ast_interface:route_leg/5). After routing, a leg can be attached (see ext_ast_interface:attach_leg/2), so as to give the person connected to the leg the ability to receive or send sound to the call. Attached legs can be removed by detaching, and then releasing them. Besides legs, resources can also be created (see ext_ast_interface:reserve_resource/3) and attached (see ext_ast_interface:attach_resource/2) . After this they can be used (see ext_ast_interface:play/3, (see ext_ast_interface:record/3), (see ext_ast_interface:start_dtmf/2) or (see ext_ast_interface:record/3) ). Resources can be stopped (see ext_ast_interface:stop/2), detached (see ext_ast_interface:detach_resource/2) and released (see ext_ast_interface:pronounce/3).

Calls which are no longer needed can be released (see ext_ast_interface:release_call/1).

The following messages are send to functions which are provided by ExtENS, or to ExtENS self. The function for ExtENS has been defined as: fun(X) -> ext_module:call_msg(CallId, self(), X) end. Because of this definition, the call id of the call to which the message refers can also be found in the message.

Messages to ExtENS

Messages to a leg

Messages to a resource

The Ext-Ast-Interface has been implemented using the gen-server behaviour. This means that all function calls returning 'ok' (see below) are gen_server casts, which carry out their function asynchronously. An 'ok' does not mean success. If a function has success or not can only be derived from side-effects and messages such as send by the Ext-Ast-Interface (see above).

Data Types

ast_module()

ast_module() = atom()

call()

call() = {Id::integer(), Legs::[leg()], Resources::[resource()], F::function()}

ext_module()

ext_module() = atom()

leg()

leg() = {Id::integer(), Channel::string(), Dest_addr::string(), Orig_addr::string(), Ast_id::string(), State::atom(), Context::string(), F::function(), Agi_pid::pid()}

pending_call()

pending_call() = {Id::integer(), Call_id::integer(), Leg_id::integer()}

resource()

resource() = {Id::integer(), State::atom(), Type::atom(), File::string(), Leg::integer(), Stopped::bool(), Reserved_side::bool(), F::function(), Chan_1::string(), Chan_2::string(), Ast_id_1::string(), Ast_id_2::string()}

Function Index

Function Details

attach_leg/2

attach_leg(CallId::integer(), LegId::integer()) -> ok

Attaches a leg. The leg to be attached must have been created and routed first.

Introduced in: 0.1

See also: ext_ast_interface:create_leg/2, ext_ast_interface:route_leg/5.

attach_resource/3

attach_resource(CallId::integer(), LegId::integer(), ResourceId::integer()) -> ok

Attaches a resources. The resource to be attached must have been created first.

Introduced in: 0.1

See also: ext_ast_interface:reserve_resource/3.

create_call/1

create_call(F::function()) -> ok

Creates a new call record The function is used to pass messages for this call.

Introduced in: 0.1

create_leg/2

create_leg(CallId::integer(), F::function()) -> ok

Creates a new leg record. A call with the given call id has to be created first, either by Asterisk or ExtENS. The function is used to pass messages for this leg.

Introduced in: 0.1

See also: ext_ast_interface:create_call/1.

detach_leg/2

detach_leg(CallId::integer(), LegId::integer()) -> ok

Detaches a leg. The leg to be detached must have been created and routed first.

Introduced in: 0.1

See also: ext_ast_interface:create_leg/2, ext_ast_interface:route_leg/5.

detach_resource/2

detach_resource(CallId::integer(), ResourceId::integer()) -> ok

Detaches a resource. The resource to be detached must have been created first.

Introduced in: 0.1

See also: ext_ast_interface:reserve_resource/3.

get_state/0

get_state() -> State::{Calls::[call()], PendingCalls::[pending_call()], ExtensModule::ext_module(), AstModule::ast_module()}

Retrieves the current state of the Ext-Ast-Interface server

Introduced in: 0.1

play/3

play(CallId::integer(), ResourceId::integer(), File::string()) -> ok

Start to play sound. A resource whose id is resource id, must have been created. This resource must also be attached and of the type 'SOUND PLAYER'. Note: the resources 'SOUND PLAYER', 'SOUND RECORDER' and 'TEXT PRONOUNCER' are equal. This means play can also be called on a 'SOUND PLAYER'.

Introduced in: 0.1

See also: ext_ast_interface:attach_resource/3, ext_ast_interface:reserve_resource/3.

pronounce/3

pronounce(CallId::integer(), ResourceId::integer(), Text::string()) -> ok

Pronounce a given text string. A resource whose id is resource id, must have been created. This resource must also be attached and of the type 'TEXT PRONOUNCER'. Note: the resources 'SOUND PLAYER', 'SOUND RECORDER' and 'TEXT PRONOUNCER' are equal. This means pronounce can also be called on a 'SOUND PLAYER'.

Introduced in: 1.0

See also: ext_ast_interface:attach_resource/3, ext_ast_interface:reserve_resource/3.

record/3

record(CallId::integer(), ResourceId::integer(), File::string()) -> ok

Start to record sound. A resource whose id is resource id, must have been created. This resource must also be attached and of the type 'SOUND RECORDER'. Note: the resources 'SOUND PLAYER', 'SOUND RECORDER' and 'TEXT PRONOUNCER' are equal. This means record can also be called on a 'SOUND PLAYER'.

Introduced in: 0.1

See also: ext_ast_interface:attach_resource/3, ext_ast_interface:reserve_resource/3.

release_call/1

release_call(CallId::integer()) -> ok

Releases a call and its record. Also releases all legs and resources in the call.

Introduced in: 0.1

See also: ext_ast_interface:release_leg/3, ext_ast_interface:release_resource/2.

release_leg/3

release_leg(CallId::integer(), LegId::integer(), Cause) -> ok

Releases a leg and its record. If this is the last leg in a call, the call is also released.

Introduced in: 0.1

See also: ext_ast_interface:release_call/1.

release_resource/2

release_resource(CallId::integer(), ResourceId::integer()) -> ok

Releases a resource and its record. It is advisable to stop and detach a resource before releasing it

Introduced in: 0.2

See also: ext_ast_interface:detach_resource/2, ext_ast_interface:stop/2.

reserve_resource/3

reserve_resource(CallId::integer(), Type::resource_type(), F::funcion()) -> ok

• resource_type() = 'SOUND PLAYER' | 'SOUND RECORDER' | 'TEXT PRONOUNCER' | 'DTMF RECEIVER'

Reserves a new resource of a given type. A call with the given call id has to be created first, either by Asterisk or ExtENS. The function is used to pass messages for this resource.

Introduced in: 0.1

See also: ext_ast_interface:create_call/1.

route_leg/5

route_leg(CallId::integer(), LegId::integer(), ChanType::chantype(), DestAddr::string(), OrigAddr::string()) -> ok

• chantype() = PSTN | SIP | IAX

Routes an existing leg to the specified address. The leg record whose id is leg id must have been created first.

Introduced in: 0.1

See also: ext_ast_interface:create_leg/2.

start_dtmf/2

start_dtmf(CallId::integer(), ResourceId::integer()) -> ok

Start to record dtmf. A resource whose id is resource id, must have been created. This resource must also be attached and of the type 'DTMF RECEIVER'.

Introduced in: 0.2

See also: ext_ast_interface:attach_resource/3, ext_ast_interface:reserve_resource/3.

stop/2

stop(CallId::integer(), ResourceId::integer()) -> ok

Stop a resource.

Introduced in: 0.1

update_ast_module/1

update_ast_module(NewAstModule::atom()) -> ok

Changes the Asterisk module, to which information from ExtENS is send

Introduced in: 0.1

update_ext_module/1

update_ext_module(NewExtModule::atom()) -> ok

Changes the ExtENS module, to which information from Asterisk is send

Introduced in: 0.1