GUAC-1389: Add missing documentation for socket handlers.

This commit is contained in:
Michael Jumper 2016-03-01 13:02:42 -08:00
parent 7653fa106e
commit 14522dab22
2 changed files with 69 additions and 0 deletions

View File

@ -129,6 +129,22 @@ ssize_t guac_socket_fd_write(guac_socket* socket,
}
/**
* Attempts to read from the underlying file descriptor of the given
* guac_socket, populating the given buffer.
*
* @param socket
* The guac_socket being read from.
*
* @param buf
* The arbitrary buffer which we must populate with data.
*
* @param count
* The maximum number of bytes to read into the buffer.
*
* @return
* The number of bytes read, or -1 if an error occurs.
*/
static ssize_t guac_socket_fd_read_handler(guac_socket* socket,
void* buf, size_t count) {
@ -176,6 +192,16 @@ static ssize_t guac_socket_fd_flush(guac_socket* socket) {
}
/**
* Flushes the internal buffer of the given guac_socket, writing all data
* to the underlying file descriptor.
*
* @param socket
* The guac_socket to flush.
*
* @return
* Zero if the flush operation was successful, non-zero otherwise.
*/
static ssize_t guac_socket_fd_flush_handler(guac_socket* socket) {
int retval;
@ -258,6 +284,23 @@ static ssize_t guac_socket_fd_write_buffered(guac_socket* socket,
}
/**
* Appends the provided data to the internal buffer for future writing. The
* actual write attempt will occur only upon flush, or when the internal buffer
* is full.
*
* @param socket
* The guac_socket being write to.
*
* @param buf
* The arbitrary buffer containing the data to be written.
*
* @param count
* The number of bytes contained within the buffer.
*
* @return
* The number of bytes written, or -1 if an error occurs.
*/
static ssize_t guac_socket_fd_write_handler(guac_socket* socket,
const void* buf, size_t count) {
@ -277,6 +320,21 @@ static ssize_t guac_socket_fd_write_handler(guac_socket* socket,
}
/**
* Waits for data on the underlying file desriptor of the given socket to
* become available such that the next read operation will not block.
*
* @param socket
* The guac_socket to wait for.
*
* @param usec_timeout
* The maximum amount of time to wait for data, in microseconds, or -1 to
* potentially wait forever.
*
* @return
* A positive value on success, zero if the timeout elapsed and no data is
* available, or a negative value if an error occurs.
*/
static int guac_socket_fd_select_handler(guac_socket* socket,
int usec_timeout) {

View File

@ -105,6 +105,17 @@ ssize_t __guac_socket_nest_write_handler(guac_socket* socket,
}
/**
* Frees all implementation-specific data associated with the given socket, but
* not the socket object itself.
*
* @param socket
* The guac_socket whose associated data should be freed.
*
* @return
* Zero if the data was successfully freed, non-zero otherwise. This
* implementation always succeeds, and will always return zero.
*/
static int __guac_socket_nest_free_handler(guac_socket* socket) {
/* Free associated data */