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

[SVN commits to the Asterisk project]

Author: dvossel
Date: Tue Sep 14 16:56:25 2010
New Revision: 286833

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=286833
Log:
awesomehook.h file

Added:
    team/dvossel/awesomehooks/include/asterisk/awesomehook.h   (with props)

Added: team/dvossel/awesomehooks/include/asterisk/awesomehook.h
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/awesomehooks/include/asterisk/awesomehook.h?view=auto&rev=286833
==============================================================================
--- team/dvossel/awesomehooks/include/asterisk/awesomehook.h (added)
+++ team/dvossel/awesomehooks/include/asterisk/awesomehook.h Tue Sep 14 16:56:25 2010
@@ -1,0 +1,149 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2010, Digium, Inc.
+ *
+ * David Vossel <dvossel at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ * \brief AwesomeHook Architecture
+ */
+
+#ifndef _AST_AWESOMEHOOK_H_
+#define _AST_AWESOMEHOOK_H_
+
+enum ast_awesomehook_status {
+	AST_AWESOMEHOOK_STATUS_INIT,
+	AST_AWESOMEHOOK_STATUS_ATTACHED,
+	AST_AWESOMEHOOK_STATUS_DETACHED
+};
+
+enum ast_awesomehook_event {
+	AST_AWESOMEHOOK_EVENT_READ, /*!< frame is intercepted in the read direction on the channel. */
+	AST_AWESOMEHOOK_EVENT_WRITE, /*!< frame is intercepted on the write direction on the channel. */
+	AST_AWESOMEHOOK_EVENT_ATTACHED, /*!< the awesomehook is attached and running on the channel. */
+	AST_AWESOMEHOOK_EVENT_DETACHED /*!< the awesomehook is detached from the channel. */
+};
+
+struct ast_awesomehook;
+
+/*!
+ * \brief This callback is called every time an event occurs on the awesomehook.
+ *
+ * \description Two events are guaranteed to occur once the ast_awesomehook_attach()
+ * function is called. These events are AST_AWESOMEHOOK_EVENT_ATTACHED, which occurs
+ * immediately after the awesomehook is attached to a channel, and
+ * AST_AWESOMEHOOK_EVENT_DETACHED, which occurs right after the awesomehook is 
+ * detached.
+ */
+typedef int (*ast_awesomehook_event_callback)(struct ast_awesomehook *awesomehook,
+	struct ast_channel *chan,
+	struct ast_frame *frame,
+	enum ast_awesomehook_event event);
+
+/*!
+ * \brief This callback is called immediately before the awesomehook is destroyed.
+ * \note  This function should be used to clean up any pointers pointing to the
+ * awesomehook structure as the awesomehook will be freed immediately afterwards.
+ */
+typedef int (*ast_awesomehook_destroy_callback)(struct ast_awesomehook *awesomehook);
+
+struct ast_awesomehook {
+	ast_mutex_t lock;
+	/*! Current awesomehook status. */
+	enum ast_awesomehook_status status;
+	/*! The last event type that went to the awesomehook event callback */
+	enum ast_awesomehook_event last_event;
+	/*! This pointer holds any stateful data an application wishes to store. */
+	void *datastore;
+	/*! This pointer to ast_channel the awesomehook is attached to. */
+	struct ast_channel chan;
+	/*! Pointer to the registered event callback function. */
+	ast_awesomehook_event_callback event_cb;
+	/*! Pointer to the registered destruction callback function. */
+	ast_awesomehook_destroy_callback destroy_cb;
+};
+
+/*!
+ * \brief Initialize a new awesomehook structure.
+ *
+ * \param event_cb represents the function that will be called everytime an
+ * event occurs on the awesomehook.
+ * \param destroy_cb is option.  This function is called immediately before the
+ * awesomehook is destroyed so cleanup can occur.
+ */
+int ast_awesomehook_alloc(ast_awesomehook_event_callback event_cb,
+	ast_awesomehook_destroy_callback destroy_cb);
+
+/*!
+ * \brief Attach an awesomehook onto a channel for frame interception.
+ *
+ * \param ast_channel to attached the awesomehook onto.
+ * \retval 0 success, -1 failure
+ */
+int ast_awesomehook_attach(struct ast_channel *chan);
+
+/*!
+ * \brief Mark awesomehook for channel detachment and destruction.
+ *
+ * \note This function is marks the awesomehook for removal and destruction
+ * by the channel thread.  Once the actual destruction takes place the
+ * awesomehook's destroy callback function will be called allowing for
+ * any necessary cleanup to occur.
+ *
+ * \note After this function is used on a awesomehook, that awesomehook
+ * is effectively done.  It can never be re-attached to another channel.
+ *
+ * \param awesomehook to mark for detachment.
+ * \retval 0 success, -1 failure
+ */
+int ast_awesomehook_signal_cleanup(struct ast_awesomehook *awesomehook);
+
+/*!
+ * \brief free an awesomehook structure
+ *
+ * \note XXX READ THIS! This function should only be used by the
+ * Channel API after a awesomehook is detached from a channel. Any
+ * application using awesomehooks on a channel should use the
+ * ast_awesomehook_signal_cleanup() function to remove and free the
+ * awesomehook.
+ * 
+ * \note This function invokes the awesomehook's destruction callback before
+ * freeing it.
+ *
+ * \param awesomehook to mark for detachment.
+ * \retval 0 success, -1 failure
+ */
+int ast_awesomehook_destroy(struct ast_awesomehook);
+
+/*!
+ * \brief Return the status of an awesomehook.
+ */
+enum ast_awesomehook_status ast_awesomehook_get_status(struct ast_awesomehook *awesomehook);
+
+/*!
+ * \brief Set the awesomehook's custom data storage pointer.
+ *
+ * \note A custom data pointer can be stored on an awesomehook.  This allows
+ * for any stateful data the event_callback may need to be sorted directly on
+ * the awesomehook.
+ */
+int ast_awesomehook_set_datastore(struct ast_awesomehook *awesomehook, void *data);
+
+/*!
+ * \brief Return the awesomehook's custom data storage pointer.
+ */
+void *ast_awesomehook_get_datastore(struct ast_awesomehook *awesomehook);
+
+#endif /* _AST_AWESOMEHOOK_H */

Propchange: team/dvossel/awesomehooks/include/asterisk/awesomehook.h
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/dvossel/awesomehooks/include/asterisk/awesomehook.h
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/dvossel/awesomehooks/include/asterisk/awesomehook.h
------------------------------------------------------------------------------
    svn:mime-type = text/plain