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