dfeef513cf54d2dd0e48a2c99a1c66a1f898b5e6
[asterisk/asterisk.git] / include / asterisk / ari.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012 - 2013, Digium, Inc.
5  *
6  * David M. Lee, II <dlee@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_ARI_H
20 #define _ASTERISK_ARI_H
21
22 /*! \file
23  *
24  * \brief Asterisk RESTful API hooks.
25  *
26  * This header file is used mostly as glue code between generated declarations
27  * and res_ari.c.
28  *
29  * \author David M. Lee, II <dlee@digium.com>
30  */
31
32 #include "asterisk/http.h"
33 #include "asterisk/json.h"
34
35 /* Forward-declare websocket structs. This avoids including http_websocket.h,
36  * which causes optional_api stuff to happen, which makes optional_api more
37  * difficult to debug. */
38
39 struct ast_websocket_server;
40
41 struct ast_websocket;
42
43 /*!
44  * \brief Configured encoding format for JSON output.
45  * \return JSON output encoding (compact, pretty, etc.)
46  */
47 enum ast_json_encoding_format ast_ari_json_format(void);
48
49 struct ast_ari_response;
50
51 /*!
52  * \brief Callback type for RESTful method handlers.
53  * \param get_params GET parameters from the HTTP request.
54  * \param path_vars Path variables from any wildcard path segments.
55  * \param headers HTTP headers from the HTTP requiest.
56  * \param[out] response The RESTful response.
57  */
58 typedef void (*stasis_rest_callback)(struct ast_variable *get_params,
59                                      struct ast_variable *path_vars,
60                                      struct ast_variable *headers,
61                                      struct ast_ari_response *response);
62
63 /*!
64  * \brief Handler for a single RESTful path segment.
65  */
66 struct stasis_rest_handlers {
67         /*! Path segement to handle */
68         const char *path_segment;
69         /*! If true (non-zero), path_segment is a wildcard, and will match all
70          * values.
71          *
72          * Value of the segement will be passed into the \a path_vars parameter
73          * of the callback.
74          */
75         int is_wildcard;
76         /*! Callbacks for all handled HTTP methods. */
77         stasis_rest_callback callbacks[AST_HTTP_MAX_METHOD];
78         /*! WebSocket server for handling WebSocket upgrades. */
79         struct ast_websocket_server *ws_server;
80         /*! Number of children in the children array */
81         size_t num_children;
82         /*! Handlers for sub-paths */
83         struct stasis_rest_handlers *children[];
84 };
85
86 /*!
87  * Response type for RESTful requests
88  */
89 struct ast_ari_response {
90         /*! Response message */
91         struct ast_json *message;
92         /*! \r\n seperated response headers */
93         struct ast_str *headers;
94         /*! HTTP response code.
95          * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
96         int response_code;
97         /*! Corresponding text for the response code */
98         const char *response_text; /* Shouldn't http.c handle this? */
99         /*! Flag to indicate that no further response is needed */
100         int no_response:1;
101 };
102
103 /*!
104  * Add a resource for REST handling.
105  * \param handler Handler to add.
106  * \return 0 on success.
107  * \return non-zero on failure.
108  */
109 int ast_ari_add_handler(struct stasis_rest_handlers *handler);
110
111 /*!
112  * Remove a resource for REST handling.
113  * \param handler Handler to add.
114  * \return 0 on success.
115  * \return non-zero on failure.
116  */
117 int ast_ari_remove_handler(struct stasis_rest_handlers *handler);
118
119 /*!
120  * \internal
121  * \brief Stasis RESTful invocation handler.
122  *
123  * Only call from res_ari and test_ari. Only public to allow
124  * for unit testing.
125  *
126  * \param ser TCP/TLS connection.
127  * \param uri HTTP URI, relative to the API path.
128  * \param method HTTP method.
129  * \param get_params HTTP \c GET parameters.
130  * \param headers HTTP headers.
131  * \param[out] response RESTful HTTP response.
132  */
133 void ast_ari_invoke(struct ast_tcptls_session_instance *ser,
134         const char *uri, enum ast_http_method method,
135         struct ast_variable *get_params, struct ast_variable *headers,
136         struct ast_ari_response *response);
137
138 /*!
139  * \internal
140  * \brief Service function for API declarations.
141  *
142  * Only call from res_ari and test_ari. Only public to allow
143  * for unit testing.
144  *
145  * \param uri Requested URI, relative to the docs path.
146  * \param headers HTTP headers.
147  * \param[out] response RESTful HTTP response.
148  */
149 void ast_ari_get_docs(const char *uri, struct ast_variable *headers, struct ast_ari_response *response);
150
151 /*! \brief Abstraction for reading/writing JSON to a WebSocket */
152 struct ast_ari_websocket_session;
153
154 /*!
155  * \brief Create an ARI WebSocket session.
156  *
157  * If \c NULL is given for the validator function, no validation will be
158  * performed.
159  *
160  * \param ws_session Underlying WebSocket session.
161  * \param validator Function to validate outgoing messages.
162  * \return New ARI WebSocket session.
163  * \return \c NULL on error.
164  */
165 struct ast_ari_websocket_session *ast_ari_websocket_session_create(
166         struct ast_websocket *ws_session, int (*validator)(struct ast_json *));
167
168 /*!
169  * \brief Read a message from an ARI WebSocket.
170  *
171  * \param session Session to read from.
172  * \return Message received.
173  * \return \c NULL if WebSocket could not be read.
174  */
175 struct ast_json *ast_ari_websocket_session_read(
176         struct ast_ari_websocket_session *session);
177
178 /*!
179  * \brief Send a message to an ARI WebSocket.
180  *
181  * \param session Session to write to.
182  * \param message Message to send.
183  * \return 0 on success.
184  * \return Non-zero on error.
185  */
186 int ast_ari_websocket_session_write(struct ast_ari_websocket_session *session,
187         struct ast_json *message);
188
189 /*!
190  * \brief The stock message to return when out of memory.
191  *
192  * The refcount is NOT bumped on this object, so ast_json_ref() if you want to
193  * keep the reference.
194  *
195  * \return JSON message specifying an out-of-memory error.
196  */
197 struct ast_json *ast_ari_oom_json(void);
198
199 /*!
200  * \brief Fill in an error \a ast_ari_response.
201  * \param response Response to fill in.
202  * \param response_code HTTP response code.
203  * \param response_text Text corresponding to the HTTP response code.
204  * \param message_fmt Error message format string.
205  */
206 void ast_ari_response_error(struct ast_ari_response *response,
207                                 int response_code,
208                                 const char *response_text,
209                                 const char *message_fmt, ...)
210 __attribute__((format(printf, 4, 5)));
211
212 /*!
213  * \brief Fill in an \c OK (200) \a ast_ari_response.
214  * \param response Response to fill in.
215  * \param message JSON response.  This reference is stolen, so just \ref
216  *                ast_json_incref if you need to keep a reference to it.
217  */
218 void ast_ari_response_ok(struct ast_ari_response *response,
219                              struct ast_json *message);
220
221 /*!
222  * \brief Fill in a <tt>No Content</tt> (204) \a ast_ari_response.
223  */
224 void ast_ari_response_no_content(struct ast_ari_response *response);
225
226 /*!
227  * \brief Fill in a <tt>Created</tt> (201) \a ast_ari_response.
228  */
229 void ast_ari_response_created(struct ast_ari_response *response,
230         const char *url, struct ast_json *message);
231
232 /*!
233  * \brief Fill in \a response with a 500 message for allocation failures.
234  * \param response Response to fill in.
235  */
236 void ast_ari_response_alloc_failed(struct ast_ari_response *response);
237
238 #endif /* _ASTERISK_ARI_H */