272bac70dd
Add framework to connect to, and read and write protocol based messages from and to an external application using an Asterisk External Application Protocol (AEAP). This has been divided into several abstractions: 1. transport - base communication layer (currently websocket only) 2. message - AEAP description and data (currently JSON only) 3. transaction - links/binds requests and responses 4. aeap - transport, message, and transaction handler/manager This patch also adds an AEAP implementation for speech to text. Existing speech API callbacks for speech to text have been completed making it possible for Asterisk to connect to a configured external translator service and provide audio for STT. Results can also be received from the external translator, and made available as speech results in Asterisk. Unit tests have also been created that test the AEAP framework, and also the speech to text implementation. ASTERISK-29726 #close Change-Id: Iaa4b259f84aa63501e5fd2a6fb107f900b4d4ed2
210 lines
6.2 KiB
C
210 lines
6.2 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2021, Sangoma Technologies Corporation
|
|
*
|
|
* Kevin Harwell <kharwell@sangoma.com>
|
|
*
|
|
* 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 RES_AEAP_TRANSPORT_H
|
|
#define RES_AEAP_TRANSPORT_H
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "asterisk/res_aeap.h"
|
|
|
|
struct aeap_transport;
|
|
|
|
/*!
|
|
* \brief Asterisk external application transport virtual table
|
|
*
|
|
* Callbacks to be implemented by "derived" transports
|
|
*/
|
|
struct aeap_transport_vtable {
|
|
/*!
|
|
* \brief Connect a transport
|
|
*
|
|
* \param self The transport object
|
|
* \param url The URL to connect to
|
|
* \param protocol The connection protocol to use if applicable
|
|
* \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
|
|
*
|
|
* \returns 0 on success, or -1 on error
|
|
*/
|
|
int (*connect)(struct aeap_transport *self, const char *url, const char *protocol, int timeout);
|
|
|
|
/*!
|
|
* \brief Disconnect a transport
|
|
*
|
|
* \param self The transport object
|
|
*
|
|
* \returns 0 on success, or -1 on error
|
|
*/
|
|
int (*disconnect)(struct aeap_transport *self);
|
|
|
|
/*!
|
|
* \brief Destroy a transport
|
|
*
|
|
* \param self The transport object
|
|
*/
|
|
void (*destroy)(struct aeap_transport *self);
|
|
|
|
/*!
|
|
* \brief Read data from a transport
|
|
*
|
|
* \param self The transport object
|
|
* \param buf The buffer data is read read into
|
|
* \param size The size of the given data buffer
|
|
* \param rtype [out] The type of data read
|
|
*
|
|
* \returns Total number of bytes read, or less than zero on error
|
|
*/
|
|
intmax_t (*read)(struct aeap_transport *self, void *buf, intmax_t size,
|
|
enum AST_AEAP_DATA_TYPE *rtype);
|
|
|
|
/*!
|
|
* \brief Write data to a transport
|
|
*
|
|
* \param self The transport object
|
|
* \param buf The data to write
|
|
* \param size The size of data to write
|
|
* \param wtype The type of data to write
|
|
*
|
|
* \returns Total number of bytes written, or less than zero on error
|
|
*/
|
|
intmax_t (*write)(struct aeap_transport *self, const void *buf, intmax_t size,
|
|
enum AST_AEAP_DATA_TYPE wtype);
|
|
};
|
|
|
|
/*!
|
|
* \brief Asterisk external application transport structure to be
|
|
* "derived" by specific transport implementation types
|
|
*
|
|
* Transports are assumed to support simultaneous reading and writing,
|
|
* thus separate read and write locks. A transport type not supporting
|
|
* such can simply apply the opposing lock during a read or write, i.e.
|
|
* lock the write lock during a read and vice versa.
|
|
*/
|
|
struct aeap_transport {
|
|
/*! Transport virtual table */
|
|
struct aeap_transport_vtable *vtable;
|
|
/*! Whether or not the transport is connected */
|
|
unsigned int connected;
|
|
/*! Lock used when reading */
|
|
ast_mutex_t read_lock;
|
|
/*! Lock used when writing */
|
|
ast_mutex_t write_lock;
|
|
};
|
|
|
|
/*!
|
|
* \brief Create an Asterisk external application transport
|
|
*
|
|
* \param type The type of transport to create
|
|
*
|
|
* \returns An Asterisk external application transport, or NULL on error
|
|
*/
|
|
struct aeap_transport *aeap_transport_create(const char *type);
|
|
|
|
/*!
|
|
* \brief Connect a transport
|
|
*
|
|
* \param transport The transport to connect
|
|
* \param url The URL to connect to
|
|
* \param protocol The connection protocol to use if applicable
|
|
* \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
|
|
*
|
|
* \returns 0 on success, or -1 on error
|
|
*/
|
|
int aeap_transport_connect(struct aeap_transport *transport, const char *url,
|
|
const char *protocol, int timeout);
|
|
|
|
/*!
|
|
* \brief Create an Asterisk external application transport, and connect it
|
|
*
|
|
* \param type The type of transport to create
|
|
* \param url The URL to connect to
|
|
* \param protocol The connection protocol to use if applicable
|
|
* \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
|
|
*
|
|
* \returns An Asterisk external application transport, or NULL on error
|
|
*/
|
|
struct aeap_transport *aeap_transport_create_and_connect(const char* type,
|
|
const char *url, const char *protocol, int timeout);
|
|
|
|
/*!
|
|
* \brief Disconnect a transport
|
|
*
|
|
* \note Locks both the transport's read and write locks before calling transport
|
|
* instance's disconnect, and unlocks both before returning.
|
|
*
|
|
* \param transport The transport to disconnect
|
|
*
|
|
* \returns 0 on success, or -1 on error
|
|
*/
|
|
int aeap_transport_disconnect(struct aeap_transport *transport);
|
|
|
|
/*!
|
|
* \brief Whether or not the transport is in a connected state
|
|
*
|
|
* \param transport The transport object
|
|
*
|
|
* \returns True if connected, false otherwise
|
|
*/
|
|
int aeap_transport_is_connected(struct aeap_transport *transport);
|
|
|
|
/*!
|
|
* \brief Destroy a transport
|
|
*
|
|
* \param transport The transport to destroy
|
|
*
|
|
* \returns 0 on success, or -1 on error
|
|
*/
|
|
void aeap_transport_destroy(struct aeap_transport *transport);
|
|
|
|
/*!
|
|
* \brief Read data from the transport
|
|
*
|
|
* This is a blocking read, and will not return until the transport
|
|
* implementation returns.
|
|
*
|
|
* \note Locks transport's read lock before calling transport instance's
|
|
* read, and unlocks it before returning.
|
|
*
|
|
* \param transport The transport to read from
|
|
* \param buf The buffer data is read into
|
|
* \param size The size of data given data buffer
|
|
* \param rtype [out] The type of data read
|
|
*
|
|
* \returns Total number of bytes read, or less than zero on error
|
|
*/
|
|
intmax_t aeap_transport_read(struct aeap_transport *transport, void *buf, intmax_t size,
|
|
enum AST_AEAP_DATA_TYPE *rtype);
|
|
|
|
/*!
|
|
* \brief Write data to the transport
|
|
*
|
|
* \note Locks transport's write lock before calling transport instance's
|
|
* write, and unlocks it before returning.
|
|
*
|
|
* \param transport The transport to write to
|
|
* \param buf The data to write
|
|
* \param size The size of data to write
|
|
* \param wtype The type of data to write
|
|
*
|
|
* \returns Total number of bytes written, or less than zero on error
|
|
*/
|
|
intmax_t aeap_transport_write(struct aeap_transport *transport, const void *buf, intmax_t size,
|
|
enum AST_AEAP_DATA_TYPE wtype);
|
|
|
|
#endif /* RES_AEAP_TRANSPORT_H */
|