- Plugin API

doc/siproxd_guide.sgml

@@ -43,6 +43,12 @@
         <authorinitials>tries@users.sourceforge.net</authorinitials>
         <revremark>New Asterisk Config Files</revremark>
       </revision>
+      <revision>
+        <revnumber>0.7.1</revnumber>
+        <date>2008-01-27</date>
+        <authorinitials>tries@users.sourceforge.net</authorinitials>
+        <revremark>Plugin API</revremark>
+      </revision>
     </revhistory>
   </bookinfo>
   <toc></toc>
@@ -523,10 +529,102 @@ pi_shortdial_entry = 17474745000
       <para>Create chroot jail</para>
       <para>What files must be present?</para>
     </sect1>
+  </chapter>
 
-    <!-- Chapter 4.3: Quick Dial -->
+  <!-- Chapter 5: Plugins -->
-    <sect1 label="4.3">
+  <chapter label="5" id="Plugins">
-      <?dbhtml filename="siproxd_guide_c4s3.html">
+    <?dbhtml filename="siproxd_guide_c5.html">
+    <title>Plugins</title>
+
+    <!-- Chapter 5.1: Plugin API -->
+    <sect1 label="5.1">
+      <?dbhtml filename="siproxd_guide_c5s1.html">
+      <title>Plugin API</title>
+      <para>Siproxd plugins are dynamic loadable libraries and must provide
+        3 functions towards siproxd:
+<screen>
+int  plugin_init(plugin_def_t *plugin_def);
+int  plugin_process(int stage, sip_ticket_t *ticket);
+int  plugin_end(plugin_def_t *plugin_def);
+</screen>
+        </para>
+      <para>
+        The <filename>plugin_init</filename> function is called when
+        the plugin is loaded during startup of siproxd. The plugin must
+        defined the following 4 fields of the plugin_def structure:
+        <orderedlist numeration="arabic">
+          <listitem><para><filename>api_version</filename></para></listitem>
+          <listitem><para><filename>name</filename></para></listitem>
+          <listitem><para><filename>desc</filename></para></listitem>
+          <listitem><para><filename>exe_mask</filename></para></listitem>
+        </orderedlist>
+
+        Example code fragment:
+<screen>
+/* API version number of siproxd that this plugin is built against.
+ * This constant will change whenever changes to the API are made
+ * that require adaptions in the plugin. */
+plugin_def->api_version=SIPROXD_API_VERSION;
+
+/* Name and descriptive text of the plugin */
+plugin_def->name=strdup("plugin_demo");
+plugin_def->desc=strdup("This is just a demo plugin without any purpose");
+
+/* Execution mask - during what stages of SIP processing shall
+ * the plugin be called. */
+plugin_def->exe_mask=PLUGIN_DETERMINE_TARGET|PLUGIN_PRE_PROXY;
+</screen>
+        </para>
+      <para>
+        The <filename>plugin_process</filename> function is called at
+        the requested SIP processing stages (see 'execution mask').
+        Your processing will be done here.
+        </para>
+      <para>
+        The <filename>plugin_end</filename> function is called at
+        shutdown of siproxd and gives the plugin the opportunity
+        to clean up and properly shutdown itself.</para>
+      <para>Note: The previously allocated 'name' and 'desc' must be
+        freed by the plugin.</para>
+      <para>
+        Minimum required clean up procedure:
+<screen>
+int  plugin_end(plugin_def_t *plugin_def){
+   /* free my allocated rescources */
+   if (plugin_def->name) {free(plugin_def->name); plugin_def->name=NULL;}
+   if (plugin_def->desc) {free(plugin_def->desc); plugin_def->desc=NULL;}
+   return STS_SUCCESS;
+}
+</screen>
+        </para>
+      <para>
+        For a simple example refer to the simple demonstration plugin
+        <filename>plugin_demo</filename>.
+        .</para>
+    </sect1>
+
+    <!-- Chapter 5.2: Available Plugins -->
+    <sect1 label="5.2">
+      <?dbhtml filename="siproxd_guide_c5s2.html">
+      <title>Available Plugins</title>
+      <para>The following plugins are provided with siproxd:
+        <orderedlist numeration="arabic">
+          <listitem><para><filename>plugin_demo</filename></para>
+                    <para>Demo plugin. Provides the basic framework to
+                      be used for plugins.
+                    </para></listitem>
+          <listitem><para><filename>plugin_shortdial</filename></para>
+                    <para>Quick Dial feature.
+                    </para></listitem>
+        </orderedlist>
+        Some of the plugins are described in more detail in the
+        following chapters.
+      </para>
+    </sect1>
+
+    <!-- Chapter 5.3: Quick Dial -->
+    <sect1 label="5.3">
+      <?dbhtml filename="siproxd_guide_c5s3.html">
       <title>Quick Dial</title>
 <!--&&&& do be completed -->
       <para>Since 0.5.12, Siproxd includes a Quick-Dial feature. This
@@ -546,14 +644,14 @@ pi_shortdial_entry = 17474745000
     </sect1>
   </chapter>
 
-  <!-- Chapter 5: Troubleshooting -->
+  <!-- Chapter 6: Troubleshooting -->
-  <chapter label="5" id="Troubleshooting">
+  <chapter label="6" id="Troubleshooting">
-    <?dbhtml filename="siproxd_guide_c5.html">
+    <?dbhtml filename="siproxd_guide_c6.html">
     <title>Troubleshooting</title>
 
