doc/datastores.txt

   1 Asterisk Channel Data Stores
   2 ============================
   3
   4 * What is a data store?
   5
   6 A data store is a way of storing complex data (such as a structure) on a channel
   7 so it can be retrieved at a later time by another application, or the same application.
   8
   9 If the data store is not freed by said application though, a callback to a destroy function
  10 occurs which frees the memory used by the data in the data store so no memory loss occurs.
  11
  12 * A datastore info structure
  13 static const struct example_datastore {
  14        .type = "example",
  15        .destroy = callback_destroy
  16 };
  17
  18 This is a needed structure that contains information about a datastore, it's used by many API calls.
  19
  20 * How do you create a data store?
  21
  22 1. Use ast_channel_datastore_alloc function to return a pre-allocated structure
  23    Ex: datastore = ast_channel_datastore_alloc(&example_datastore, "uid");
  24    This function takes two arguments: (datastore info structure, uid)
  25 2. Attach data to pre-allocated structure.
  26    Ex: datastore->data = mysillydata;
  27 3. Add datastore to the channel
  28    Ex: ast_channel_datastore_add(chan, datastore);
  29    This function takes two arguments: (pointer to channel, pointer to data store)
  30
  31 Full Example:
  32
  33 void callback_destroy(void *data)
  34 {
  35         ast_free(data);
  36 }
  37
  38 struct ast_datastore *datastore = NULL;
  39 datastore = ast_channel_datastore_alloc(&example_datastore, NULL);
  40 datastore->data = mysillydata;
  41 ast_channel_datastore_add(chan, datastore);
  42
  43 NOTE: Because you're passing a pointer to a function in your module, you'll want to include
  44 this in your use count. When allocated increment, when destroyed decrement.
  45
  46 * How do you remove a data store?
  47
  48 1. Find the data store
  49    Ex: datastore = ast_channel_datastore_find(chan, &example_datastore, NULL);
  50    This function takes three arguments: (pointer to channel, datastore info structure, uid)
  51 2. Remove the data store from the channel
  52    Ex: ast_channel_datastore_remove(chan, datastore);
  53    This function takes two arguments: (pointer to channel, pointer to data store)
  54 3. If we want to now do stuff to the data on the data store
  55 4. Free the data store (this will call the destroy call back)
  56    Ex: ast_channel_datastore_free(datastore);
  57    This function takes one argument: (pointer to data store)
  58
  59 * How do you find a data store?
  60
  61 1. Find the data store
  62    Ex: datastore = ast_channel_datastore_find(chan, &example_datastore, NULL);
  63    This function takes three arguments: (pointer to channel, datastore info structure, uid)