<p>Jenkins2 <strong>merged</strong> this change.</p><p><a href="https://gerrit.asterisk.org/8888">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Richard Mudgett: Looks good to me, but someone else must approve
Joshua Colp: Looks good to me, approved
Jenkins2: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">iostreams: Add some documentation for the ast_iostream_* functions<br><br>Change-Id: Id71b87637f0a484eb5a1cd26c3d1c7c15c7dcf26<br>---<br>M include/asterisk/iostream.h<br>M main/iostream.c<br>2 files changed, 175 insertions(+), 31 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">diff --git a/include/asterisk/iostream.h b/include/asterisk/iostream.h<br>index e9816ac..b4cdeb2 100644<br>--- a/include/asterisk/iostream.h<br>+++ b/include/asterisk/iostream.h<br>@@ -44,7 +44,7 @@<br> /*!<br> * \brief Disable the iostream timeout timer.<br> *<br>- * \param stream iostream control data.<br>+ * \param stream A pointer to an iostream<br> *<br> * \return Nothing<br> */<br>@@ -53,7 +53,7 @@<br> /*!<br> * \brief Set the iostream inactivity timeout timer.<br> *<br>- * \param stream iostream control data.<br>+ * \param stream A pointer to an iostream<br> * \param timeout Number of milliseconds to wait for data transfer with the peer.<br> *<br> * \details This is basically how much time we are willing to spend<br>@@ -66,12 +66,30 @@<br> */<br> void ast_iostream_set_timeout_inactivity(struct ast_iostream *stream, int timeout);<br> <br>+/*!<br>+ * \brief Set the iostream inactivity & idle timeout timers.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param timeout Number of milliseconds to wait for initial data transfer with<br>+ * the peer.<br>+ * \param timeout_reset Number of milliseconds to wait for subsequent data<br>+ * transfer with the peer.<br>+ *<br>+ * \details As an example, if you want to timeout a peer if they do not send an<br>+ * initial message within 5 seconds or if they do not send a message at<br>+ * least every 30 seconds, you would set \a timeout to \c 5000 and<br>+ * \a timeout_reset to \c 30000.<br>+ *<br>+ * \note Setting either of these timeouts to -1 will disable them.<br>+ *<br>+ * \return Nothing<br>+ */<br> void ast_iostream_set_timeout_idle_inactivity(struct ast_iostream *stream, int timeout, int timeout_reset);<br> <br> /*!<br> * \brief Set the iostream I/O sequence timeout timer.<br> *<br>- * \param stream iostream control data.<br>+ * \param stream A pointer to an iostream<br> * \param start Time the I/O sequence timer starts.<br> * \param timeout Number of milliseconds from the start time before timeout.<br> *<br>@@ -89,7 +107,7 @@<br> /*!<br> * \brief Set the iostream if it can exclusively depend upon the set timeouts.<br> *<br>- * \param stream iostream control data.<br>+ * \param stream A pointer to an iostream<br> * \param exclusive_input TRUE if stream can exclusively wait for fd input.<br> * Otherwise, the stream will not wait for fd input. It will wait while<br> * trying to send data.<br>@@ -100,20 +118,146 @@<br> */<br> void ast_iostream_set_exclusive_input(struct ast_iostream *stream, int exclusive_input);<br> <br>+/*!<br>+ * \brief Get an iostream's file descriptor.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ *<br>+ * \return The file descriptor for the given iostream, or -1 if the iostream has no open<br>+ * file descriptor.<br>+ */<br> int ast_iostream_get_fd(struct ast_iostream *stream);<br>+<br>+/*!<br>+ * \brief Make an iostream non-blocking.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ *<br>+ * \return Nothing<br>+ */<br> void ast_iostream_nonblock(struct ast_iostream *stream);<br> <br>-SSL* ast_iostream_get_ssl(struct ast_iostream *stream);<br>+/*!<br>+ * \brief Get a pointer to an iostream's OpenSSL \c SSL structure<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ *<br>+ * \return A pointer to the OpenSSL \c SSL structure for the given iostream, or<br>+ * \c NULL if TLS has not been initiated.<br>+ *<br>+ * \note If OpenSSL support is not included in the build, this will always return<br>+ * \c NULL.<br>+ */<br>+SSL *ast_iostream_get_ssl(struct ast_iostream *stream);<br> <br>-ssize_t ast_iostream_read(struct ast_iostream *stream, void *buf, size_t count);<br>-ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buf, size_t count);<br>+/*!<br>+ * \brief Read data from an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param buffer Pointer to a buffer to store the read bytes.<br>+ * \param count The number of bytes to read.<br>+ *<br>+ * \return Upon successful completion, returns a non-negative integer indicating<br>+ * the number of bytes actually read. Otherwise, returns -1 and may set<br>+ * errno to indicate the error.<br>+ */<br>+ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count);<br>+<br>+/*!<br>+ * \brief Read a LF-terminated string from an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param buffer Pointer to a buffer to store the read bytes.<br>+ * \param size The total size of \a buffer in bytes.<br>+ *<br>+ * \return The number of bytes stored in \a buffer, excluding the null byte used<br>+ * to terminate the string. If the size of \a buffer (indicated by the<br>+ * caller with the \a size argument) is not sufficient to store the<br>+ * entire line it will be truncated to fit the available space. The<br>+ * contents of \a buffer will always be terminated with a null byte. In<br>+ * the case of an error, \c -1 will be returned and \c errno may be set<br>+ * indicating the error.<br>+ */<br>+ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size);<br>+<br>+/*!<br>+ * \brief Discard the specified number of bytes from an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param count The number of bytes to discard.<br>+ *<br>+ * \return Upon successful completion, returns the number of bytes discarded.<br>+ * Otherwise, \c -1 is returned and \c errno may be set indicating the<br>+ * error.<br>+ */<br> ssize_t ast_iostream_discard(struct ast_iostream *stream, size_t count);<br>-ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buf, size_t count);<br>-ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(<br>- struct ast_iostream *stream, const char *fmt, ...);<br> <br>-struct ast_iostream* ast_iostream_from_fd(int *fd);<br>+/*!<br>+ * \brief Write data to an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param buffer Pointer to a buffer from which to read bytes.<br>+ * \param count The number of bytes from \a buffer to write.<br>+ *<br>+ * \return Upon successful completion, returns the number of bytes actually<br>+ * written to the iostream. This number shall never be greater than<br>+ * \a count. Otherwise, returns \c -1 and may set \c errno to indicate<br>+ * the error.<br>+ */<br>+ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t count);<br>+<br>+/*!<br>+ * \brief Write a formatted string to an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ * \param format A format string, as documented by printf(3)<br>+ * \param ... Arguments for the provided \a format string<br>+ *<br>+ * \return The number of bytes written, or \c -1 if an error occurs. Note that if<br>+ * \c -1 is returned, the number of bytes written to the iostream is<br>+ * unspecified.<br>+ */<br>+ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(<br>+ struct ast_iostream *stream, const char *format, ...);<br>+<br>+/*!<br>+ * \brief Create an iostream from a file descriptor.<br>+ *<br>+ * \param fd A pointer to an open file descriptor<br>+ *<br>+ * \return A newly allocated iostream or \c NULL if allocation fails.<br>+ */<br>+struct ast_iostream *ast_iostream_from_fd(int *fd);<br>+<br>+/*!<br>+ * \brief Begin TLS on an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream pointer<br>+ * \param ctx A pointer to an \c SSL_CTX which will be passed to \c SSL_new()<br>+ * \param client Non-zero to indicate that we are the client, zero to indicate<br>+ * that we are the server.<br>+ *<br>+ * \retval 0 success<br>+ * \retval -1 failure<br>+ *<br>+ * \note The iostream that is passed in \a stream may be replaced with a<br>+ * different one before this function returns.<br>+ * \note On failure, \c errno may be set providing additional information on why<br>+ * the failure occurred.<br>+ */<br> int ast_iostream_start_tls(struct ast_iostream **stream, SSL_CTX *ctx, int client);<br>+<br>+/*!<br>+ * \brief Close an iostream.<br>+ *<br>+ * \param stream A pointer to an iostream<br>+ *<br>+ * \retval 0 success<br>+ * \retval -1 failure<br>+ *<br>+ * \note On failure, \c errno may be set providing additional information on why<br>+ * the failure occurred.<br>+ */<br> int ast_iostream_close(struct ast_iostream *stream);<br> <br> #endif /* _ASTERISK_IOSTREAM_H */<br>diff --git a/main/iostream.c b/main/iostream.c<br>index aaa74fa..4cddd43 100644<br>--- a/main/iostream.c<br>+++ b/main/iostream.c<br>@@ -238,9 +238,9 @@<br> }<br> }<br> <br>-ssize_t ast_iostream_read(struct ast_iostream *stream, void *buf, size_t size)<br>+ssize_t ast_iostream_read(struct ast_iostream *stream, void *buffer, size_t count)<br> {<br>- if (!size) {<br>+ if (!count) {<br> /* You asked for no data you got no data. */<br> return 0;<br> }<br>@@ -252,20 +252,20 @@<br> <br> /* Get any remains from the read buffer */<br> if (stream->rbuflen) {<br>- size_t r = size;<br>+ size_t r = count;<br> if (r > stream->rbuflen) {<br> r = stream->rbuflen;<br> }<br>- memcpy(buf, stream->rbufhead, r);<br>+ memcpy(buffer, stream->rbufhead, r);<br> stream->rbuflen -= r;<br> stream->rbufhead += r;<br> return r;<br> }<br> <br>- return iostream_read(stream, buf, size);<br>+ return iostream_read(stream, buffer, count);<br> }<br> <br>-ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buf, size_t count)<br>+ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buffer, size_t size)<br> {<br> ssize_t r;<br> char *newline;<br>@@ -275,15 +275,15 @@<br> newline = memchr(stream->rbufhead, '\n', stream->rbuflen);<br> if (newline) {<br> r = newline - stream->rbufhead + 1;<br>- if (r > count-1) {<br>- r = count-1;<br>+ if (r > size-1) {<br>+ r = size-1;<br> }<br> break;<br> }<br> <br> /* Enough data? */<br>- if (stream->rbuflen >= count - 1) {<br>- r = count - 1;<br>+ if (stream->rbuflen >= size - 1) {<br>+ r = size - 1;<br> break;<br> }<br> <br>@@ -301,8 +301,8 @@<br> } while (1);<br> <br> /* Return r bytes with termination byte */<br>- memcpy(buf, stream->rbufhead, r);<br>- buf[r] = 0;<br>+ memcpy(buffer, stream->rbufhead, r);<br>+ buffer[r] = 0;<br> stream->rbuflen -= r;<br> stream->rbufhead += r;<br> <br>@@ -326,7 +326,7 @@<br> return size;<br> }<br> <br>-ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buf, size_t size)<br>+ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buffer, size_t size)<br> {<br> struct timeval start;<br> int ms;<br>@@ -357,7 +357,7 @@<br> for (;;) {<br> int sslerr;<br> char err[256];<br>- res = SSL_write(stream->ssl, buf + written, remaining);<br>+ res = SSL_write(stream->ssl, buffer + written, remaining);<br> if (res == remaining) {<br> /* Everything was written. */<br> return size;<br>@@ -414,7 +414,7 @@<br> written = 0;<br> remaining = size;<br> for (;;) {<br>- res = write(stream->fd, buf + written, remaining);<br>+ res = write(stream->fd, buffer + written, remaining);<br> if (res == remaining) {<br> /* Yay everything was written. */<br> return size;<br>@@ -443,14 +443,14 @@<br> }<br> }<br> <br>-ssize_t ast_iostream_printf(struct ast_iostream *stream, const char *fmt, ...)<br>+ssize_t ast_iostream_printf(struct ast_iostream *stream, const char *format, ...)<br> {<br> char sbuf[512], *buf = sbuf;<br> int len, len2, ret = -1;<br> va_list va;<br> <br>- va_start(va, fmt);<br>- len = vsnprintf(buf, sizeof(sbuf), fmt, va);<br>+ va_start(va, format);<br>+ len = vsnprintf(buf, sizeof(sbuf), format, va);<br> va_end(va);<br> <br> if (len > sizeof(sbuf) - 1) {<br>@@ -461,8 +461,8 @@<br> if (!buf) {<br> return -1;<br> }<br>- va_start(va, fmt);<br>- len2 = vsnprintf(buf, buf_len, fmt, va);<br>+ va_start(va, format);<br>+ len2 = vsnprintf(buf, buf_len, format, va);<br> va_end(va);<br> if (len2 != len) {<br> goto error;<br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/8888">change 8888</a>. To unsubscribe, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/8888"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 15 </div>
<div style="display:none"> Gerrit-MessageType: merged </div>
<div style="display:none"> Gerrit-Change-Id: Id71b87637f0a484eb5a1cd26c3d1c7c15c7dcf26 </div>
<div style="display:none"> Gerrit-Change-Number: 8888 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: Sean Bright <sean.bright@gmail.com> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins2 </div>
<div style="display:none"> Gerrit-Reviewer: Joshua Colp <jcolp@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Richard Mudgett <rmudgett@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Sean Bright <sean.bright@gmail.com> </div>