Asterisk - The Open Source Telephony Project GIT-master-8924258
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Modules Pages
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 (Maybe NULL if not available).
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 /*!
82 * ws_server is no longer needed to indicate if a path should cause
83 * an Upgrade to websocket but is kept for backwards compatability.
84 * Instead, simply set is_websocket to true.
85 */
86 union {
87 /*! \deprecated WebSocket server for handling WebSocket upgrades. */
89 /*! The path segment is handled by the websocket */
91 };
92 /*! Number of children in the children array */
94 /*! Handlers for sub-paths */
96};
97
98/*!
99 * Response type for RESTful requests
100 */
102 /*! Response message */
104 /*! \\r\\n seperated response headers */
106 /*! HTTP response code.
107 * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
109 /*! File descriptor for whatever file we want to respond with */
110 int fd;
111 /*! Corresponding text for the response code */
112 const char *response_text; /* Shouldn't http.c handle this? */
113 /*! Flag to indicate that no further response is needed */
114 unsigned int no_response:1;
115};
116
117/*!
118 * Add a resource for REST handling.
119 * \param handler Handler to add.
120 * \retval 0 on success.
121 * \retval non-zero on failure.
122 */
124
125/*!
126 * Remove a resource for REST handling.
127 * \param handler Handler to add.
128 * \retval 0 on success.
129 * \retval non-zero on failure.
130 */
132
133/*!
134 * \internal
135 * \brief Stasis RESTful invocation handler response codes.
136 */
141};
142
143/*!
144 * \internal
145 * \brief How was Stasis RESTful invocation handler invoked?
146 */
151};
152
153/*!
154 * \internal
155 * \brief Stasis RESTful invocation handler.
156 *
157 * Only call from res_ari and test_ari. Only public to allow
158 * for unit testing.
159 *
160 * \param ser TCP/TLS connection.
161 * \param uri HTTP URI, relative to the API path.
162 * \param method HTTP method.
163 * \param get_params HTTP \c GET parameters.
164 * \param headers HTTP headers.
165 * \param body
166 * \param[out] response RESTful HTTP response.
167 * \param is_websocket Flag to indicate if this is a WebSocket request.
168 */
170 enum ast_ari_invoke_source source, const struct ast_http_uri *urih,
171 const char *uri, enum ast_http_method method,
172 struct ast_variable *get_params, struct ast_variable *headers,
173 struct ast_json *body, struct ast_ari_response *response);
174
175/*!
176 * \internal
177 * \brief Service function for API declarations.
178 *
179 * Only call from res_ari and test_ari. Only public to allow
180 * for unit testing.
181 *
182 * \param uri Requested URI, relative to the docs path.
183 * \param prefix prefix that prefixes all http requests
184 * \param headers HTTP headers.
185 * \param[out] response RESTful HTTP response.
186 */
187void ast_ari_get_docs(const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response);
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 */
197struct 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 */
206void 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_ref if you need to keep a reference to it.
217 */
218void 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 */
224void ast_ari_response_no_content(struct ast_ari_response *response);
225
226/*!
227 * \brief Fill in a <tt>Accepted</tt> (202) \a ast_ari_response.
228 */
229void ast_ari_response_accepted(struct ast_ari_response *response);
230
231/*!
232 * \brief Fill in a <tt>Created</tt> (201) \a ast_ari_response.
233 * \param response Response to fill in.
234 * \param url URL to the created resource.
235 * \param message JSON response. This reference is stolen, so just \ref
236 * ast_json_ref if you need to keep a reference to it.
237 */
238void ast_ari_response_created(struct ast_ari_response *response,
239 const char *url, struct ast_json *message);
240
241/*!
242 * \brief Fill in \a response with a 500 message for allocation failures.
243 * \param response Response to fill in.
244 */
246
247#endif /* _ASTERISK_ARI_H */
enum ast_json_encoding_format ast_ari_json_format(void)
Configured encoding format for JSON output.
Definition: res_ari.c:1015
ast_ari_invoke_source
Definition: ari.h:147
@ ARI_INVOKE_SOURCE_REST
Definition: ari.h:148
@ ARI_INVOKE_SOURCE_TEST
Definition: ari.h:150
@ ARI_INVOKE_SOURCE_WEBSOCKET
Definition: ari.h:149
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:365
int ast_ari_remove_handler(struct stasis_rest_handlers *handler)
Definition: res_ari.c:262
ast_ari_invoke_result
Definition: ari.h:137
@ ARI_INVOKE_RESULT_SUCCESS
Definition: ari.h:138
@ ARI_INVOKE_RESULT_ERROR_CLOSE
Definition: ari.h:140
@ ARI_INVOKE_RESULT_ERROR_CONTINUE
Definition: ari.h:139
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:319
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:336
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:351
struct ast_json * ast_ari_oom_json(void)
The stock message to return when out of memory.
Definition: res_ari.c:234
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:358
void ast_ari_response_no_content(struct ast_ari_response *response)
Fill in a No Content (204) ast_ari_response.
Definition: res_ari.c:344
void ast_ari_get_docs(const char *uri, const char *prefix, struct ast_variable *headers, struct ast_ari_response *response)
Definition: res_ari.c:833
int ast_ari_add_handler(struct stasis_rest_handlers *handler)
Definition: res_ari.c:239
enum ast_ari_invoke_result ast_ari_invoke(struct ast_tcptls_session_instance *ser, enum ast_ari_invoke_source source, const struct ast_http_uri *urih, 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:635
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:105
struct ast_json * message
Definition: ari.h:103
int response_code
Definition: ari.h:108
const char * response_text
Definition: ari.h:112
unsigned int no_response
Definition: ari.h:114
Definition of a URI handler.
Definition: http.h:102
Abstract JSON element (object, array, string, int, ...).
Support for dynamic strings.
Definition: strings.h:623
describes a server instance
Definition: tcptls.h:151
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
int is_websocket
Definition: ari.h:90
const char * path_segment
Definition: ari.h:71
struct ast_websocket_server * ws_server
Definition: ari.h:88
struct stasis_rest_handlers * children[]
Definition: ari.h:95
size_t num_children
Definition: ari.h:93
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