internal.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2013, Digium, Inc.
 *
 * David M. Lee, II <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

#ifndef ARI_INTERNAL_H_
#define ARI_INTERNAL_H_

/*! \file
 *
 * \brief Internal API's for res_ari.
 * \author David M. Lee, II <[email protected]>
 */

#include "asterisk/http.h"
#include "asterisk/json.h"
#include "asterisk/stringfields.h"

/*! @{ */

/*!
 * \brief Register CLI commands for ARI.
 *
 * \return 0 on success.
 * \return Non-zero on error.
 */
int ast_ari_cli_register(void);

/*!
 * \brief Unregister CLI commands for ARI.
 */
void ast_ari_cli_unregister(void);

/*! @} */

/*! @{ */

struct ast_ari_conf_general;

/*! \brief All configuration options for ARI. */
struct ast_ari_conf {
   /*! The general section configuration options. */
   struct ast_ari_conf_general *general;
   /*! Configured users */
   struct ao2_container *users;
};

/*! Max length for auth_realm field */
#define ARI_AUTH_REALM_LEN 80

/*! \brief Global configuration options for ARI. */
struct ast_ari_conf_general {
   /*! Enabled by default, disabled if false. */
   int enabled;
   /*! Write timeout for websocket connections */
   int write_timeout;
   /*! Encoding format used during output (default compact). */
   enum ast_json_encoding_format format;
   /*! Authentication realm */
   char auth_realm[ARI_AUTH_REALM_LEN];

   AST_DECLARE_STRING_FIELDS(
      AST_STRING_FIELD(allowed_origins);
   );
};

/*! \brief Password format */
enum ast_ari_password_format {
   /*! \brief Plaintext password */
   ARI_PASSWORD_FORMAT_PLAIN,
   /*! crypt(3) password */
   ARI_PASSWORD_FORMAT_CRYPT,
};

/*!
 * \brief User's password mx length.
 *
 * If 256 seems like a lot, a crypt SHA-512 has over 106 characters.
 */
#define ARI_PASSWORD_LEN 256

/*! \brief Per-user configuration options */
struct ast_ari_conf_user {
   /*! Username for authentication */
   char *username;
   /*! User's password. */
   char password[ARI_PASSWORD_LEN];
   /*! Format for the password field */
   enum ast_ari_password_format password_format;
   /*! If true, user cannot execute change operations */
   int read_only;
};

/*!
 * \brief Initialize the ARI configuration
 */
int ast_ari_config_init(void);

/*!
 * \brief Reload the ARI configuration
 */
int ast_ari_config_reload(void);

/*!
 * \brief Destroy the ARI configuration
 */
void ast_ari_config_destroy(void);

/*!
 * \brief Get the current ARI configuration.
 *
 * This is an immutable object, so don't modify it. It is AO2 managed, so
 * ao2_cleanup() when you're done with it.
 *
 * \return ARI configuration object.
 * \return \c NULL on error.
 */
struct ast_ari_conf *ast_ari_config_get(void);

/*!
 * \brief Validated a user's credentials.
 *
 * \param username Name of the user.
 * \param password User's password.
 * \return User object.
 * \return \c NULL if username or password is invalid.
 */
struct ast_ari_conf_user *ast_ari_config_validate_user(const char *username,
   const char *password);

/*! @} */

/* Forward-declare websocket structs. This avoids including http_websocket.h,
 * which causes optional_api stuff to happen, which makes optional_api more
 * difficult to debug. */

struct ast_websocket_server;

/*!
 * \brief Wrapper for invoking the websocket code for an incoming connection.
 *
 * \param ws_server WebSocket server to invoke.
 * \param ser HTTP session.
 * \param uri Requested URI.
 * \param method Requested HTTP method.
 * \param get_params Parsed query parameters.
 * \param headers Parsed HTTP headers.
 */
void ari_handle_websocket(struct ast_websocket_server *ws_server,
   struct ast_tcptls_session_instance *ser, const char *uri,
   enum ast_http_method method, struct ast_variable *get_params,
   struct ast_variable *headers);

#endif /* ARI_INTERNAL_H_ */