Asterisk - The Open Source Telephony Project  21.4.1
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 
34 struct ssl_st; /* forward declaration */
35 struct ssl_ctx_st; /* forward declaration */
36 struct timeval; /* forward declaration */
37 typedef struct ssl_st SSL;
38 typedef struct ssl_ctx_st SSL_CTX;
39 
40 struct 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  */
61 void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout);
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  */
79 void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int timeout, int timeout_reset);
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  */
95 void 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  */
107 void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive_input);
108 
109 /*!
110  * \brief Set the iostream's SNI hostname for TLS client connections
111  *
112  * \param stream A pointer to an iostream
113  * \param sni_hostname The hostname to use for SNI when in client mode
114  *
115  * \retval 0 if the hostname was set successfully.
116  * \retval -1 if memory could not be allocated for the hostname.
117  */
118 int ast_iostream_set_sni_hostname(struct ast_iostream *stream, const char *sni_hostname);
119 
120 /*!
121  * \brief Get an iostream's file descriptor.
122  *
123  * \param stream A pointer to an iostream
124  *
125  * \return The file descriptor for the given iostream
126  * \retval -1 if the iostream has no open file descriptor.
127  */
128 int ast_iostream_get_fd(struct ast_iostream *stream);
129 
130 /*!
131  * \brief Wait for input on the iostream's file descriptor
132  * \since 16.8.0
133  * \since 17.2.0
134  *
135  * \param stream A pointer to an iostream
136  * \param timeout the number of milliseconds to wait
137  *
138  * \retval -1 if error occurred
139  * \retval 0 if the timeout expired
140  * \retval 1 if the stream is ready for reading
141  */
142 int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout);
143 
144 /*!
145  * \brief Make an iostream non-blocking.
146  *
147  * \param stream A pointer to an iostream
148  */
149 void ast_iostream_nonblock(struct ast_iostream *stream);
150 
151 /*!
152  * \brief Get a pointer to an iostream's OpenSSL \c SSL structure
153  *
154  * \param stream A pointer to an iostream
155  *
156  * \return A pointer to the OpenSSL \c SSL structure for the given iostream
157  * \retval NULL if TLS has not been initiated.
158  *
159  * \note If OpenSSL support is not included in the build, this will always return
160  * \c NULL.
161  */
162 SSL *ast_iostream_get_ssl(struct ast_iostream *stream);
163 
164 /*!
165  * \brief Read data from an iostream.
166  *
167  * \param stream A pointer to an iostream
168  * \param buffer Pointer to a buffer to store the read bytes.
169  * \param count The number of bytes to read.
170  *
171  * \return Upon successful completion, returns a non-negative integer indicating
172  * the number of bytes actually read. Otherwise, returns -1 and may set
173  * errno to indicate the error.
174  */
175 ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count);
176 
177 /*!
178  * \brief Read a LF-terminated string from an iostream.
179  *
180  * \param stream A pointer to an iostream
181  * \param buffer Pointer to a buffer to store the read bytes.
182  * \param size The total size of \a buffer in bytes.
183  *
184  * \return The number of bytes stored in \a buffer, excluding the null byte used
185  * to terminate the string. If the size of \a buffer (indicated by the
186  * caller with the \a size argument) is not sufficient to store the
187  * entire line it will be truncated to fit the available space. The
188  * contents of \a buffer will always be terminated with a null byte. In
189  * the case of an error, \c -1 will be returned and \c errno may be set
190  * indicating the error.
191  */
192 ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size);
193 
194 /*!
195  * \brief Discard the specified number of bytes from an iostream.
196  *
197  * \param stream A pointer to an iostream
198  * \param count The number of bytes to discard.
199  *
200  * \return Upon successful completion, returns the number of bytes discarded.
201  * Otherwise, \c -1 is returned and \c errno may be set indicating the
202  * error.
203  */
204 ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count);
205 
206 /*!
207  * \brief Write data to an iostream.
208  *
209  * \param stream A pointer to an iostream
210  * \param buffer Pointer to a buffer from which to read bytes.
211  * \param count The number of bytes from \a buffer to write.
212  *
213  * \return Upon successful completion, returns the number of bytes actually
214  * written to the iostream. This number shall never be greater than
215  * \a count. Otherwise, returns \c -1 and may set \c errno to indicate
216  * the error.
217  */
218 ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count);
219 
220 /*!
221  * \brief Write a formatted string to an iostream.
222  *
223  * \param stream A pointer to an iostream
224  * \param format A format string, as documented by printf(3)
225  * \param ... Arguments for the provided \a format string
226  *
227  * \return The number of bytes written, or \c -1 if an error occurs. Note that if
228  * \c -1 is returned, the number of bytes written to the iostream is
229  * unspecified.
230  */
231 ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(
232  struct ast_iostream *stream, const char *format, ...);
233 
234 /*!
235  * \brief Create an iostream from a file descriptor.
236  *
237  * \param fd A pointer to an open file descriptor
238  *
239  * \return A newly allocated iostream or \c NULL if allocation fails.
240  */
241 struct ast_iostream *ast_iostream_from_fd(int *fd);
242 
243 /*!
244  * \brief Begin TLS on an iostream.
245  *
246  * \param stream A pointer to an iostream pointer
247  * \param ctx A pointer to an \c SSL_CTX which will be passed to \c SSL_new()
248  * \param client Non-zero to indicate that we are the client, zero to indicate
249  * that we are the server.
250  *
251  * \retval 0 success
252  * \retval -1 failure
253  *
254  * \note The iostream that is passed in \a stream may be replaced with a
255  * different one before this function returns.
256  * \note On failure, \c errno may be set providing additional information on why
257  * the failure occurred.
258  */
259 int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client);
260 
261 /*!
262  * \brief Close an iostream.
263  *
264  * \param stream A pointer to an iostream
265  *
266  * \retval 0 success
267  * \retval -1 failure
268  *
269  * \note On failure, \c errno may be set providing additional information on why
270  * the failure occurred.
271  */
272 int ast_iostream_close(struct ast_iostream *stream);
273 
274 #endif /* _ASTERISK_IOSTREAM_H */
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:149
int ast_iostream_wait_for_input(struct ast_iostream *stream, int timeout)
Wait for input on the iostream's file descriptor.
Definition: iostream.c:90
Asterisk main include file. File version handling, generic pbx functions.
int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client)
Begin TLS on an iostream.
Definition: iostream.c:627
ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count)
Write data to an iostream.
Definition: iostream.c:385
ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count)
Discard the specified number of bytes from an iostream.
Definition: iostream.c:368
void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout)
Set the iostream inactivity timeout timer.
Definition: iostream.c:122
struct ast_iostream * ast_iostream_from_fd(int *fd)
Create an iostream from a file descriptor.
Definition: iostream.c:611
int ast_iostream_get_fd(struct ast_iostream *stream)
Get an iostream's file descriptor.
Definition: iostream.c:85
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:131
ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count)
Read data from an iostream.
Definition: iostream.c:284
SSL * ast_iostream_get_ssl(struct ast_iostream *stream)
Get a pointer to an iostream's OpenSSL SSL structure.
Definition: iostream.c:109
int ast_iostream_close(struct ast_iostream *stream)
Close an iostream.
Definition: iostream.c:539
ssize_t ast_iostream_printf(struct ast_iostream *stream, const char *format,...)
Write a formatted string to an iostream.
Definition: iostream.c:502
void ast_iostream_set_timeout_disable(struct ast_iostream *stream)
Disable the iostream timeout timer.
Definition: iostream.c:114
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:140
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:311
int ast_iostream_set_sni_hostname(struct ast_iostream *stream, const char *sni_hostname)
Set the iostream's SNI hostname for TLS client connections.
Definition: iostream.c:156
void ast_iostream_nonblock(struct ast_iostream *stream)
Make an iostream non-blocking.
Definition: iostream.c:104