FreePBX API: Extensions Class

The extensions class exists to allow multiple modules to create dialplan code, including modifying code created by other modules, in a way that minimizes the possibility for conflicts.

freepbx/trunk/amp_conf/htdocs/admin/extensions.class.php

---

General Overview

The way the dialplan (Extensions.conf) is generated in FreePBX 2.x is as follows:

• retrieve_conf loads all functions.inc.php files (from all modules)
• retrieve_conf creates a new Extension class with the global variable $ext
• retrieve_conf runs all the <modulename>_get_config() functions
  • These methods should add extensions to the $ext Extensions variable

Often it is necessary to detect the version of asterisk, and customize the exact commands based on that. Several modules do that, so if you look through the various _get_config() functions you'll see that happening.

It is also worth noting that every _get_config() function checks the $engine variable (a parameter passed to _get_config()), usually in a switch statement. This is for future expansion in supporting other engines besides Asterisk.

_get_config() methods

modulename_get_config() gets one parameter, the $engine currently being used.

There are also a few global variables: $ext, containing the extensions class instance. $amp_conf, an Array containing the amportal.conf values. $db, containing the database object.

Typical skeleton:

function modulename_get_config($engine) {
    global $ext, $amp_conf, $db;
    switch ($engine) {
        case 'asterisk':
            .....
        break;
    }
}

extensions API

add()

extensions::add($section, $extension, $tag, $command, $basetag = false, $addpriority = false)

Parameter	Type	Description
$section	string	The section to be added to
$extension	string	The extension number (or pattern) to use
$tag	string	A tag to use when referencing this item with $basetag
$command	extension	The actual command to execute, which is a child of the extension class
$basetag	string	The tag to base this on. Only used in conjunction with $addpriority priority. Defaults to false.
$addpriority	int	Finds the priority of the tag called $basetag, and adds this value to it to use as the priority for this command.

priorities

Note that you don't have to worry about priorities - when the dialplan is generated, it automatically starts at 1, then uses n after that.

To do an n+101 style jump, you use $tag, $basetag, and $addpriority. See the example below.

splice()

todo

addInclude()

extensions::addInclude($section, $incsection)

Parameter	Type	Description
$section	string	The section to add the include to
$incsection	string	The section to be included

Examples

Simple

    $id = "app-callwaiting-cwon"; // The context to be included  
    $c = '*70';
    $ext->addInclude('from-internal-additional', $id);
    $ext->add($id, $c, '', new ext_answer('')); // $cmd,1,Answer
    $ext->add($id, $c, '', new ext_wait('1')); // $cmd,n,Wait(1)
    $ext->add($id, $c, '', new ext_macro('user-callerid')); // $cmd,n,Macro(user-callerid)
    $ext->add($id, $c, '', new ext_setvar('DB(CW/${AMPUSER})', 'ENABLED'));
    $ext->add($id, $c, '', new ext_playback('call-waiting&activated')); // $cmd,n,Playback(...)
    $ext->add($id, $c, '', new ext_macro('hangupcall')); // $cmd,n,Macro(user-callerid)

This generates:

[from-internal-additional]
include => app-callwaiting-cwon

[app-callwaiting-cwon]
include => app-callwaiting-cwon-custom
exten => *70,1,Answer
exten => *70,n,Wait(1)
exten => *70,n,Macro(user-callerid,)
exten => *70,n,Set(DB(CW/${AMPUSER})=ENABLED)
exten => *70,n,Playback(call-waiting&activated)
exten => *70,n,Macro(hangupcall,)

Goto example

    $id = "app-blacklist-check";
    $c = "s";
    $ext->add($id, $c, '', new ext_lookupblacklist(''));
    $ext->add($id, $c, '', new ext_gotoif('$["${LOOKUPBLSTATUS}"="FOUND"]', 'blacklisted'));
    $ext->add($id, $c, '', new ext_return(''));
    $ext->add($id, $c, 'blacklisted', new ext_answer(''));
    $ext->add($id, $c, '', new ext_wait(1));
    $ext->add($id, $c, '', new ext_zapateller(''));
    $ext->add($id, $c, '', new ext_playback('ss-noservice'));
    $ext->add($id, $c, '', new ext_hangup(''));

Generates:

[app-blacklist-check]
include => app-blacklist-check-custom
exten => s,1,LookupBlacklist()
exten => s,n,GotoIf($["${LOOKUPBLSTATUS}"="FOUND"]?blacklisted)
exten => s,n,Return()
exten => s,n(blacklisted),Answer
exten => s,n,Wait(1)
exten => s,n,Zapateller()
exten => s,n,Playback(ss-noservice)
exten => s,n,Hangup

Note the use of the $tag parameter as a goto target

Priorities Adding

    $ext->add($context, $code, 'check', new ext_chanisavail('${DIAL}', 'sj'));
    $ext->add($context, $code, '', new ext_dial('${DIAL}','5,A(beep)'));
    $ext->add($context, $code, '', new ext_macro('hangupcall'));
    $ext->add($context, $code, '', new ext_busy(), 'check',101);

Generates:

exten => _*80.,n(check),ChanIsAvail(${DIAL},sj)
exten => _*80.,n,Dial(${DIAL},5,A(beep))
exten => _*80.,n,Macro(hangupcall,)
exten => _*80.,check+101,Busy(20)