Asterisk - The Open Source Telephony Project  21.4.1
res_mwi_external.h
Go to the documentation of this file.
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 
40 
41 /*! \brief Convenience unref function for mailbox object. */
42 #define ast_mwi_mailbox_unref(mailbox) ao2_ref((struct ast_mwi_mailbox_object *) mailbox, -1)
43 
44 /*!
45  * \brief Allocate an external MWI object.
46  * \since 12.1.0
47  *
48  * \param mailbox_id Name of mailbox.
49  *
50  * \return object on success. The object is an ao2 object.
51  * \retval NULL on error.
52  */
53 struct ast_mwi_mailbox_object *ast_mwi_mailbox_alloc(const char *mailbox_id);
54 
55 /*!
56  * \brief Get mailbox id.
57  * \since 12.1.0
58  *
59  * \param mailbox Object to get id.
60  *
61  * \return mailbox_id of the object.
62  *
63  * \note This should never return NULL unless there is a bug in sorcery.
64  */
65 const char *ast_mwi_mailbox_get_id(const struct ast_mwi_mailbox_object *mailbox);
66 
67 /*!
68  * \brief Get the number of new messages.
69  * \since 12.1.0
70  *
71  * \param mailbox Object to get number of new messages.
72  *
73  * \return Number of new messages.
74  */
75 unsigned int ast_mwi_mailbox_get_msgs_new(const struct ast_mwi_mailbox_object *mailbox);
76 
77 /*!
78  * \brief Get the number of old messages.
79  * \since 12.1.0
80  *
81  * \param mailbox Object to get number of old messages.
82  *
83  * \return Number of old messages.
84  */
85 unsigned int ast_mwi_mailbox_get_msgs_old(const struct ast_mwi_mailbox_object *mailbox);
86 
87 /*!
88  * \brief Copy the external MWI counts object.
89  * \since 12.1.0
90  *
91  * \param mailbox What to copy.
92  *
93  * \return copy on success. The object is an ao2 object.
94  * \retval NULL on error.
95  */
97 
98 /*!
99  * \brief Set the number of new messages.
100  * \since 12.1.0
101  *
102  * \param mailbox Object to set number of new messages.
103  * \param num_msgs Number of messages to set.
104  */
105 void ast_mwi_mailbox_set_msgs_new(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
106 
107 /*!
108  * \brief Set the number of old messages.
109  * \since 12.1.0
110  *
111  * \param mailbox Object to set number of old messages.
112  * \param num_msgs Number of messages to set.
113  */
114 void ast_mwi_mailbox_set_msgs_old(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs);
115 
116 /*!
117  * \brief Update the external MWI counts with the given object.
118  * \since 12.1.0
119  *
120  * \param mailbox What to update.
121  *
122  * \retval 0 on success.
123  * \retval -1 on error.
124  */
126 
127 /*!
128  * \brief Delete matching external MWI object.
129  * \since 12.1.0
130  *
131  * \param mailbox_id Name of mailbox to delete.
132  *
133  * \retval 0 on success.
134  * \retval -1 on error.
135  */
136 int ast_mwi_mailbox_delete(const char *mailbox_id);
137 
138 /*!
139  * \brief Delete all external MWI objects selected by the regular expression.
140  * \since 12.1.0
141  *
142  * \param regex Regular expression in extended syntax. (NULL is same as "")
143  *
144  * \note The provided regex is treated as extended case sensitive.
145  *
146  * \retval 0 on success.
147  * \retval -1 on error.
148  */
149 int ast_mwi_mailbox_delete_by_regex(const char *regex);
150 
151 /*!
152  * \brief Delete all external MWI objects.
153  * \since 12.1.0
154  *
155  * \retval 0 on success.
156  * \retval -1 on error.
157  */
159 
160 /*!
161  * \brief Get matching external MWI object.
162  * \since 12.1.0
163  *
164  * \param mailbox_id Name of mailbox to retrieve.
165  *
166  * \return requested mailbox on success. The object is an ao2 object.
167  * \retval NULL on error or no mailbox.
168  *
169  * \note The object must be treated as read-only.
170  */
171 const struct ast_mwi_mailbox_object *ast_mwi_mailbox_get(const char *mailbox_id);
172 
173 /*!
174  * \brief Get all external MWI objects selected by the regular expression.
175  * \since 12.1.0
176  *
177  * \param regex Regular expression in extended syntax. (NULL is same as "")
178  *
179  * \note The provided regex is treated as extended case sensitive.
180  *
181  * \return container of struct ast_mwi_mailbox_object on success.
182  * \retval NULL on error.
183  *
184  * \note The objects in the container must be treated as read-only.
185  */
186 struct ao2_container *ast_mwi_mailbox_get_by_regex(const char *regex);
187 
188 /*!
189  * \brief Get all external MWI objects.
190  * \since 12.1.0
191  *
192  * \return container of struct ast_mwi_mailbox_object on success.
193  * \retval NULL on error.
194  *
195  * \note The objects in the container must be treated as read-only.
196  */
198 
199 
200 /* ------------------------------------------------------------------- */
201 
202 #if defined(__cplusplus) || defined(c_plusplus)
203 }
204 #endif
205 
206 #endif /* _ASTERISK_RES_MWI_EXTERNAL_H */
const char * ast_mwi_mailbox_get_id(const struct ast_mwi_mailbox_object *mailbox)
Get mailbox id.
struct ao2_container * ast_mwi_mailbox_get_all(void)
Get all external MWI objects.
struct ast_mwi_mailbox_object * ast_mwi_mailbox_alloc(const char *mailbox_id)
Allocate an external MWI object.
void ast_mwi_mailbox_set_msgs_new(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs)
Set the number of new messages.
int ast_mwi_mailbox_delete_all(void)
Delete all external MWI objects.
int ast_mwi_mailbox_update(struct ast_mwi_mailbox_object *mailbox)
Update the external MWI counts with the given object.
const struct ast_mwi_mailbox_object * ast_mwi_mailbox_get(const char *mailbox_id)
Get matching external MWI object.
int ast_mwi_mailbox_delete(const char *mailbox_id)
Delete matching external MWI object.
struct ast_mwi_mailbox_object * ast_mwi_mailbox_copy(const struct ast_mwi_mailbox_object *mailbox)
Copy the external MWI counts object.
unsigned int ast_mwi_mailbox_get_msgs_new(const struct ast_mwi_mailbox_object *mailbox)
Get the number of new messages.
void ast_mwi_mailbox_set_msgs_old(struct ast_mwi_mailbox_object *mailbox, unsigned int num_msgs)
Set the number of old messages.
Generic container type.
unsigned int ast_mwi_mailbox_get_msgs_old(const struct ast_mwi_mailbox_object *mailbox)
Get the number of old messages.
int ast_mwi_mailbox_delete_by_regex(const char *regex)
Delete all external MWI objects selected by the regular expression.
struct ao2_container * ast_mwi_mailbox_get_by_regex(const char *regex)
Get all external MWI objects selected by the regular expression.