Asterisk - The Open Source Telephony Project GIT-master-2de1a68
iostream.h
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 1999 - 2015, Digium, Inc.
5 *
6 * Timo Teräs <timo.teras@iki.fi>
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_IOSTREAM_H
20#define _ASTERISK_IOSTREAM_H
21
22/*!
23 * \file
24 *
25 * \brief Generic abstraction for input/output streams.
26 */
27
28#include "asterisk.h" /* for size_t, ssize_t, HAVE_OPENSSL */
29
30#if defined(HAVE_OPENSSL)
31#define DO_SSL /* comment in/out if you want to support ssl */
32#endif
33
34struct ssl_st; /* forward declaration */
35struct ssl_ctx_st; /* forward declaration */
36struct timeval; /* forward declaration */
37typedef struct ssl_st SSL;
38typedef struct ssl_ctx_st SSL_CTX;
39
40struct ast_iostream; /* forward declaration */
41
42/*!
43 * \brief Disable the iostream timeout timer.
44 *
45 * \param stream A pointer to an iostream
46 */
48
49/*!
50 * \brief Set the iostream inactivity timeout timer.
51 *
52 * \param stream A pointer to an iostream
53 * \param timeout Number of milliseconds to wait for data transfer with the peer.
54 *
55 * \details This is basically how much time we are willing to spend
56 * in an I/O call before we declare the peer unresponsive.
57 *
58 * \note Setting timeout to -1 disables the timeout.
59 * \note Setting this timeout replaces the I/O sequence timeout timer.
60 */
62
63/*!
64 * \brief Set the iostream inactivity & idle timeout timers.
65 *
66 * \param stream A pointer to an iostream
67 * \param timeout Number of milliseconds to wait for initial data transfer with
68 * the peer.
69 * \param timeout_reset Number of milliseconds to wait for subsequent data
70 * transfer with the peer.
71 *
72 * \details As an example, if you want to timeout a peer if they do not send an
73 * initial message within 5 seconds or if they do not send a message at
74 * least every 30 seconds, you would set \a timeout to \c 5000 and
75 * \a timeout_reset to \c 30000.
76 *
77 * \note Setting either of these timeouts to -1 will disable them.
78 */
80
81/*!
82 * \brief Set the iostream I/O sequence timeout timer.
83 *
84 * \param stream A pointer to an iostream
85 * \param start Time the I/O sequence timer starts.
86 * \param timeout Number of milliseconds from the start time before timeout.
87 *
88 * \details This is how much time are we willing to allow the peer
89 * to complete an operation that can take several I/O calls. The
90 * main use is as an authentication timer with us.
91 *
92 * \note Setting timeout to -1 disables the timeout.
93 * \note Setting this timeout replaces the inactivity timeout timer.
94 */
95void ast_iostream_set_timeout_sequence(struct ast_iostream *stream, struct timeval start, int timeout);
96
97/*!
98 * \brief Set the iostream if it can exclusively depend upon the set timeouts.
99 *
100 * \param stream A pointer to an iostream
101 * \param exclusive_input TRUE if stream can exclusively wait for fd input.
102 * Otherwise, the stream will not wait for fd input. It will wait while
103 * trying to send data.
104 *
105 * \note The stream timeouts still need to be set.
106 */
108
109/*!
110 * \brief Get an iostream's file descriptor.
111 *
112 * \param stream A pointer to an iostream
113 *
114 * \return The file descriptor for the given iostream
115 * \retval -1 if the iostream has no open file descriptor.
116 */
117int ast_iostream_get_fd(struct ast_iostream *stream);
118
119/*!
120 * \brief Wait for input on the iostream's file descriptor
121 * \since 16.8.0
122 * \since 17.2.0
123 *
124 * \param stream A pointer to an iostream
125 * \param timeout the number of milliseconds to wait
126 *
127 * \retval -1 if error occurred
128 * \retval 0 if the timeout expired
129 * \retval 1 if the stream is ready for reading
130 */
131int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout);
132
133/*!
134 * \brief Make an iostream non-blocking.
135 *
136 * \param stream A pointer to an iostream
137 */
138void ast_iostream_nonblock(struct ast_iostream *stream);
139
140/*!
141 * \brief Get a pointer to an iostream's OpenSSL \c SSL structure
142 *
143 * \param stream A pointer to an iostream
144 *
145 * \return A pointer to the OpenSSL \c SSL structure for the given iostream
146 * \retval NULL if TLS has not been initiated.
147 *
148 * \note If OpenSSL support is not included in the build, this will always return
149 * \c NULL.
150 */
151SSL *ast_iostream_get_ssl(struct ast_iostream *stream);
152
153/*!
154 * \brief Read data from an iostream.
155 *
156 * \param stream A pointer to an iostream
157 * \param buffer Pointer to a buffer to store the read bytes.
158 * \param count The number of bytes to read.
159 *
160 * \return Upon successful completion, returns a non-negative integer indicating
161 * the number of bytes actually read. Otherwise, returns -1 and may set
162 * errno to indicate the error.
163 */
164ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count);
165
166/*!
167 * \brief Read a LF-terminated string from an iostream.
168 *
169 * \param stream A pointer to an iostream
170 * \param buffer Pointer to a buffer to store the read bytes.
171 * \param size The total size of \a buffer in bytes.
172 *
173 * \return The number of bytes stored in \a buffer, excluding the null byte used
174 * to terminate the string. If the size of \a buffer (indicated by the
175 * caller with the \a size argument) is not sufficient to store the
176 * entire line it will be truncated to fit the available space. The
177 * contents of \a buffer will always be terminated with a null byte. In
178 * the case of an error, \c -1 will be returned and \c errno may be set
179 * indicating the error.
180 */
181ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size);
182
183/*!
184 * \brief Discard the specified number of bytes from an iostream.
185 *
186 * \param stream A pointer to an iostream
187 * \param count The number of bytes to discard.
188 *
189 * \return Upon successful completion, returns the number of bytes discarded.
190 * Otherwise, \c -1 is returned and \c errno may be set indicating the
191 * error.
192 */
193ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count);
194
195/*!
196 * \brief Write data to an iostream.
197 *
198 * \param stream A pointer to an iostream
199 * \param buffer Pointer to a buffer from which to read bytes.
200 * \param count The number of bytes from \a buffer to write.
201 *
202 * \return Upon successful completion, returns the number of bytes actually
203 * written to the iostream. This number shall never be greater than
204 * \a count. Otherwise, returns \c -1 and may set \c errno to indicate
205 * the error.
206 */
207ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count);
208
209/*!
210 * \brief Write a formatted string to an iostream.
211 *
212 * \param stream A pointer to an iostream
213 * \param format A format string, as documented by printf(3)
214 * \param ... Arguments for the provided \a format string
215 *
216 * \return The number of bytes written, or \c -1 if an error occurs. Note that if
217 * \c -1 is returned, the number of bytes written to the iostream is
218 * unspecified.
219 */
220ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(
221 struct ast_iostream *stream, const char *format, ...);
222
223/*!
224 * \brief Create an iostream from a file descriptor.
225 *
226 * \param fd A pointer to an open file descriptor
227 *
228 * \return A newly allocated iostream or \c NULL if allocation fails.
229 */
231
232/*!
233 * \brief Begin TLS on an iostream.
234 *
235 * \param stream A pointer to an iostream pointer
236 * \param ctx A pointer to an \c SSL_CTX which will be passed to \c SSL_new()
237 * \param client Non-zero to indicate that we are the client, zero to indicate
238 * that we are the server.
239 *
240 * \retval 0 success
241 * \retval -1 failure
242 *
243 * \note The iostream that is passed in \a stream may be replaced with a
244 * different one before this function returns.
245 * \note On failure, \c errno may be set providing additional information on why
246 * the failure occurred.
247 */
248int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client);
249
250/*!
251 * \brief Close an iostream.
252 *
253 * \param stream A pointer to an iostream
254 *
255 * \retval 0 success
256 * \retval -1 failure
257 *
258 * \note On failure, \c errno may be set providing additional information on why
259 * the failure occurred.
260 */
261int ast_iostream_close(struct ast_iostream *stream);
262
263#endif /* _ASTERISK_IOSTREAM_H */
Asterisk main include file. File version handling, generic pbx functions.
struct ssl_ctx_st SSL_CTX
Definition: iostream.h:38
ssize_t ast_iostream_printf(struct ast_iostream *stream, const char *format,...)
Write a formatted string to an iostream.
Definition: iostream.c:491
ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size)
Read a LF-terminated string from an iostream.
Definition: iostream.c:300
void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout)
Set the iostream inactivity timeout timer.
Definition: iostream.c:121
struct ast_iostream * ast_iostream_from_fd(int *fd)
Create an iostream from a file descriptor.
Definition: iostream.c:604
void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int timeout, int timeout_reset)
Set the iostream inactivity & idle timeout timers.
Definition: iostream.c:130
SSL * ast_iostream_get_ssl(struct ast_iostream *stream)
Get a pointer to an iostream's OpenSSL SSL structure.
Definition: iostream.c:108
int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client)
Begin TLS on an iostream.
Definition: iostream.c:620
ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count)
Write data to an iostream.
Definition: iostream.c:374
int ast_iostream_get_fd(struct ast_iostream *stream)
Get an iostream's file descriptor.
Definition: iostream.c:84
struct ssl_st SSL
Definition: iostream.h:37
void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive_input)
Set the iostream if it can exclusively depend upon the set timeouts.
Definition: iostream.c:148
ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count)
Read data from an iostream.
Definition: iostream.c:273
void ast_iostream_set_timeout_sequence(struct ast_iostream *stream, struct timeval start, int timeout)
Set the iostream I/O sequence timeout timer.
Definition: iostream.c:139
void ast_iostream_nonblock(struct ast_iostream *stream)
Make an iostream non-blocking.
Definition: iostream.c:103
ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count)
Discard the specified number of bytes from an iostream.
Definition: iostream.c:357
int ast_iostream_close(struct ast_iostream *stream)
Close an iostream.
Definition: iostream.c:528
void ast_iostream_set_timeout_disable(struct ast_iostream *stream)
Disable the iostream timeout timer.
Definition: iostream.c:113
int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout)
Wait for input on the iostream's file descriptor.
Definition: iostream.c:89
int timeout
Definition: iostream.c:43
int exclusive_input
Definition: iostream.c:45
int timeout_reset
Definition: iostream.c:44
struct timeval start
Definition: iostream.c:41