How-to: Write an Asterisk Module, Part 1

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.

33 thoughts on “How-to: Write an Asterisk Module, Part 1

  1. Pingback: Programando módulos personalizados para Asterisk at Mi Brain-Training Personal

  2. Pingback: How-to: Write an Asterisk Module, Part 2

  3. Pingback: Tutorials for writing Asterisk modules « Michigan Telephone, VoIP and Broadband blog

  4. Pingback: How-to: Write an Asterisk Module, Part 3

  5. 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.

  6. 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.

  7. 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.

  8. Could you help me out? I’m trying to compile a module created to A1.6 but when I try to load it into A1.4 it says: “Module xxxx.so does not provide a description”. I don’t know it this changed 1.4->1.6 or I’m making a big mistake… Thanks.

  9. Pingback: Asterisk Module Programming : alexanderjohansen[dot]com

  10. Hi Russel,

    Thank you for great article, some thing i have been looking for lately as i get more in to linux and asterisk development, still very new to all this. I compiled your code as above but I keep getting error AST_MODULE undeclared here but in the function. I know some thing is out of sync but no sure what. Your help would be greatly appreciated. Are there any more resources on developing for asterisk?

  11. Hi Russel,
    Thank you very much for your wonderful work! It is really very commendable.
    I have one question. It is just clarification request. What is the meaning of the folowing statement (that I have seen in app_skel.c)?
    enum {
    OPTION_A = (1 << 0),
    OPTION_B = (1 << 1),
    OPTION_C = (1 << 2),
    } option_flags;

    I know c and c++ , but never came accross with such an enumeration declaration. Could you please describe what it means?

    Thank you

    Best regards,

    Zelalem

  12. The enum that you refer to defines names for bits to be used as flags. OPTION_A is the first bit, OPTION_B is the second bit, OPTION_C is the third bit, …

    So, you can define an integer like this:

    unsigned int flags;

    flags = OPTION_A | OPTION_C;

    That sets two bits in the integer flags to indication that options A and C are enabled.

    Hopefully this helps!

  13. Ray,

    The AST_MODULE error should not happen if you drop the module in the Asterisk build system and let it get built automatically.

    If you’re building the module outside of Asterisk, you can just define it in your souce:

    #ifndef AST_MODULE
    #define AST_MODULE “app_mymodule”
    #endif

      • Follow the examples of the existing modules that use mysql. You can see the commands run by the Asterisk build system if you run “make NOISY_BUILD=yes”.

  14. Hi Russel, I got one problem. I had developed an application that I run successfully (it takes the current exten from asterisk through the chan variable) and then it identifies a path. And then I wanted it to return tha path back to asterisk. My problem is here. I want to return a string value from my application to asterisk, but couldn’t succeed. Please help me. I have done everything but couldn’t return a value back to asterisk. i can even got value from asterisk (like the current extension).

  15. Zelalem, the function that you probably want to use here is pbx_builtin_setvar_helper(). This lets you set a channel variable on a channel that you can access from the dialplan.

    I hope this helps.

  16. Hi Russel, thanks a lot for your “How-to” it is very useful.
    I have a question, because i’m finding much more informations about all functions of Asterisk, because i don’t know to develope a module if i don’t know what are the functions.
    I have seen the “Doxygen code documentation” but seems to be a little ambiguos, because i can see all type of struct but not a list of all functions with specification for each one.
    Can you help and tell me where i can find something like this?
    Thanks a lot.
    Francesco.

  17. Russel,

    thank you very much for this three tutorials and also thanks to SC for showing how to compile only the module and not the whole asterisk.

    It made me going into the right direction of writing custom CDR which POSTS data via HTTP to external server.

  18. I try to compile a module with Asterisk1.8 i couldn’t.

    There is some differences between the too version?

    • Probably … this post is 5 years old now, so it’s not surprising if it’s not accurate anymore. It guides you in the right direction, but the best thing to do is look at some existing modules in the Asterisk source. Look in the funcs/ directory. There should be some relatively small modules in there that you can use as an example.

      • Hello,

        I compiled my module but when try to load it i get an error : “Module xxxxxx.so did not register itself during load”

        From where this error comes? how i can fix it?
        do you have any idea?

  19. hie, Russel
    i am a newbie in asterisk module C coding, thank you for the introduction was really helpful. I need your help with how to implement channels in a module , that allows a sip call to interact with that module , sought of a softphone-> module interaction , where it is called in a asterisk dialplan, and return a voice message , or play an mp3 file within any of my directories..

    • Raymond :
      hie, Russel
      i am a newbie in asterisk module C coding, thank you for the introduction was really helpful. I need your help with how to implement channels in a module , that allows a sip call to interact with that module , sought of a softphone-> module interaction , where it is called in a asterisk dialplan, and return a voice message , or play an mp3 file within any of my directories..

    • I tried to compile the module seperately with the command you mentioned above but for some reason asterisk unable to load the module it gives “me was not compiled with the same compile-time options as this version of Asterisk.”
      what could be the reason , what should i do if we want to load successfully.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s