Building the iotum Asterisk Module
Pages: 1, 2

Introduction to the source code

In load_module() the applications that the module are exposing are registered: res = ast_register_application(app,iotumRelevance_exec,tdesc,synopsis);

The arguments expected by this function are the name of the app that will be exposed to the dialplan, the function pointer for the implementation of the app, a long name of the app, and a short description of the application.

Next, the xml-rpc library is initialized (see the load_module() function in app_iotum.c) and the configuration file is read in (see load_config) using support functions provided by Asterisk. This takes care of loading the file and parsing the entries, leaving the interpretation of the data found up to the module code. See ParseRoomsList for an example of parsing something more complex than a string.

We use ast_mutex_lock()/ast_mutex_unlock() to isolate the global data while it's being written to in load_config().

For historical reasons, the iotum call processing dial plan function is exposed in two different ways. One is a read function named IOTUMRELEVANCE, which returns a string which needs to be parsed by the dial plan. The other is an application named iotumRelevance, which sets channel variables to return information to the dial plan.

The iotumRelevance app is the recommended way to use the iotum service, and the IOTUMRELEVANCE function is being maintained for backwards compatibility with our first release of the Asterisk module. That said, the code to handle the two different entry points is shared.

In Common_exec, the arguments passed into the function are split apart. Using the Asterisk provided AST_DECLARE_APP_ARGS() the expected arguments are declared, ast_strdupa() is called to duplicate the passed argument string data on the local stack, and AST_STANDARD_APP_ARGS() is called to split the duplicated string into the arguments.

Following that the arguments are validated, and any error conditions are reported using the ast_log() facility.

The function process_f() sets up and makes the xml-rpc call, and then hands off the results to the appropriate handler function for extracting the returned information for the different resulting actions.

For the results of ACCEPT and DECLINE there's little extra work. The result is returned and in the case of an error, the module returns ACCEPT so that the calls will get through in a worst case scenario.

When the REDIRECT action is returned the new destination is returned as the target destination. There is one special case, where the account holder's number is returned with ;actor="msg-taker" appended, which indicates that the call should be sent to voicemail. Otherwise the target is the destination number, with a tel: or sip: prefix.

The most complex case is for the CONFERENCE action. There are two values returned with the CONFERENCE action, name and participants. Name is used to identify that particular conference call, so that subsequent callers can be joined into the same conference call. Participants is a list of numbers which could be called and joined into the same conference room. We'll get to that later.

First, we need a conference room. On Asterisk, there's MeetMe conferences for this kind of application. The iotum.conf file contains a list of the rooms available for the iotum Module's exclusive use. This is kept in memory, from when the module was loaded. When a room is needed, the list is searched, looking for an unassigned room, or failing that, an empty room to be reused. Once found, the room is assigned, and the participants are added to a list associated with the room.

The MeetMe room is returned to the dial plan in the IOTUM_CONFERENCE channel variable. Back in Common_exec() the returned values are set into the proper channel variables.

The function then returns control to the dial plan, which acts on the results, routing the call appropriately.

The dial plan is where the real functionality comes into play. The way the iotum module exposes the iotumRelevance function, the dial plan can react to any of the resulting actions however it wants. This keeps the control of the calls in the dial plan.

For the ACCEPT action, the call should be routed to the users usual location. For the DECLINE action, the call should be declined. The dial plan could either hangup on the caller, or play a message and hang up. For the VMAIL action, the call should be sent directly to voicemail.

For the REDIRECT action, the call should be sent to the number stored in the IOTUM_REDIRECT channel variable. This number can be dialed using the Asterisk Dial application.

The CONFERENCE action is the most complex to handle. There are a couple of options. The first is to just conference the caller into the MeetMe room that's returned in the IOTUM_CONFERENCE channel variable. This will require each person invited to the conference to call to the organizer to be placed into the conference.

For more sophisticated handling, the dial plan can make use of the iotumConfOutgoing() dial plan application which will initiate calls to the participants. Again, most of the power lies in the dial plan for setting this. The IotumConfOutgoing() needs to be told how to call out, ie. which technology (SIP, Zap or other) and which context to use to make the outgoing call, as well as which context will handle the call on the asterisk end, before routing it into the MeetMe room. In the example we include, the Asterisk end of the conference call prompts the called person to 'Press 1' before joining them into the MeetMe room. This prevents voicemail systems from being joined into conference calls.

Please see the extensions.conf included in our source distribution to see an example of how this is used.

Asterisk's rich set of features and extensibility make it possible to change it in any way you need. At iotum we were able to create a module which extends the power of the dial plan, making the iotum service available to every Asterisk user.

Todd Jefferson is Chief Code Wrangler at iotum where he spends his days coding voice 2.0 applications.

---

Return to the O'Reilly Emerging Telephony