mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-05 04:32:44 +00:00
44a9c16e9c
Fixes four misuses of the parameter 'name'. Additionally, for consistency and to avoid such an issue in future, those few other places, which used '\file name', were changed just to '\file'. Then, Doxygen uses the name of the current file. ASTERISK-29733 Change-Id: I0c18b4c863c6988b138c77448057349a9ee7052d
276 lines
9.0 KiB
C
276 lines
9.0 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 1999 - 2015, Digium, Inc.
|
|
*
|
|
* Timo Teräs <timo.teras@iki.fi>
|
|
*
|
|
* 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 _ASTERISK_IOSTREAM_H
|
|
#define _ASTERISK_IOSTREAM_H
|
|
|
|
/*!
|
|
* \file
|
|
*
|
|
* \brief Generic abstraction for input/output streams.
|
|
*/
|
|
|
|
#include "asterisk.h" /* for size_t, ssize_t, HAVE_OPENSSL */
|
|
|
|
#if defined(HAVE_OPENSSL)
|
|
#define DO_SSL /* comment in/out if you want to support ssl */
|
|
#endif
|
|
|
|
struct ssl_st; /* forward declaration */
|
|
struct ssl_ctx_st; /* forward declaration */
|
|
struct timeval; /* forward declaration */
|
|
typedef struct ssl_st SSL;
|
|
typedef struct ssl_ctx_st SSL_CTX;
|
|
|
|
struct ast_iostream; /* forward declaration */
|
|
|
|
/*!
|
|
* \brief Disable the iostream timeout timer.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_set_timeout_disable(struct ast_iostream *stream);
|
|
|
|
/*!
|
|
* \brief Set the iostream inactivity timeout timer.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param timeout Number of milliseconds to wait for data transfer with the peer.
|
|
*
|
|
* \details This is basically how much time we are willing to spend
|
|
* in an I/O call before we declare the peer unresponsive.
|
|
*
|
|
* \note Setting timeout to -1 disables the timeout.
|
|
* \note Setting this timeout replaces the I/O sequence timeout timer.
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout);
|
|
|
|
/*!
|
|
* \brief Set the iostream inactivity & idle timeout timers.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param timeout Number of milliseconds to wait for initial data transfer with
|
|
* the peer.
|
|
* \param timeout_reset Number of milliseconds to wait for subsequent data
|
|
* transfer with the peer.
|
|
*
|
|
* \details As an example, if you want to timeout a peer if they do not send an
|
|
* initial message within 5 seconds or if they do not send a message at
|
|
* least every 30 seconds, you would set \a timeout to \c 5000 and
|
|
* \a timeout_reset to \c 30000.
|
|
*
|
|
* \note Setting either of these timeouts to -1 will disable them.
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int timeout, int timeout_reset);
|
|
|
|
/*!
|
|
* \brief Set the iostream I/O sequence timeout timer.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param start Time the I/O sequence timer starts.
|
|
* \param timeout Number of milliseconds from the start time before timeout.
|
|
*
|
|
* \details This is how much time are we willing to allow the peer
|
|
* to complete an operation that can take several I/O calls. The
|
|
* main use is as an authentication timer with us.
|
|
*
|
|
* \note Setting timeout to -1 disables the timeout.
|
|
* \note Setting this timeout replaces the inactivity timeout timer.
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_set_timeout_sequence(struct ast_iostream *stream, struct timeval start, int timeout);
|
|
|
|
/*!
|
|
* \brief Set the iostream if it can exclusively depend upon the set timeouts.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param exclusive_input TRUE if stream can exclusively wait for fd input.
|
|
* Otherwise, the stream will not wait for fd input. It will wait while
|
|
* trying to send data.
|
|
*
|
|
* \note The stream timeouts still need to be set.
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive_input);
|
|
|
|
/*!
|
|
* \brief Get an iostream's file descriptor.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
*
|
|
* \return The file descriptor for the given iostream, or -1 if the iostream has no open
|
|
* file descriptor.
|
|
*/
|
|
int ast_iostream_get_fd(struct ast_iostream *stream);
|
|
|
|
/*!
|
|
* \brief Wait for input on the iostream's file descriptor
|
|
* \since 16.8.0
|
|
* \since 17.2.0
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param timeout the number of milliseconds to wait
|
|
*
|
|
* \retval -1 if error occurred
|
|
* \retval 0 if the timeout expired
|
|
* \retval 1 if the stream is ready for reading
|
|
*/
|
|
int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout);
|
|
|
|
/*!
|
|
* \brief Make an iostream non-blocking.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
void ast_iostream_nonblock(struct ast_iostream *stream);
|
|
|
|
/*!
|
|
* \brief Get a pointer to an iostream's OpenSSL \c SSL structure
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
*
|
|
* \return A pointer to the OpenSSL \c SSL structure for the given iostream, or
|
|
* \c NULL if TLS has not been initiated.
|
|
*
|
|
* \note If OpenSSL support is not included in the build, this will always return
|
|
* \c NULL.
|
|
*/
|
|
SSL *ast_iostream_get_ssl(struct ast_iostream *stream);
|
|
|
|
/*!
|
|
* \brief Read data from an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param buffer Pointer to a buffer to store the read bytes.
|
|
* \param count The number of bytes to read.
|
|
*
|
|
* \return Upon successful completion, returns a non-negative integer indicating
|
|
* the number of bytes actually read. Otherwise, returns -1 and may set
|
|
* errno to indicate the error.
|
|
*/
|
|
ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count);
|
|
|
|
/*!
|
|
* \brief Read a LF-terminated string from an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param buffer Pointer to a buffer to store the read bytes.
|
|
* \param size The total size of \a buffer in bytes.
|
|
*
|
|
* \return The number of bytes stored in \a buffer, excluding the null byte used
|
|
* to terminate the string. If the size of \a buffer (indicated by the
|
|
* caller with the \a size argument) is not sufficient to store the
|
|
* entire line it will be truncated to fit the available space. The
|
|
* contents of \a buffer will always be terminated with a null byte. In
|
|
* the case of an error, \c -1 will be returned and \c errno may be set
|
|
* indicating the error.
|
|
*/
|
|
ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size);
|
|
|
|
/*!
|
|
* \brief Discard the specified number of bytes from an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param count The number of bytes to discard.
|
|
*
|
|
* \return Upon successful completion, returns the number of bytes discarded.
|
|
* Otherwise, \c -1 is returned and \c errno may be set indicating the
|
|
* error.
|
|
*/
|
|
ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count);
|
|
|
|
/*!
|
|
* \brief Write data to an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param buffer Pointer to a buffer from which to read bytes.
|
|
* \param count The number of bytes from \a buffer to write.
|
|
*
|
|
* \return Upon successful completion, returns the number of bytes actually
|
|
* written to the iostream. This number shall never be greater than
|
|
* \a count. Otherwise, returns \c -1 and may set \c errno to indicate
|
|
* the error.
|
|
*/
|
|
ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count);
|
|
|
|
/*!
|
|
* \brief Write a formatted string to an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
* \param format A format string, as documented by printf(3)
|
|
* \param ... Arguments for the provided \a format string
|
|
*
|
|
* \return The number of bytes written, or \c -1 if an error occurs. Note that if
|
|
* \c -1 is returned, the number of bytes written to the iostream is
|
|
* unspecified.
|
|
*/
|
|
ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(
|
|
struct ast_iostream *stream, const char *format, ...);
|
|
|
|
/*!
|
|
* \brief Create an iostream from a file descriptor.
|
|
*
|
|
* \param fd A pointer to an open file descriptor
|
|
*
|
|
* \return A newly allocated iostream or \c NULL if allocation fails.
|
|
*/
|
|
struct ast_iostream *ast_iostream_from_fd(int *fd);
|
|
|
|
/*!
|
|
* \brief Begin TLS on an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream pointer
|
|
* \param ctx A pointer to an \c SSL_CTX which will be passed to \c SSL_new()
|
|
* \param client Non-zero to indicate that we are the client, zero to indicate
|
|
* that we are the server.
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note The iostream that is passed in \a stream may be replaced with a
|
|
* different one before this function returns.
|
|
* \note On failure, \c errno may be set providing additional information on why
|
|
* the failure occurred.
|
|
*/
|
|
int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client);
|
|
|
|
/*!
|
|
* \brief Close an iostream.
|
|
*
|
|
* \param stream A pointer to an iostream
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note On failure, \c errno may be set providing additional information on why
|
|
* the failure occurred.
|
|
*/
|
|
int ast_iostream_close(struct ast_iostream *stream);
|
|
|
|
#endif /* _ASTERISK_IOSTREAM_H */
|