[Asterisk-code-review] iostreams: Add some documentation for the ast iostream * fun... (asterisk[15])
Sean Bright
asteriskteam at digium.com
Tue May 1 16:09:15 CDT 2018
Sean Bright has uploaded this change for review. ( https://gerrit.asterisk.org/8888
Change subject: iostreams: Add some documentation for the ast_iostream_* functions
......................................................................
iostreams: Add some documentation for the ast_iostream_* functions
Change-Id: Id71b87637f0a484eb5a1cd26c3d1c7c15c7dcf26
---
M include/asterisk/iostream.h
1 file changed, 150 insertions(+), 17 deletions(-)
git pull ssh://gerrit.asterisk.org:29418/asterisk refs/changes/88/8888/1
diff --git a/include/asterisk/iostream.h b/include/asterisk/iostream.h
index e9816ac..1b07cde 100644
--- a/include/asterisk/iostream.h
+++ b/include/asterisk/iostream.h
@@ -44,7 +44,7 @@
/*!
* \brief Disable the iostream timeout timer.
*
- * \param stream iostream control data.
+ * \param stream A pointer to an iostream
*
* \return Nothing
*/
@@ -53,7 +53,7 @@
/*!
* \brief Set the iostream inactivity timeout timer.
*
- * \param stream iostream control data.
+ * \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
@@ -61,17 +61,31 @@
*
* \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 \c timeout to \c 5000 and
+ * \c timeout_reset to \c 30000.
+ *
+ * \note Setting either of these timeouts to -1 will disable them.
+ */
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 iostream control data.
+ * \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.
*
@@ -81,39 +95,158 @@
*
* \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 iostream control data.
+ * \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 Make an iostream non-blocking.
+ *
+ * \param stream A pointer to an iostream
+ */
void ast_iostream_nonblock(struct ast_iostream *stream);
-SSL* ast_iostream_get_ssl(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);
-ssize_t ast_iostream_read(struct ast_iostream *stream, void *buf, size_t count);
-ssize_t ast_iostream_gets(struct ast_iostream *stream, char *buf, size_t count);
+/*!
+ * \brief Read data from an iostream.
+ *
+ * \param stream A pointer to an iostream
+ * \param buf 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 buf Pointer to a buffer to store the read bytes.
+ * \param size The total size of \c buf in bytes.
+ *
+ * \return The number of bytes stored in \c buf, excluding the null byte used to
+ * terminate the string. If the size of \c buf (indicated by the caller
+ * with the \c count argument) is not sufficient to store the entire line
+ * it will be truncated to fit the available space. The contents of \c buf
+ * 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);
-ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buf, size_t count);
-ssize_t __attribute__((format(printf, 2, 3))) ast_iostream_printf(
- struct ast_iostream *stream, const char *fmt, ...);
-struct ast_iostream* ast_iostream_from_fd(int *fd);
+/*!
+ * \brief Write data to an iostream.
+ *
+ * \param stream A pointer to an iostream
+ * \param buf Pointer to a buffer from which to read bytes.
+ * \param count The number of bytes from \c buf to write.
+ *
+ * \return Upon successful completion, returns the number of bytes actually
+ * written to the iostream. This number shall never be greater than
+ * \c count. Otherwise, returns -1 and may set \c errno to indicate
+ * the error.
+ */
+ssize_t ast_iostream_write(struct ast_iostream *stream, const void *buf, 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 \c 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 \c iostream that is passed in \c 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 */
--
To view, visit https://gerrit.asterisk.org/8888
To unsubscribe, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 15
Gerrit-MessageType: newchange
Gerrit-Change-Id: Id71b87637f0a484eb5a1cd26c3d1c7c15c7dcf26
Gerrit-Change-Number: 8888
Gerrit-PatchSet: 1
Gerrit-Owner: Sean Bright <sean.bright at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20180501/baf7b659/attachment-0001.html>
More information about the asterisk-code-review
mailing list