mirror of
https://github.com/asterisk/asterisk.git
synced 2025-11-04 05:15:22 +00:00
69 lines
2.6 KiB
Plaintext
69 lines
2.6 KiB
Plaintext
|
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 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(&example_datastore, NULL);
|
||
|
|
datastore->data = mysillydata;
|
||
|
|
datastore->destroy = callback_destroy;
|
||
|
|
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, 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, &example_datastore, NULL);
|
||
|
|
This function takes three arguments: (pointer to channel, datastore info structure, uid)
|