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