iotum offers a Voice 2.0 call management service, which intelligently filters, ranks, and prioritizes calls based on their relevance to you. Using your contextual information and preferences, iotum knows who's calling, whether you want to take the call, and which phone you want to use.
For gathering context, iotum currently provides a Microsoft Windows application and a Microsoft Outlook plugin, which gathers contextual information from the user's contacts, calenders, and MSN presence, and forwards that to the iotum server.
The iotum server offers an xml-rpc web service to make this information available to call routing applications such as pbxs or phone switches. The pbx or soft switch can integrate with the iotum service by making an xml-rpc call and rerouting the call based on the returned action information.
Asterisk, being open source and extensible, is an excellent place to do such an integration. Asterisk can be extended by writing a module, which is a dynamically loadable shared library that exports an expected set of functions.
Figure 1. The iotum module allows Asterisk to use the iotum service to determine where to route your calls.
When a module is loaded and initialized by Asterisk it can make new functions available to the dial plan. The Asterisk administrator can then call those functions from the dial plan and add the iotum functionality for their users.
The dial plan is a domain-specific language for manipulating calls, media, and other aspects of Asterisk. Offering new functions from a module increases the power of the dial plan language, giving the administrators the ability to offer more features to their users.
The Asterisk source distribution includes an example module file in the apps directory, named app_skel.c . This is about the minimum amount of code required to have a module load into Asterisk and provide new functionality to the dial plan. However, in this file there are some techniques used for which there are now newer and easier alternatives, such as how to extract the parameters passed from the dialplan.
If you're not sure how to do something, look for similar functionality in other Asterisk applications, such as Dial (app_dial.c) or Voicemail (app_voicemail.c).
The iotum server offers an xml-rpc interface to the process call application, and to talk to it we make use of an excellent xml-rpc implementation provided by the xmlrpc-c library. Installing that library is the first step to building the iotum Asterisk module. The iotum Asterisk module also links with these libraries: dl z ssl crypto curl pthread.
After building and installing xmlrpc-c for your server and ensuring the other libraries are available, the next step is to add the iotum module to the asterisk build. After unpacking iotum_asterisk.tar.gz (which can be downloaded at http://www.iotum.com/asterisk/iotum_asterisk.tar.gz):
copy app_iotum.c into the asterisk apps directory
eg. /usr/src/asterisk-1.2/appsModify the Makefile in asterisk-1.2/apps by
app_iotum.so to the APPS listIOTUMLIBS=/usr/local/lib/libxmlrpc_client.a /usr/local/lib/libxmlrpc.a
/usr/local/lib/libxmlrpc_xmlparse.a /usr/local/lib/libxmlrpc_xmltok.a
-ldl -lz -lssl -lcrypto -lcurl -lpthreadapp_iotum.so: app_iotum.o
$(CC) $(SOLINK) -o $@ ${CYGSOLINK} $< ${CYGSOLIB} ${IOTUMLIBS}Now compile from the main asterisk directory (eg. /usr/src/asterisk-1.2) with:
make installThere's one more important file, iotum.conf. This file lives with all of the asterisk configuration files, usually in /etc/asterisk. It looks like this:
[general]
server=https://ws.myiotum.com
port=443
pbxAccount=
pbxAccountPwd=
conferenceRooms=The pbxAccount and pbxAccountPwd are provided by iotum when you've signed up for an account. This is the account which has the authority to ask the iotum server to process the incoming calls. To sign up for an iotum account go to www.iotum.com and follow the links under Asterisk. The conferenceRooms setting is a comma delimited list of the MeetMe rooms which have been configured, and are intended for the iotum Asterisk Module's sole use, eg. conferenceRooms=300,301,302,303.
Once this file is created, restart asterisk or connect to the asterisk CLI and load the module:
breadmaster*CLI> load app_iotum.so
Loaded /usr/lib/asterisk/modules/app_iotum.so => (iotum Relevance Engine Application)
== Registered application 'iotumRelevance'
== Registered application 'iotumConfOutgoing'
== Registered custom function IOTUMRELEVANCE
== Parsing '/etc/asterisk/iotum.conf': Found
> iotum: Room 300 added to conference rooms list
> iotum: Room 301 added to conference rooms list
> iotum: Room 302 added to conference rooms list
> iotum: Room 303 added to conference rooms list
|
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
Copyright © 2009 O'Reilly Media, Inc.