ari.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2012 - 2013, Digium, Inc.
00005  *
00006  * David M. Lee, II <dlee@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 #ifndef _ASTERISK_ARI_H
00020 #define _ASTERISK_ARI_H
00021 
00022 /*! \file
00023  *
00024  * \brief Asterisk RESTful API hooks.
00025  *
00026  * This header file is used mostly as glue code between generated declarations
00027  * and res_ari.c.
00028  *
00029  * \author David M. Lee, II <dlee@digium.com>
00030  */
00031 
00032 #include "asterisk/http.h"
00033 #include "asterisk/json.h"
00034 
00035 /* Forward-declare websocket structs. This avoids including http_websocket.h,
00036  * which causes optional_api stuff to happen, which makes optional_api more
00037  * difficult to debug. */
00038 
00039 struct ast_websocket_server;
00040 
00041 struct ast_websocket;
00042 
00043 /*!
00044  * \brief Configured encoding format for JSON output.
00045  * \return JSON output encoding (compact, pretty, etc.)
00046  */
00047 enum ast_json_encoding_format ast_ari_json_format(void);
00048 
00049 struct ast_ari_response;
00050 
00051 /*!
00052  * \brief Callback type for RESTful method handlers.
00053  * \param ser TCP/TLS session object
00054  * \param get_params GET parameters from the HTTP request.
00055  * \param path_vars Path variables from any wildcard path segments.
00056  * \param headers HTTP headers from the HTTP requiest.
00057  * \param[out] response The RESTful response.
00058  */
00059 typedef void (*stasis_rest_callback)(
00060    struct ast_tcptls_session_instance *ser,
00061    struct ast_variable *get_params, struct ast_variable *path_vars,
00062    struct ast_variable *headers, struct ast_ari_response *response);
00063 
00064 /*!
00065  * \brief Handler for a single RESTful path segment.
00066  */
00067 struct stasis_rest_handlers {
00068    /*! Path segement to handle */
00069    const char *path_segment;
00070    /*! If true (non-zero), path_segment is a wildcard, and will match all
00071     * values.
00072     *
00073     * Value of the segement will be passed into the \a path_vars parameter
00074     * of the callback.
00075     */
00076    int is_wildcard;
00077    /*! Callbacks for all handled HTTP methods. */
00078    stasis_rest_callback callbacks[AST_HTTP_MAX_METHOD];
00079    /*! WebSocket server for handling WebSocket upgrades. */
00080    struct ast_websocket_server *ws_server;
00081    /*! Number of children in the children array */
00082    size_t num_children;
00083    /*! Handlers for sub-paths */
00084    struct stasis_rest_handlers *children[];
00085 };
00086 
00087 /*!
00088  * Response type for RESTful requests
00089  */
00090 struct ast_ari_response {
00091    /*! Response message */
00092    struct ast_json *message;
00093    /*! \r\n seperated response headers */
00094    struct ast_str *headers;
00095    /*! HTTP response code.
00096     * See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
00097    int response_code;
00098    /*! Corresponding text for the response code */
00099    const char *response_text; /* Shouldn't http.c handle this? */
00100    /*! Flag to indicate that no further response is needed */
00101    int no_response:1;
00102 };
00103 
00104 /*!
00105  * Add a resource for REST handling.
00106  * \param handler Handler to add.
00107  * \return 0 on success.
00108  * \return non-zero on failure.
00109  */
00110 int ast_ari_add_handler(struct stasis_rest_handlers *handler);
00111 
00112 /*!
00113  * Remove a resource for REST handling.
00114  * \param handler Handler to add.
00115  * \return 0 on success.
00116  * \return non-zero on failure.
00117  */
00118 int ast_ari_remove_handler(struct stasis_rest_handlers *handler);
00119 
00120 /*!
00121  * \internal
00122  * \brief Stasis RESTful invocation handler.
00123  *
00124  * Only call from res_ari and test_ari. Only public to allow
00125  * for unit testing.
00126  *
00127  * \param ser TCP/TLS connection.
00128  * \param uri HTTP URI, relative to the API path.
00129  * \param method HTTP method.
00130  * \param get_params HTTP \c GET parameters.
00131  * \param headers HTTP headers.
00132  * \param[out] response RESTful HTTP response.
00133  */
00134 void ast_ari_invoke(struct ast_tcptls_session_instance *ser,
00135    const char *uri, enum ast_http_method method,
00136    struct ast_variable *get_params, struct ast_variable *headers,
00137    struct ast_ari_response *response);
00138 
00139 /*!
00140  * \internal
00141  * \brief Service function for API declarations.
00142  *
00143  * Only call from res_ari and test_ari. Only public to allow
00144  * for unit testing.
00145  *
00146  * \param uri Requested URI, relative to the docs path.
00147  * \param headers HTTP headers.
00148  * \param[out] response RESTful HTTP response.
00149  */
00150 void ast_ari_get_docs(const char *uri, struct ast_variable *headers, struct ast_ari_response *response);
00151 
00152 /*! \brief Abstraction for reading/writing JSON to a WebSocket */
00153 struct ast_ari_websocket_session;
00154 
00155 /*!
00156  * \brief Create an ARI WebSocket session.
00157  *
00158  * If \c NULL is given for the validator function, no validation will be
00159  * performed.
00160  *
00161  * \param ws_session Underlying WebSocket session.
00162  * \param validator Function to validate outgoing messages.
00163  * \return New ARI WebSocket session.
00164  * \return \c NULL on error.
00165  */
00166 struct ast_ari_websocket_session *ast_ari_websocket_session_create(
00167    struct ast_websocket *ws_session, int (*validator)(struct ast_json *));
00168 
00169 /*!
00170  * \brief Read a message from an ARI WebSocket.
00171  *
00172  * \param session Session to read from.
00173  * \return Message received.
00174  * \return \c NULL if WebSocket could not be read.
00175  */
00176 struct ast_json *ast_ari_websocket_session_read(
00177    struct ast_ari_websocket_session *session);
00178 
00179 /*!
00180  * \brief Send a message to an ARI WebSocket.
00181  *
00182  * \param session Session to write to.
00183  * \param message Message to send.
00184  * \return 0 on success.
00185  * \return Non-zero on error.
00186  */
00187 int ast_ari_websocket_session_write(struct ast_ari_websocket_session *session,
00188    struct ast_json *message);
00189 
00190 /*!
00191  * \brief The stock message to return when out of memory.
00192  *
00193  * The refcount is NOT bumped on this object, so ast_json_ref() if you want to
00194  * keep the reference.
00195  *
00196  * \return JSON message specifying an out-of-memory error.
00197  */
00198 struct ast_json *ast_ari_oom_json(void);
00199 
00200 /*!
00201  * \brief Fill in an error \a ast_ari_response.
00202  * \param response Response to fill in.
00203  * \param response_code HTTP response code.
00204  * \param response_text Text corresponding to the HTTP response code.
00205  * \param message_fmt Error message format string.
00206  */
00207 void ast_ari_response_error(struct ast_ari_response *response,
00208             int response_code,
00209             const char *response_text,
00210             const char *message_fmt, ...)
00211 __attribute__((format(printf, 4, 5)));
00212 
00213 /*!
00214  * \brief Fill in an \c OK (200) \a ast_ari_response.
00215  * \param response Response to fill in.
00216  * \param message JSON response.  This reference is stolen, so just \ref
00217  *                ast_json_ref if you need to keep a reference to it.
00218  */
00219 void ast_ari_response_ok(struct ast_ari_response *response,
00220               struct ast_json *message);
00221 
00222 /*!
00223  * \brief Fill in a <tt>No Content</tt> (204) \a ast_ari_response.
00224  */
00225 void ast_ari_response_no_content(struct ast_ari_response *response);
00226 
00227 /*!
00228  * \brief Fill in a <tt>Created</tt> (201) \a ast_ari_response.
00229  * \param response Response to fill in.
00230  * \param url URL to the created resource.
00231  * \param message JSON response.  This reference is stolen, so just \ref
00232  *                ast_json_ref if you need to keep a reference to it.
00233  */
00234 void ast_ari_response_created(struct ast_ari_response *response,
00235    const char *url, struct ast_json *message);
00236 
00237 /*!
00238  * \brief Fill in \a response with a 500 message for allocation failures.
00239  * \param response Response to fill in.
00240  */
00241 void ast_ari_response_alloc_failed(struct ast_ari_response *response);
00242 
00243 #endif /* _ASTERISK_ARI_H */

Generated on Thu Apr 16 06:27:13 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6