Clean up doxygen warnings
[asterisk/asterisk.git] / include / asterisk / datastore.h
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 */
31 struct ast_datastore_info {
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
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 Structure for a data store object */
54 struct ast_datastore {
55         const char *uid;                        /*!< Unique data store identifier */
56         void *data;                             /*!< Contained data */
57         const struct ast_datastore_info *info;  /*!< Data store type information */
58         unsigned int inheritance;               /*!< Number of levels this item will continue to be inherited */
59         AST_LIST_ENTRY(ast_datastore) entry;    /*!< Used for easy linking */
60 };
61
62 /*!
63  * \brief Create a data store object
64  * \param[in] info information describing the data store object
65  * \param[in] uid unique identifer
66  * \param file, line, function
67  * \version 1.6.1 moved here and renamed from ast_channel_datastore_alloc
68  */
69 struct ast_datastore * attribute_malloc __ast_datastore_alloc(const struct ast_datastore_info *info, const char *uid,
70                                                               const char *file, int line, const char *function);
71
72 #define ast_datastore_alloc(info, uid) __ast_datastore_alloc(info, uid, __FILE__, __LINE__, __PRETTY_FUNCTION__)
73
74 /*!
75  * \brief Free a data store object
76  * \param[in] datastore datastore to free
77  * \version 1.6.1 moved here and renamed from ast_channel_datastore_free
78  */
79 int ast_datastore_free(struct ast_datastore *datastore);
80
81 #if defined(__cplusplus) || defined(c_plusplus)
82 }
83 #endif
84
85 #endif /* _ASTERISK_DATASTORE_H */