-    <!-- Chapter 5.1: Problem Reporting -->
+    <!-- Chapter 6.1: Problem Reporting -->
-    <sect1 label="5.1">
+    <sect1 label="6.1">
-      <?dbhtml filename="siproxd_guide_c5s1.html">
+      <?dbhtml filename="siproxd_guide_c6s1.html">
       <title>Problem Reporting</title>
       <para>If you encounter problems/crashes and ask for support,
         please include as much information as possible. Very helpful
@@ -563,9 +661,9 @@ pi_shortdial_entry = 17474745000
         include your <filename>siproxd.conf</filename>.</para>
     </sect1>
 
-    <!-- Chapter 5.2: Create a Debug Log -->
+    <!-- Chapter 6.2: Create a Debug Log -->
-    <sect1 label="5.2">
+    <sect1 label="6.2">
-      <?dbhtml filename="siproxd_guide_c5s2.html">
+      <?dbhtml filename="siproxd_guide_c6s2.html">
       <title>Create a Debug Log</title>
       <para>The easiest way to generate a debug log is:
         <orderedlist numeration="arabic">
@@ -597,9 +695,9 @@ pi_shortdial_entry = 17474745000
         the outbound network) can connect.</para>
     </sect1>
 
-    <!-- Chapter 5.3: Siproxd crashes -->
+    <!-- Chapter 6.3: Siproxd crashes -->
-    <sect1 label="5.3">
+    <sect1 label="6.3">
-      <?dbhtml filename="siproxd_guide_c5s3.html">
+      <?dbhtml filename="siproxd_guide_c6s3.html">
       <title>Siproxd crashes</title>
       <para>If siproxd crashes, a stack back trace usually is
         helpful to me:
@@ -635,7 +733,7 @@ pi_shortdial_entry = 17474745000
     </sect1>
   </chapter>
 
-  <!-- Chapter 6: Sample Configurations -->
+  <!-- Chapter 7: Sample Configurations -->
   <chapter label="6" id="Sample-Configurations">
      <?dbhtml filename="siproxd_guide_c6.html">
     <title>Sample Configurations</title>

src/plugin_demo.c

@@ -76,7 +76,11 @@ int  plugin_process(int stage, sip_ticket_t *ticket){
  * to clean up its mess (e.g. dynamic memory allocation, database
  * connections, whatever the plugin messes around with)
  */
-int  plugin_end(void){
+int  plugin_end(plugin_def_t *plugin_def){
+   /* free my allocated rescources */
+   if (plugin_def->name) {free(plugin_def->name); plugin_def->name=NULL;}
+   if (plugin_def->desc) {free(plugin_def->desc); plugin_def->desc=NULL;}
+
    INFO("plugin_demo ends here");
    return STS_SUCCESS;
 }

src/plugin_shortdial.c

@@ -63,7 +63,11 @@ int  plugin_process(int stage, sip_ticket_t *ticket){
 }
 
 /* De-Initialization */
-int  plugin_end(void){
+int  plugin_end(plugin_def_t *plugin_def){
+   /* free my allocated rescources */
+   if (plugin_def->name) {free(plugin_def->name); plugin_def->name=NULL;}
+   if (plugin_def->desc) {free(plugin_def->desc); plugin_def->desc=NULL;}
+
    return STS_SUCCESS;
 }
 

src/plugins.c

@@ -40,7 +40,7 @@ plugin_def_t *siproxd_plugins=NULL;
 /* code */
 typedef int (*func_plugin_init_t)(plugin_def_t *plugin_def);
 typedef int (*func_plugin_process_t)(int stage, sip_ticket_t *ticket);
-typedef int (*func_plugin_end_t)(void);
+typedef int (*func_plugin_end_t)(plugin_def_t *plugin_def);
 
 
 /* 
@@ -110,7 +110,8 @@ int load_plugins (void) {
             ERROR("Plugin '%s' does not support correct API version. "
                   "Please compile plugin with correct siproxd version.",
                   cur->name);
-            sts=(*plugin_end)();
+            sts=(*plugin_end)(cur);
+            free(cur);
             continue;
          }
 
@@ -207,7 +208,7 @@ int unload_plugins(void) {
       for (cur=siproxd_plugins; cur->next != NULL; cur = cur->next) {last=cur;}
 
       plugin_end=cur->plugin_end;
-      sts=(*plugin_end)();
+      sts=(*plugin_end)(cur);
       DEBUGC(DBCLASS_PLUGIN, "unload_plugins: '%s' unloaded with %s, ptr=%p",
              cur->name, (sts==STS_SUCCESS)?"success":"failure", cur);
 
@@ -217,10 +218,9 @@ int unload_plugins(void) {
          ERROR("lt_dlclose() failed for plugin %s", cur->name);
       }
 
-      /* deallocate plugins list item */
+      /* NOTE: cur->name and cur->desc must be cleaned up by the plugin! */
-      if (cur->name) {free(cur->name); cur->name=NULL;}
-      if (cur->desc) {free(cur->desc); cur->desc=NULL;}
 
+      /* deallocate plugins list item */
       if (last) last->next=NULL;
       free(cur);
 

src/plugins.h

@@ -78,4 +78,4 @@ typedef struct {
 */
 int  plugin_init(plugin_def_t *plugin_def);
 int  plugin_process(int stage, sip_ticket_t *ticket);
-int  plugin_end(void);
+int  plugin_end(plugin_def_t *plugin_def);