ARI: Add mailboxes resource for controlling and polling external MWI
[asterisk/asterisk.git] / include / asterisk / stasis_app_mailbox.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2014, Digium, Inc.
5  *
6  * Jonathan Rose <jrose@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 #ifndef _ASTERISK_STASIS_APP_MAILBOX_H
20 #define _ASTERISK_STASIS_APP_MAILBOX_H
21
22 /*! \file
23  *
24  * \brief Stasis Application Mailbox API. See \ref res_stasis "Stasis
25  * Application API" for detailed documentation.
26  *
27  * \author Jonathan Rose <kharwell@digium.com>
28  * \since 12
29  */
30
31 #include "asterisk/app.h"
32 #include "asterisk/stasis_app.h"
33
34 /*! @{ */
35
36 /*! Stasis mailbox operation result codes */
37 enum stasis_mailbox_result {
38         /*! Mailbox operation completed successfully */
39         STASIS_MAILBOX_OK,
40         /*! Mailbox of the requested name does not exist */
41         STASIS_MAILBOX_MISSING,
42         /*! Mailbox operation failed internally */
43         STASIS_MAILBOX_ERROR,
44 };
45
46 /*!
47  * \brief Convert mailbox to JSON
48  *
49  * \param name the name of the mailbox
50  * \param json If the query is successful, this pointer at this address will
51  *        be set to the JSON representation of the mailbox
52  *
53  * \return stasis mailbox result code indicating success or failure and cause
54  * \return \c NULL on error.
55  */
56 enum stasis_mailbox_result stasis_app_mailbox_to_json(const char *name, struct ast_json **json);
57
58 /*!
59  * brief Convert mailboxes to json array
60  *
61  * \return JSON representation of the mailboxes
62  * \return \c NULL on error.
63  */
64 struct ast_json *stasis_app_mailboxes_to_json(void);
65
66 /*!
67  * \brief Changes the state of a mailbox.
68  *
69  * \note Implicitly creates the mailbox.
70  *
71  * \param name The name of the ARI controlled mailbox
72  * \param old_messages count of old (read) messages in the mailbox
73  * \param new_messages count of new (unread) messages in the mailbox
74  *
75  * \return 0 if successful
76  * \return -1 on internal error.
77  */
78 int stasis_app_mailbox_update(
79         const char *name, int old_messages, int new_messages);
80
81 /*!
82  * \brief Delete a mailbox controlled by ARI.
83  *
84  * \param name the name of the ARI controlled mailbox
85  *
86  * \return a stasis mailbox application result
87  */
88 enum stasis_mailbox_result stasis_app_mailbox_delete(
89         const char *name);
90
91 #endif /* _ASTERISK_STASIS_APP_MAILBOX_H */