[asterisk-commits] dvossel: branch dvossel/awesomehooks r287382 - /team/dvossel/awesomehooks/inc...

[SVN commits to the Asterisk project]

Author: dvossel
Date: Fri Sep 17 10:52:44 2010
New Revision: 287382

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=287382
Log:
awesomehook API documentation and example usage

Modified:
    team/dvossel/awesomehooks/include/asterisk/awesomehook.h

Modified: team/dvossel/awesomehooks/include/asterisk/awesomehook.h
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/awesomehooks/include/asterisk/awesomehook.h?view=diff&rev=287382&r1=287381&r2=287382
==============================================================================
--- team/dvossel/awesomehooks/include/asterisk/awesomehook.h (original)
+++ team/dvossel/awesomehooks/include/asterisk/awesomehook.h Fri Sep 17 10:52:44 2010
@@ -19,6 +19,103 @@
 /*! \file
  * \brief AwesomeHook Architecture
  */
+
+/*! 
+
+\page AstAwesomeHookAPI Asterisk AwesomeHook API
+
+\section AwesomeHookFunctionality How AwesomeHooks Work
+    AwesomeHooks work by intercepting all frames being written and read off
+    a channel and allowing those frames to be viewed and manipulated within a
+    call back function. 
+    
+\section AwesomeHookAPIUsage How to Use an AwesomeHook
+    Attaching and detaching an AwesomeHook to a channel is very simple.  There are only
+    two functions involved, ast_awesome_attach() which will return an id representing
+    the new AwesomeHook on the channel, and ast_awesomehook_detach() which signals the
+    AwesomeHook for detachment and destruction. Below is detailed information each of these
+    functions and their usage.
+
+\code
+    int id = ast_awesome_attach(channel, event_callback, destroy_callback, datastore);
+\endcode
+
+    The ast_awesomehook_attach() function creates and attaches a new AwesomeHook onto
+    a channel. Once attached to the channel, the AwesomeHook will call the event_callback
+    function each time a frame is written or read on the channel.  A custom datastore
+    pointer can be provided to this function to store on the AwesomeHook as well.  This
+    pointer can be used to keep up with any statefull information associated with the AwesomeHook
+    and is provided during the event_callback function.  The destroy_callback function is optional.
+    This function exists so any custom data stored on the AwesomeHook can be destroyed before
+    the Awesomehook if destroyed.
+
+\code
+    ast_awesomehook_detach(channel, id);
+\endcode
+
+    The ast_awesomehook_detach() function signals the AwesomeHook represented by an id to
+    be detached and destroyed on a channel.  Since it is possible this function may be called
+    during the AwesomeHook's event callback, it is impossible to synchronously detach the
+    AwesomeHook from the channel during this function call.  It is guaranteed that the next
+    event proceeding the ast_awesomehook_detach() will be of type AST_AWESOMEHOOK_EVENT_DETACH,
+    and that after that event occurs no other event will ever be issued for that AwesomeHook.
+    Once the AwesomeHook is destroyed, the destroy callback function will be called if it was
+    provided.
+
+
+\section AwesomeHookAPICodeExample AwesomeHook Example Code
+    The example code below attaches an AwesomeHook on a channel, and then detachs it when
+    the first ast_frame is read or written to the event callback function.  The Awesomehook's id
+    is stored on the AwesomeHook's data pointer so it can be detached within the callback.
+
+\code
+    static void destroy_cb(void *datastore) {
+	    ast_free(datastore);
+    }
+
+    static struct ast_frame *event_cb(struct ast_channel *chan,
+            struct ast_frame *frame,
+            enum ast_awesomehook_event event,
+            void *datastore) {
+   
+        int *id = datastore;
+
+        if (!frame) {
+            return frame;
+        }
+
+        if (event == AST_AWESOMEHOOK_EVENT_WRITE) {
+            ast_log(LOG_NOTICE, "YAY we received a frame in the write direction, Type: %d\n", frame->frametype)
+            ast_awesomehook_detach(chan, id);
+        } else if (event == AST_AWESOMEHOOK_EVENT_READ) {
+            ast_log(LOG_NOTICE, "YAY we received a frame in the read direction: Type: %d\n", frame->frametype);
+            ast_awesomehook_detach(chan, id);
+        }
+
+        return frame;
+    {
+
+    int some_function() {
+        int *id = ast_calloc(1, sizeof(int));
+
+        if (!id) {
+            return -1;
+        }
+
+        ast_channel_lock(chan);
+        *id = ast_awesomehook_attach(chan, event_cb, destroy_cb, id);
+        ast_channel_unlock(chan);
+
+        if (*id < 0) {
+            // awesomehook attach failed, free data
+            ast_free(id);
+            return -1;
+        }
+        return 0;
+    }
+\endcode
+*/
+
 
 #ifndef _AST_AWESOMEHOOK_H_
 #define _AST_AWESOMEHOOK_H_