Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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  void (*chan_fixup)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
49 
50  /*!
51  * \brief Fix up channel references on the channel being masqueraded into
52  *
53  * \arg data The datastore data
54  * \arg old_chan The old channel owning the datastore
55  * \arg new_chan The new channel owning the datastore
56  *
57  * This is the same as the above callback, except it is called for the channel
58  * being masqueraded into instead of the channel that is masquerading.
59  */
60  void (*chan_breakdown)(void *data, struct ast_channel *old_chan, struct ast_channel *new_chan);
61 };
62 
63 /*! \brief Structure for a data store object */
64 struct ast_datastore {
65  const char *uid; /*!< Unique data store identifier */
66  void *data; /*!< Contained data */
67  const struct ast_datastore_info *info; /*!< Data store type information */
68  struct ast_module *mod; /*!< Module referenced by this datastore */
69  unsigned int inheritance; /*!< Number of levels this item will continue to be inherited */
70  AST_LIST_ENTRY(ast_datastore) entry; /*!< Used for easy linking */
71 };
72 
73 /*!
74  * \brief Create a data store object
75  * \param[in] info information describing the data store object
76  * \param[in] uid unique identifer
77  * \param[in] mod The module to hold until this datastore is freed.
78  * \param file, line, function
79  * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc
80  */
82  const struct ast_datastore_info *info, const char *uid, struct ast_module *mod,
83  const char *file, int line, const char *function);
84 
85 #define ast_datastore_alloc(info, uid) \
86  __ast_datastore_alloc(info, uid, AST_MODULE_SELF, __FILE__, __LINE__, __PRETTY_FUNCTION__)
87 
88 /*!
89  * \brief Free a data store object
90  * \param[in] datastore datastore to free
91  * \version 1.6.1 moved here and renamed from ast_channel_datastore_free
92  */
93 int ast_datastore_free(struct ast_datastore *datastore);
94 
95 /*!
96  * \brief Allocate a specialized data stores container
97  *
98  * \return a container for storing data stores
99  *
100  * \since 14.0.0
101  */
102 struct ao2_container *ast_datastores_alloc(void);
103 
104 /*!
105  * \brief Add a data store to a container
106  *
107  * \param[in] datastores container to store datastore in
108  * \param[in] datastore datastore to add
109  *
110  * \retval 0 success
111  * \retval -1 failure
112  *
113  * \since 14.0.0
114  */
115 int ast_datastores_add(struct ao2_container *datastores, struct ast_datastore *datastore);
116 
117 /*!
118  * \brief Remove a data store from a container
119  *
120  * \param[in] datastores container to remove datastore from
121  * \param[in] name name of the data store to remove
122  *
123  * \since 14.0.0
124  */
125 void ast_datastores_remove(struct ao2_container *datastores, const char *name);
126 
127 /*!
128  * \brief Find a data store in a container
129  *
130  * \param[in] datastores container to find datastore in
131  * \param[in] name name of the data store to find
132  *
133  * \retval non-NULL success
134  * \retval NULL failure
135  *
136  * \since 14.0.0
137  */
138 struct ast_datastore *ast_datastores_find(struct ao2_container *datastores, const char *name);
139 
140 /*!
141  * \brief Allocate a datastore for use with the datastores container
142  *
143  * \param[in] info information about the datastore
144  * \param[in] uid unique identifier for the datastore
145  *
146  * \retval non-NULL success
147  * \retval NULL failure
148  *
149  * \since 14.0.0
150  */
151 struct ast_datastore *ast_datastores_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
152 
153 #if defined(__cplusplus) || defined(c_plusplus)
154 }
155 #endif
156 
157 #endif /* _ASTERISK_DATASTORE_H */
void ast_datastores_remove(struct ao2_container *datastores, const char *name)
Remove a data store from a container.
Definition: datastore.c:114
int ast_datastores_add(struct ao2_container *datastores, struct ast_datastore *datastore)
Add a data store to a container.
Definition: datastore.c:101
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 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
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
int ast_datastore_free(struct ast_datastore *datastore)
Free a data store object.
Definition: datastore.c:68
struct ao2_container * ast_datastores_alloc(void)
Allocate a specialized data stores container.
Definition: datastore.c:95
static const char name[]
Definition: format_mp3.c:68
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
def info(msg)
Generic container type.
Main Channel structure associated with a channel.
const char * data
Structure for a data store type.
Definition: datastore.h:31
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:48
const char * type
Definition: datastore.h:32
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:60
void(* destroy)(void *data)
Definition: datastore.h:34
Structure for a data store object.
Definition: datastore.h:64
const struct ast_datastore_info * info
Definition: datastore.h:67
const char * uid
Definition: datastore.h:65
void * data
Definition: datastore.h:66
struct ast_module * mod
Definition: datastore.h:68
unsigned int inheritance
Definition: datastore.h:69
struct ast_datastore::@242 entry