External MWI core support.
[asterisk/asterisk.git] / include / asterisk / res_mwi_external.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Richard Mudgett <rmudgett@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \brief Core external MWI support.
22  *
23  * \author Richard Mudgett <rmudgett@digium.com>
24  *
25  * See Also:
26  * \arg \ref AstCREDITS
27  */
28
29 #ifndef _ASTERISK_RES_MWI_EXTERNAL_H
30 #define _ASTERISK_RES_MWI_EXTERNAL_H
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C"
34 {
35 #endif
36
37 /* ------------------------------------------------------------------- */
38
39 /*!
40  * \brief Increase the external MWI resource module reference count.
41  * \since 12.1.0
42  *
43  * \return Nothing
44  */
45 void ast_mwi_external_ref(void);
46
47 /*!
48  * \brief Decrease the external MWI resource module reference count.
49  * \since 12.1.0
50  *
51  * \return Nothing
52  */
53 void ast_mwi_external_unref(void);
54
55 struct ast_mwi_mailbox_object;
56
57 /*! \brief Convienience unref function for mailbox object. */
58 #define ast_mwi_mailbox_unref(mailbox) ao2_ref((struct ast_mwi_mailbox_object *) mailbox, -1)
59
60 /*!
61  * \brief Allocate an external MWI object.
62  * \since 12.1.0
63  *
64  * \param mailbox_id Name of mailbox.
65  *
66  * \retval object on success.  The object is an ao2 object.
67  * \retval NULL on error.
68  */
69 struct ast_mwi_mailbox_object *ast_mwi_mailbox_alloc(const char *mailbox_id);
70
71 /*!
72  * \brief Get mailbox id.
73  * \since 12.1.0
74  *
75  * \param mailbox Object to get id.
76  *
77  * \return mailbox_id of the object.
78  *
79  * \note This should never return NULL unless there is a bug in sorcery.
80  */
81 const char *ast_mwi_mailbox_get_id(const struct ast_mwi_mailbox_object *mailbox);
82
83 /*!
84  * \brief Get the number of new messages.
85  * \since 12.1.0
86  *
87  * \param mailbox Object to get number of new messages.
88  *
89  * \return Number of new messages.
90  */
91 unsigned int ast_mwi_mailbox_get_msgs_new(const struct ast_mwi_mailbox_object *mailbox);
92
93 /*!
94  * \brief Get the number of old messages.
95  * \since 12.1.0
96  *
97  * \param mailbox Object to get number of old messages.
98  *
99  * \return Number of old messages.
100  */
101 unsigned int ast_mwi_mailbox_get_msgs_old(const struct ast_mwi_mailbox_object *mailbox);
102
103 /*!
104  * \brief Copy the external MWI counts object.
105  * \since 12.1.0
106  *
107  * \param mailbox What to copy.
108  *
109  * \retval copy on success.  The object is an ao2 object.
110  * \retval NULL on error.
111  */
112 struct ast_mwi_mailbox_object *ast_mwi_mailbox_copy(const struct ast_mwi_mailbox_object *mailbox);
113
114 /*!
115  * \brief Set the number of new messages.
116  * \since 12.1.0
117  *
118  * \param mailbox Object to set number of new messages.
119  * \param num_msgs Number of messages to set.
120  *
121  * \return Nothing
122  */
123 void ast_mwi_mailbox_set_msgs_new(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
124
125 /*!
126  * \brief Set the number of old messages.
127  * \since 12.1.0
128  *
129  * \param mailbox Object to set number of old messages.
130  * \param num_msgs Number of messages to set.
131  *
132  * \return Nothing
133  */
134 void ast_mwi_mailbox_set_msgs_old(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
135
136 /*!
137  * \brief Update the external MWI counts with the given object.
138  * \since 12.1.0
139  *
140  * \param mailbox What to update.
141  *
142  * \retval 0 on success.
143  * \retval -1 on error.
144  */
145 int ast_mwi_mailbox_update(struct ast_mwi_mailbox_object *mailbox);
146
147 /*!
148  * \brief Delete matching external MWI object.
149  * \since 12.1.0
150  *
151  * \param mailbox_id Name of mailbox to delete.
152  *
153  * \retval 0 on success.
154  * \retval -1 on error.
155  */
156 int ast_mwi_mailbox_delete(const char *mailbox_id);
157
158 /*!
159  * \brief Delete all external MWI objects selected by the regular expression.
160  * \since 12.1.0
161  *
162  * \param regex Regular expression in extended syntax.  (NULL is same as "")
163  *
164  * \note The provided regex is treated as extended case sensitive.
165  *
166  * \retval 0 on success.
167  * \retval -1 on error.
168  */
169 int ast_mwi_mailbox_delete_by_regex(const char *regex);
170
171 /*!
172  * \brief Delete all external MWI objects.
173  * \since 12.1.0
174  *
175  * \retval 0 on success.
176  * \retval -1 on error.
177  */
178 int ast_mwi_mailbox_delete_all(void);
179
180 /*!
181  * \brief Get matching external MWI object.
182  * \since 12.1.0
183  *
184  * \param mailbox_id Name of mailbox to retrieve.
185  *
186  * \retval requested mailbox on success.  The object is an ao2 object.
187  * \retval NULL on error or no mailbox.
188  *
189  * \note The object must be treated as read-only.
190  */
191 const struct ast_mwi_mailbox_object *ast_mwi_mailbox_get(const char *mailbox_id);
192
193 /*!
194  * \brief Get all external MWI objects selected by the regular expression.
195  * \since 12.1.0
196  *
197  * \param regex Regular expression in extended syntax.  (NULL is same as "")
198  *
199  * \note The provided regex is treated as extended case sensitive.
200  *
201  * \retval container of struct ast_mwi_mailbox_object on success.
202  * \retval NULL on error.
203  *
204  * \note The objects in the container must be treated as read-only.
205  */
206 struct ao2_container *ast_mwi_mailbox_get_by_regex(const char *regex);
207
208 /*!
209  * \brief Get all external MWI objects.
210  * \since 12.1.0
211  *
212  * \retval container of struct ast_mwi_mailbox_object on success.
213  * \retval NULL on error.
214  *
215  * \note The objects in the container must be treated as read-only.
216  */
217 struct ao2_container *ast_mwi_mailbox_get_all(void);
218
219
220 /* ------------------------------------------------------------------- */
221
222 #if defined(__cplusplus) || defined(c_plusplus)
223 }
224 #endif
225
226 #endif  /* _ASTERISK_RES_MWI_EXTERNAL_H */