Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
datastore.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007 - 2008, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16 
17 /*! \file
18  * \brief Asterisk datastore objects
19  */
20 
21 #ifndef _ASTERISK_DATASTORE_H
22 #define _ASTERISK_DATASTORE_H
23 
24 #if defined(__cplusplus) || defined(c_plusplus)
25 extern "C" {
26 #endif
27 
28 #include "asterisk/linkedlists.h"
29 
30 /*! \brief Structure for a data store type */
32  const char *type; /*!< Type of data store */
33  void *(*duplicate)(void *data); /*!< Duplicate item data (used for inheritance) */
34  void (*destroy)(void *data); /*!< Destroy function */
35 
36  /*!
37  * \brief Fix up channel references on the masquerading channel
38  *
39  * \arg data The datastore data
40  * \arg old_chan The old channel owning the datastore
41  * \arg new_chan The new channel owning the datastore
42  *
43  * This is exactly like the fixup callback of the channel technology interface.
44  * It allows a datastore to fix any pointers it saved to the owning channel
45  * in case that the owning channel has changed. Generally, this would happen
46  * when the datastore is set to be inherited, and a masquerade occurs.
47  *
48  * \return nothing.
49  */
50  void (*chan_fixup)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
51 
52  /*!
53  * \brief Fix up channel references on the channel being masqueraded into
54  *
55  * \arg data The datastore data
56  * \arg old_chan The old channel owning the datastore
57  * \arg new_chan The new channel owning the datastore
58  *
59  * This is the same as the above callback, except it is called for the channel
60  * being masqueraded into instead of the channel that is masquerading.
61  *
62  * \return nothing.
63  */
64  void (*chan_breakdown)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
65 };
66 
67 /*! \brief Structure for a data store object */
68 struct ast_datastore {
69  const char *uid; /*!< Unique data store identifier */
70  void *data; /*!< Contained data */
71  const struct ast_datastore_info *info; /*!< Data store type information */
72  struct ast_module *mod; /*!< Module referenced by this datastore */
73  unsigned int inheritance; /*!< Number of levels this item will continue to be inherited */
74  AST_LIST_ENTRY(ast_datastore) entry; /*!< Used for easy linking */
75 };
76 
77 /*!
78  * \brief Create a data store object
79  * \param[in] info information describing the data store object
80  * \param[in] uid unique identifer
81  * \param[in] mod The module to hold until this datastore is freed.
82  * \param file, line, function
83  * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc
84  */
86  const struct ast_datastore_info *info, const char *uid, struct ast_module *mod,
87  const char *file, int line, const char *function);
88 
89 #define ast_datastore_alloc(info, uid) \
90  __ast_datastore_alloc(info, uid, AST_MODULE_SELF, __FILE__, __LINE__, __PRETTY_FUNCTION__)
91 
92 /*!
93  * \brief Free a data store object
94  * \param[in] datastore datastore to free
95  * \version 1.6.1 moved here and renamed from ast_channel_datastore_free
96  */
97 int ast_datastore_free(struct ast_datastore *datastore);
98 
99 /*!
100  * \brief Allocate a specialized data stores container
101  *
102  * \return a container for storing data stores
103  *
104  * \since 14.0.0
105  */
106 struct ao2_container *ast_datastores_alloc(void);
107 
108 /*!
109  * \brief Add a data store to a container
110  *
111  * \param[in] datastores container to store datastore in
112  * \param[in] datastore datastore to add
113  *
114  * \retval 0 success
115  * \retval -1 failure
116  *
117  * \since 14.0.0
118  */
119 int ast_datastores_add(struct ao2_container *datastores, struct ast_datastore *datastore);
120 
121 /*!
122  * \brief Remove a data store from a container
123  *
124  * \param[in] datastores container to remove datastore from
125  * \param[in] name name of the data store to remove
126  *
127  * \since 14.0.0
128  */
129 void ast_datastores_remove(struct ao2_container *datastores, const char *name);
130 
131 /*!
132  * \brief Find a data store in a container
133  *
134  * \param[in] datastores container to find datastore in
135  * \param[in] name name of the data store to find
136  *
137  * \retval non-NULL success
138  * \retval NULL failure
139  *
140  * \since 14.0.0
141  */
142 struct ast_datastore *ast_datastores_find(struct ao2_container *datastores, const char *name);
143 
144 /*!
145  * \brief Allocate a datastore for use with the datastores container
146  *
147  * \param[in] info information about the datastore
148  * \param[in] uid unique identifier for the datastore
149  *
150  * \retval non-NULL success
151  * \retval NULL failure
152  *
153  * \since 14.0.0
154  */
155 struct ast_datastore *ast_datastores_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
156 
157 #if defined(__cplusplus) || defined(c_plusplus)
158 }
159 #endif
160 
161 #endif /* _ASTERISK_DATASTORE_H */
const char * type
Definition: datastore.h:32
struct ast_module::@386 entry
Main Channel structure associated with a channel.
static const char name[]
Definition: format_mp3.c:68
void(* chan_breakdown)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan)
Fix up channel references on the channel being masqueraded into.
Definition: datastore.h:64
int ast_datastores_add(struct ao2_container *datastores, struct ast_datastore *datastore)
Add a data store to a container.
Definition: datastore.c:101
Structure for a data store type.
Definition: datastore.h:31
Structure for a data store object.
Definition: datastore.h:68
const char * data
int ast_datastore_free(struct ast_datastore *datastore)
Free a data store object.
Definition: datastore.c:68
const char * uid
Definition: datastore.h:69
struct ast_datastore * ast_datastores_find(struct ao2_container *datastores, const char *name)
Find a data store in a container.
Definition: datastore.c:119
struct ao2_container * ast_datastores_alloc(void)
Allocate a specialized data stores container.
Definition: datastore.c:95
void(* chan_fixup)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan)
Fix up channel references on the masquerading channel.
Definition: datastore.h:50
struct ast_module * mod
Definition: datastore.h:72
const struct ast_datastore_info * info
Definition: datastore.h:71
void(* destroy)(void *data)
Definition: datastore.h:34
struct ast_datastore * ast_datastores_alloc_datastore(const struct ast_datastore_info *info, const char *uid)
Allocate a datastore for use with the datastores container.
Definition: datastore.c:138
A set of macros to manage forward-linked lists.
def info(msg)
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
void ast_datastores_remove(struct ao2_container *datastores, const char *name)
Remove a data store from a container.
Definition: datastore.c:114
unsigned int inheritance
Definition: datastore.h:73
struct ast_datastore * __ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid, struct ast_module *mod, const char *file, int line, const char *function)
Create a data store object.
Definition: datastore.c:39
void * data
Definition: datastore.h:70
Generic container type.