Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
ari.h
Go to the documentation of this file.
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
40
41struct ast_websocket;
42
43/*!
44 * \brief Configured encoding format for JSON output.
45 * \return JSON output encoding (compact, pretty, etc.)
46 */
48
49struct ast_ari_response;
50
51/*!
52 * \brief Callback type for RESTful method handlers.
53 * \param ser TCP/TLS session object
54 * \param get_params GET parameters from the HTTP request.
55 * \param path_vars Path variables from any wildcard path segments.
56 * \param headers HTTP headers from the HTTP requiest.
57 * \param body
58 * \param[out] response The RESTful response.
59 */
60typedef void (*stasis_rest_callback)(
62 struct ast_variable *get_params, struct ast_variable *path_vars,
63 struct ast_variable *headers, struct ast_json *body,
64 struct ast_ari_response *response);
65
66/*!
67 * \brief Handler for a single RESTful path segment.
68 */
70 /*! Path segement to handle */
71 const char *path_segment;
72 /*! If true (non-zero), path_segment is a wildcard, and will match all
73 * values.
74 *
75 * Value of the segement will be passed into the \a path_vars parameter
76 * of the callback.
77 */
79 /*! Callbacks for all handled HTTP methods. */
81 /*! WebSocket server for handling WebSocket upgrades. */
83 /*! Number of children in the children array */
85 /*! Handlers for sub-paths */
87};
88
89/*!
90 * Response type for RESTful requests
91 */
93 /*! Response message */
95 /*! \\r\\n seperated response headers */
97 /*! HTTP response code.
98 * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
100 /*! File descriptor for whatever file we want to respond with */
101 int fd;
102 /*! Corresponding text for the response code */
103 const char *response_text; /* Shouldn't http.c handle this? */
104 /*! Flag to indicate that no further response is needed */
105 unsigned int no_response:1;
106};
107
108/*!
109 * Add a resource for REST handling.
110 * \param handler Handler to add.
111 * \retval 0 on success.
112 * \retval non-zero on failure.
113 */
115
116/*!
117 * Remove a resource for REST handling.
118 * \param handler Handler to add.
119 * \retval 0 on success.
120 * \retval non-zero on failure.
121 */
123
124/*!
125 * \internal
126 * \brief Stasis RESTful invocation handler.
127 *
128 * Only call from res_ari and test_ari. Only public to allow
129 * for unit testing.
130 *
131 * \param ser TCP/TLS connection.
132 * \param uri HTTP URI, relative to the API path.
133 * \param method HTTP method.
134 * \param get_params HTTP \c GET parameters.
135 * \param headers HTTP headers.
136 * \param body
137 * \param[out] response RESTful HTTP response.
138 */
140 const char *uri, enum ast_http_method method,
141 struct ast_variable *get_params, struct ast_variable *headers,
142 struct ast_json *body, struct ast_ari_response *response);
143
144/*!
145 * \internal
146 * \brief Service function for API declarations.
147 *
148 * Only call from res_ari and test_ari. Only public to allow
149 * for unit testing.
150 *
151 * \param uri Requested URI, relative to the docs path.
152 * \param prefix prefix that prefixes all http requests
153 * \param headers HTTP headers.
154 * \param[out] response RESTful HTTP response.
155 */
156void ast_ari_get_docs(const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response);
157
158/*! \brief Abstraction for reading/writing JSON to a WebSocket */
160
161/*!
162 * \brief Create an ARI WebSocket session.
163 *
164 * If \c NULL is given for the validator function, no validation will be
165 * performed.
166 *
167 * \param ws_session Underlying WebSocket session.
168 * \param validator Function to validate outgoing messages.
169 * \return New ARI WebSocket session.
170 * \retval NULL on error.
171 */
173 struct ast_websocket *ws_session, int (*validator)(struct ast_json *));
174
175/*!
176 * \brief Read a message from an ARI WebSocket.
177 *
178 * \param session Session to read from.
179 * \return Message received.
180 * \retval NULL if WebSocket could not be read.
181 */
184
185/*!
186 * \brief Send a message to an ARI WebSocket.
187 *
188 * \param session Session to write to.
189 * \param message Message to send.
190 * \retval 0 on success.
191 * \retval Non-zero on error.
192 */
194 struct ast_json *message);
195
196/*!
197 * \brief Get the Session ID for an ARI WebSocket.
198 *
199 * \param session Session to query.
200 * \return Session ID.
201 * \retval NULL on error.
202 */
204 const struct ast_ari_websocket_session *session);
205
206/*!
207 * \brief Get the remote address from an ARI WebSocket.
208 *
209 * \param session Session to write to.
210 * \return ast_sockaddr (does not have to be freed)
211 */
214
215/*!
216 * \brief The stock message to return when out of memory.
217 *
218 * The refcount is NOT bumped on this object, so ast_json_ref() if you want to
219 * keep the reference.
220 *
221 * \return JSON message specifying an out-of-memory error.
222 */
223struct ast_json *ast_ari_oom_json(void);
224
225/*!
226 * \brief Fill in an error \a ast_ari_response.
227 * \param response Response to fill in.
228 * \param response_code HTTP response code.
229 * \param response_text Text corresponding to the HTTP response code.
230 * \param message_fmt Error message format string.
231 */
232void ast_ari_response_error(struct ast_ari_response *response,
233 int response_code,
234 const char *response_text,
235 const char *message_fmt, ...)
236__attribute__((format(printf, 4, 5)));
237
238/*!
239 * \brief Fill in an \c OK (200) \a ast_ari_response.
240 * \param response Response to fill in.
241 * \param message JSON response. This reference is stolen, so just \ref
242 * ast_json_ref if you need to keep a reference to it.
243 */
244void ast_ari_response_ok(struct ast_ari_response *response,
245 struct ast_json *message);
246
247/*!
248 * \brief Fill in a <tt>No Content</tt> (204) \a ast_ari_response.
249 */
250void ast_ari_response_no_content(struct ast_ari_response *response);
251
252/*!
253 * \brief Fill in a <tt>Accepted</tt> (202) \a ast_ari_response.
254 */
255void ast_ari_response_accepted(struct ast_ari_response *response);
256
257/*!
258 * \brief Fill in a <tt>Created</tt> (201) \a ast_ari_response.
259 * \param response Response to fill in.
260 * \param url URL to the created resource.
261 * \param message JSON response. This reference is stolen, so just \ref
262 * ast_json_ref if you need to keep a reference to it.
263 */
264void ast_ari_response_created(struct ast_ari_response *response,
265 const char *url, struct ast_json *message);
266
267/*!
268 * \brief Fill in \a response with a 500 message for allocation failures.
269 * \param response Response to fill in.
270 */
272
273#endif /* _ASTERISK_ARI_H */
struct ast_ari_websocket_session * ast_ari_websocket_session_create(struct ast_websocket *ws_session, int(*validator)(struct ast_json *))
Create an ARI WebSocket session.
struct ast_json * ast_ari_websocket_session_read(struct ast_ari_websocket_session *session)
Read a message from an ARI WebSocket.
enum ast_json_encoding_format ast_ari_json_format(void)
Configured encoding format for JSON output.
Definition: res_ari.c:806
void ast_ari_response_created(struct ast_ari_response *response, const char *url, struct ast_json *message)
Fill in a Created (201) ast_ari_response.
Definition: res_ari.c:305
int ast_ari_remove_handler(struct stasis_rest_handlers *handler)
Definition: res_ari.c:202
const char * ast_ari_websocket_session_id(const struct ast_ari_websocket_session *session)
Get the Session ID for an ARI WebSocket.
struct ast_sockaddr * ast_ari_websocket_session_get_remote_addr(struct ast_ari_websocket_session *session)
Get the remote address from an ARI WebSocket.
int ast_ari_websocket_session_write(struct ast_ari_websocket_session *session, struct ast_json *message)
Send a message to an ARI WebSocket.
void ast_ari_response_error(struct ast_ari_response *response, int response_code, const char *response_text, const char *message_fmt,...)
Fill in an error ast_ari_response.
Definition: res_ari.c:259
void ast_ari_invoke(struct ast_tcptls_session_instance *ser, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: res_ari.c:491
void ast_ari_response_ok(struct ast_ari_response *response, struct ast_json *message)
Fill in an OK (200) ast_ari_response.
Definition: res_ari.c:276
void(* stasis_rest_callback)(struct ast_tcptls_session_instance *ser, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Callback type for RESTful method handlers.
Definition: ari.h:60
void ast_ari_response_accepted(struct ast_ari_response *response)
Fill in a Accepted (202) ast_ari_response.
Definition: res_ari.c:291
struct ast_json * ast_ari_oom_json(void)
The stock message to return when out of memory.
Definition: res_ari.c:174
void ast_ari_response_alloc_failed(struct ast_ari_response *response)
Fill in response with a 500 message for allocation failures.
Definition: res_ari.c:298
void ast_ari_response_no_content(struct ast_ari_response *response)
Fill in a No Content (204) ast_ari_response.
Definition: res_ari.c:284
void ast_ari_get_docs(const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response)
Definition: res_ari.c:598
int ast_ari_add_handler(struct stasis_rest_handlers *handler)
Definition: res_ari.c:179
static struct ast_mansession session
static char prefix[MAX_PREFIX]
Definition: http.c:144
Support for Private Asterisk HTTP Servers.
ast_http_method
HTTP Request methods known by Asterisk.
Definition: http.h:58
@ AST_HTTP_MAX_METHOD
Definition: http.h:66
Asterisk JSON abstraction layer.
ast_json_encoding_format
Encoding format type.
Definition: json.h:791
static char url[512]
const char * method
Definition: res_pjsip.c:1279
struct ast_str * headers
Definition: ari.h:96
struct ast_json * message
Definition: ari.h:94
int response_code
Definition: ari.h:99
const char * response_text
Definition: ari.h:103
unsigned int no_response
Definition: ari.h:105
struct ast_websocket * ws_session
int(* validator)(struct ast_json *)
Abstract JSON element (object, array, string, int, ...).
Socket address structure.
Definition: netsock2.h:97
Support for dynamic strings.
Definition: strings.h:623
describes a server instance
Definition: tcptls.h:150
Structure for variables, used for configurations and for channel variables.
Structure for a WebSocket server.
Structure definition for session.
Handler for a single RESTful path segment.
Definition: ari.h:69
stasis_rest_callback callbacks[AST_HTTP_MAX_METHOD]
Definition: ari.h:80
const char * path_segment
Definition: ari.h:71
struct ast_websocket_server * ws_server
Definition: ari.h:82
struct stasis_rest_handlers * children[]
Definition: ari.h:86
size_t num_children
Definition: ari.h:84
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59