Have you ever wanted to write an Asterisk module? While some of the Asterisk modules are quite complicated, the anatomy of an Asterisk module is pretty simple. Let’s start with the “Hello World” of Asterisk modules: res_helloworld.
This example is based on Asterisk 1.6. However, creating Asterisk modules for Asterisk 1.4 is almost the exact same.
Create a file called res_helloworld.c in the res/ directory of an Asterisk source tree.
The first thing in every Asterisk module is to include the main Asterisk header file, asterisk.h.
#include "asterisk.h"
Next, include the ASTERISK_FILE_VERSION macro. This registers the file with the “core show file version” CLI command. This CLI command lists the last SVN revision where that file changed.
ASTERISK_FILE_VERSION(__FILE__, "$Revision: $")
Include the Asterisk module header file. This includes the definitions necessary for implementing an Asterisk module.
#include "asterisk/module.h"
Let’s go ahead and include the header file that lets us use the Asterisk logging interface, as well. This will let us print messages to the Asterisk log so that our new module actually does something.
#include "asterisk/logger.h"
It is now time to include the two functions that every Asterisk module must implement. Those are load_module() and unload_module(). These functions get called when Asterisk loads and unloads the module.
static int load_module(void)
{
ast_log(LOG_NOTICE, "Hello World!\n");
return AST_MODULE_LOAD_SUCCESS;
}
static int unload_module(void)
{
ast_log(LOG_NOTICE, "Goodbye World!\n");
return 0;
}
Finally, every module must include an instance of one of the AST_MODULE_INFO macros. This macro includes the necessary code for the module to properly register itself with the Asterisk core when it gets loaded.
AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Hello World");
The final result should look something like this: res_helloworld.c
When you run make to compile Asterisk, the build system should automatically find your module. It will be compiled and installed with the rest of Asterisk. Compile, install, and run Asterisk. Then, verify that your module has been loaded:
*CLI> module show like helloworld
Module Description Use Count
res_helloworld.so Hello World 0
1 modules loaded
You should also be able to unload and load your module, and see the appropriate message in the Asterisk logger.
*CLI> module unload res_helloworld.so
[Jun 19 10:50:57] NOTICE[26612]: res_helloworld.c:35 unload_module: Goodbye World!
*CLI> module load res_helloworld.so
[Jun 19 10:51:05] NOTICE[26612]: res_helloworld.c:42 load_module: Hello World!
Loaded res_helloworld.so => (Hello World)
Congratulations! You have successfully written an Asterisk module!
Next, we will start looking at how to start implementing more useful things inside of this module structure.
8 responses so far ↓
1 Programando módulos personalizados para Asterisk at Mi Brain-Training Personal // Jun 19, 2008 at 1:53 pm
[...] Que no cunda el panico, Russell ha empezado una guia en su blog en la que explica como compilar módulos para Asterisk Aquí tenéis la primera entrega: http://www.russellbryant.net/blog/index.php/2008/06/19/how-to-write-an-asterisk-module-part-1/ [...]
2 How-to: Write an Asterisk Module, Part 2 // Jun 20, 2008 at 5:15 pm
[...] part 1, I explained the “Hello World” of Asterisk modules. It implemented just enough to [...]
3 Tutorials for writing Asterisk modules « Michigan Telephone, VoIP and Broadband blog // Jun 20, 2008 at 5:38 pm
[...] Russell Bryant is starting a series of tutorials on “How-to: Write an Asterisk Module.” Part 1 and Part 2 are now online. For those of you who may have wanted to write an Asterisk module but [...]
4 Matt Riddell // Jun 22, 2008 at 4:59 pm
Cool, will put this up straight away! Great to see, it’s been something I think people have been wondering for a while.
5 How-to: Write an Asterisk Module, Part 3 // Jun 30, 2008 at 7:32 am
[...] Part 1 - Basic Module Structure Part 2 - CDR Handling Interface [...]
6 Larchen // Jul 1, 2008 at 7:56 am
If you need to write a module on Asterisk 1.4.x, you have to add this include:
#include “asterisk/module.h”
to include section of .c file.
7 sc // Jul 7, 2008 at 6:31 am
You can avoid compiling the whole asterisk. You can just compile only the module you created using this command:
gcc -pipe -Wall -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations -g3 -Iinclude -I../include -D_REENTRANT -D_GNU_SOURCE -O6 -march=i686 -fomit-frame-pointer -Wno-missing-prototypes -Wno-missing-declarations -DCRYPTO -fPIC -c -o
after that you link the object with this command:
gcc -shared -Xlinker -x -o
and finally you install it using:
install -m 755 /usr/lib/asterisk/modules
Thats it !!
Don’t forget to unload and load again the module in asterisk
SC
P.S. you can change some parameters in your compilation command according to your needs.
8 sc // Jul 7, 2008 at 6:37 am
the text in my last post was truncated some how, this should be OK now
You can avoid compiling the whole asterisk and just compile only the module you created using this command:
gcc -pipe -Wall -Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations -g3 -Iinclude -I../include -D_REENTRANT -D_GNU_SOURCE -O6 -march=i686 -fomit-frame-pointer -Wno-missing-prototypes -Wno-missing-declarations -DCRYPTO -fPIC -c -o YOUR_MODULE_NAME.o YOUR_MODULE_NAME.c
after that you link the object with this command:
gcc -shared -Xlinker -x -o YOUR_MODULE_NAME.so YOUR_MODULE_NAME.o
and finally you install it using:
install -m 755 YOUR_MODULE_NAME.so /usr/lib/asterisk/modules
Thats it !!
Don’t forget to unload and load again the module in asterisk
SC
P.S. you can change some parameters in your compilation command according to your needs.
Leave a Comment