diff options
author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2009-01-16 15:51:43 +0000 |
---|---|---|
committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2009-01-16 15:51:43 +0000 |
commit | 52acc4c45786fc04da9536c2801eb2b483cc2009 (patch) | |
tree | 3e0b68760b7b6d49c72de4fd5b747ed4d5726ad3 /doc/datastores.txt | |
parent | 5d9d64e584ec5220835eb10a124b555d449fa3d3 (diff) | |
parent | caebf8461f9849f484eb5bbd649880e457c20e31 (diff) |
Creating tag for the release of asterisk-1.4.23-rc4
git-svn-id: http://svn.digium.com/svn/asterisk/tags/1.4.23-rc4@168755 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'doc/datastores.txt')
-rw-r--r-- | doc/datastores.txt | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/doc/datastores.txt b/doc/datastores.txt new file mode 100644 index 000000000..64b5d35cc --- /dev/null +++ b/doc/datastores.txt @@ -0,0 +1,63 @@ +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. + +* A datastore info structure +static const struct example_datastore { + .type = "example", + .destroy = callback_destroy +}; + +This is a needed structure that contains information about a datastore, it's used by many API calls. + +* 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(&example_datastore, "uid"); + This function takes two arguments: (datastore info structure, uid) +2. Attach data to pre-allocated structure. + Ex: datastore->data = mysillydata; +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) +{ + ast_free(data); +} + +struct ast_datastore *datastore = NULL; +datastore = ast_channel_datastore_alloc(&example_datastore, NULL); +datastore->data = mysillydata; +ast_channel_datastore_add(chan, datastore); + +NOTE: Because you're passing a pointer to a function in your module, you'll want to include +this in your use count. When allocated increment, when destroyed decrement. + +* How do you remove a data store? + +1. Find the data store + Ex: datastore = ast_channel_datastore_find(chan, &example_datastore, NULL); + This function takes three arguments: (pointer to channel, datastore info structure, 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 do stuff to the data on the data store +4. Free the data store (this will call the destroy call back) + 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, &example_datastore, NULL); + This function takes three arguments: (pointer to channel, datastore info structure, uid) |