[asterisk-commits] branch file/datastores r10987 - /team/file/datastores/doc/datastores.txt

[asterisk-commits at lists.digium.com]

Author: file
Date: Thu Feb 23 18:17:07 2006
New Revision: 10987

URL: http://svn.digium.com/view/asterisk?rev=10987&view=rev
Log:
Add documentation for data stores like I promised I would

Added:
    team/file/datastores/doc/datastores.txt   (with props)

Added: team/file/datastores/doc/datastores.txt
URL: http://svn.digium.com/view/asterisk/team/file/datastores/doc/datastores.txt?rev=10987&view=auto
==============================================================================
--- team/file/datastores/doc/datastores.txt (added)
+++ team/file/datastores/doc/datastores.txt Thu Feb 23 18:17:07 2006
@@ -1,0 +1,57 @@
+Asterisk Channel Data Stores
+============================
+
+* What is a data store?
+
+A data store is a way of storing complex data (such as a structure) on a channel
+so it can be retrieved at a later time by another application, or the same application.
+
+If the data store is not freed by said application though, a callback to a destroy function
+occurs which frees the memory used by the data in the data store so no memory loss occurs.
+
+* How do you create a data store?
+
+1. Use ast_channel_datastore_alloc function to return a pre-allocated structure
+   Ex: datastore = ast_channel_datastore_alloc("type", "uid");
+   This function takes two arguments: (type, uid)
+2. Attach data and destroy callback to pre-allocated structure.
+   Ex: datastore->data = mysillydata;
+       datastore->destroy = callback_destroy;
+3. Add datastore to the channel
+   Ex: ast_channel_datastore_add(chan, datastore);
+   This function takes two arguments: (pointer to channel, pointer to data store)
+
+Full Example:
+
+void callback_destroy(void *data)
+{
+	free(data);
+}
+
+struct ast_datastore *datastore = NULL;
+datastore = ast_channel_datastore_alloc("test", NULL);
+datastore->data = mysillydata;
+datastore->destroy = callback_destroy;
+ast_channel_datastore_add(chan, datastore);
+
+* How do you remove a data store?
+
+1. Find the data store
+   Ex: datastore = ast_channel_datastore_find(chan, "test", NULL);
+   This function takes three arguments: (pointer to channel, type, uid)
+2. Remove the data store from the channel
+   Ex: ast_channel_datastore_remove(chan, datastore);
+   This function takes two arguments: (pointer to channel, pointer to data store)
+3. If we want to now, free the memory or do stuff to the data on the data store
+   If we do then we will want to unset the data and callback
+   Ex: datastore->data = NULL;
+       datastore->destroy = NULL;
+4. Free the data store
+   Ex: ast_channel_datastore_free(datastore);
+   This function takes one argument: (pointer to data store)
+
+* How do you find a data store?
+
+1. Find the data store
+   Ex: datastore = ast_channel_datastore_find(chan, "test", NULL);
+   This function takes three arguments: (pointer to channel, type, uid)

Propchange: team/file/datastores/doc/datastores.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/file/datastores/doc/datastores.txt
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/file/datastores/doc/datastores.txt
------------------------------------------------------------------------------
    svn:mime-type = text/plain