libguac
0.9.13-incubating
|
Defines the guac_socket object and functionss for using and manipulating it. More...
Go to the source code of this file.
Data Structures | |
struct | guac_socket |
The core I/O object of Guacamole. More... | |
Functions | |
guac_socket * | guac_socket_alloc () |
Allocates a new, completely blank guac_socket. More... | |
void | guac_socket_free (guac_socket *socket) |
Frees the given guac_socket and all associated resources. More... | |
void | guac_socket_require_keep_alive (guac_socket *socket) |
Declares that the given socket must automatically send a keep-alive ping to ensure neither side of the socket times out while the socket is open. More... | |
void | guac_socket_instruction_begin (guac_socket *socket) |
Marks the beginning of a Guacamole protocol instruction. More... | |
void | guac_socket_instruction_end (guac_socket *socket) |
Marks the end of a Guacamole protocol instruction. More... | |
guac_socket * | guac_socket_open (int fd) |
Allocates and initializes a new guac_socket object with the given open file descriptor. More... | |
guac_socket * | guac_socket_nest (guac_socket *parent, int index) |
Allocates and initializes a new guac_socket which writes all data via nest instructions to the given existing, open guac_socket. More... | |
guac_socket * | guac_socket_tee (guac_socket *primary, guac_socket *secondary) |
Allocates and initializes a new guac_socket which delegates all socket operations to the given primary socket, while simultaneously duplicating all written data to the secondary socket. More... | |
guac_socket * | guac_socket_broadcast (guac_client *client) |
Allocates and initializes a new guac_socket which duplicates all instructions written across the sockets of each connected user of the given guac_client. More... | |
ssize_t | guac_socket_write_int (guac_socket *socket, int64_t i) |
Writes the given unsigned int to the given guac_socket object. More... | |
ssize_t | guac_socket_write_string (guac_socket *socket, const char *str) |
Writes the given string to the given guac_socket object. More... | |
ssize_t | guac_socket_write_base64 (guac_socket *socket, const void *buf, size_t count) |
Writes the given binary data to the given guac_socket object as base64- encoded data. More... | |
ssize_t | guac_socket_write (guac_socket *socket, const void *buf, size_t count) |
Writes the given data to the specified socket. More... | |
ssize_t | guac_socket_read (guac_socket *socket, void *buf, size_t count) |
Attempts to read data from the socket, filling up to the specified number of bytes in the given buffer. More... | |
ssize_t | guac_socket_flush_base64 (guac_socket *socket) |
Flushes the base64 buffer, writing padding characters as necessary. More... | |
ssize_t | guac_socket_flush (guac_socket *socket) |
Flushes the write buffer. More... | |
int | guac_socket_select (guac_socket *socket, int usec_timeout) |
Waits for input to be available on the given guac_socket object until the specified timeout elapses. More... | |
Defines the guac_socket object and functionss for using and manipulating it.
guac_socket* guac_socket_alloc | ( | ) |
Allocates a new, completely blank guac_socket.
This guac_socket will do absolutely nothing when used unless its handlers are defined.
guac_socket* guac_socket_broadcast | ( | guac_client * | client | ) |
Allocates and initializes a new guac_socket which duplicates all instructions written across the sockets of each connected user of the given guac_client.
The returned socket is a write-only socket. Attempts to read from the socket will fail. If a write occurs while no users are connected, that write will simply be dropped.
Return values (error codes) from each user's socket will not affect the in-progress write, but each failing user will be forcibly stopped with guac_user_stop().
If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.
client | The client associated with the group of connected users across which duplicates of all instructions should be written. |
ssize_t guac_socket_flush | ( | guac_socket * | socket | ) |
Flushes the write buffer.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to flush |
ssize_t guac_socket_flush_base64 | ( | guac_socket * | socket | ) |
Flushes the base64 buffer, writing padding characters as necessary.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to flush |
void guac_socket_free | ( | guac_socket * | socket | ) |
Frees the given guac_socket and all associated resources.
socket | The guac_socket to free. |
void guac_socket_instruction_begin | ( | guac_socket * | socket | ) |
Marks the beginning of a Guacamole protocol instruction.
socket | The guac_socket beginning an instruction. |
void guac_socket_instruction_end | ( | guac_socket * | socket | ) |
Marks the end of a Guacamole protocol instruction.
socket | The guac_socket ending an instruction. |
guac_socket* guac_socket_nest | ( | guac_socket * | parent, |
int | index | ||
) |
Allocates and initializes a new guac_socket which writes all data via nest instructions to the given existing, open guac_socket.
Freeing the returned guac_socket has no effect on the underlying, nested guac_socket.
If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.
parent | The guac_socket this new guac_socket should write nest instructions to. |
index | The stream index to use for the written nest instructions. |
guac_socket* guac_socket_open | ( | int | fd | ) |
Allocates and initializes a new guac_socket object with the given open file descriptor.
The file descriptor will be automatically closed when the allocated guac_socket is freed.
If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.
fd | An open file descriptor that this guac_socket object should manage. |
ssize_t guac_socket_read | ( | guac_socket * | socket, |
void * | buf, | ||
size_t | count | ||
) |
Attempts to read data from the socket, filling up to the specified number of bytes in the given buffer.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket to read from. |
buf | The buffer to read bytes into. |
count | The maximum number of bytes to read. |
void guac_socket_require_keep_alive | ( | guac_socket * | socket | ) |
Declares that the given socket must automatically send a keep-alive ping to ensure neither side of the socket times out while the socket is open.
This ping will take the form of a "nop" instruction.
socket | The guac_socket to declare as requiring an automatic keep-alive ping. |
int guac_socket_select | ( | guac_socket * | socket, |
int | usec_timeout | ||
) |
Waits for input to be available on the given guac_socket object until the specified timeout elapses.
If an error occurs while waiting, a negative value is returned, and guac_error is set appropriately.
If a timeout occurs while waiting, zero value is returned, and guac_error is set to GUAC_STATUS_INPUT_TIMEOUT.
socket | The guac_socket object to wait for. |
usec_timeout | The maximum number of microseconds to wait for data, or -1 to potentially wait forever. |
guac_socket* guac_socket_tee | ( | guac_socket * | primary, |
guac_socket * | secondary | ||
) |
Allocates and initializes a new guac_socket which delegates all socket operations to the given primary socket, while simultaneously duplicating all written data to the secondary socket.
Freeing the returned guac_socket will free both primary and secondary sockets.
Return values (error codes) will come only from the primary socket. Locks (like those used by guac_socket_instruction_begin() and guac_socket_instruction_end()) will affect only the primary socket.
If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.
primary | The primary guac_socket to which all socket operations should be delegated. The error codes returned by socket operations, if any, will always come from this socket. This socket will also be the only socket locked when instructions begin (or unlocked when instructions end). |
secondary | The secondary guac_socket to which all data written to the primary guac_socket should be copied. If an error prevents the write from succeeding, that error will be ignored. Only errors from the primary guac_socket will be acknowledged. |
ssize_t guac_socket_write | ( | guac_socket * | socket, |
const void * | buf, | ||
size_t | count | ||
) |
Writes the given data to the specified socket.
The data written may be buffered until the buffer is flushed automatically or manually.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to write to. |
buf | A buffer containing the data to write. |
count | The number of bytes to write. |
ssize_t guac_socket_write_base64 | ( | guac_socket * | socket, |
const void * | buf, | ||
size_t | count | ||
) |
Writes the given binary data to the given guac_socket object as base64- encoded data.
The data written may be buffered until the buffer is flushed automatically or manually. Beware that, because base64 data is buffered on top of the write buffer already used, a call to guac_socket_flush_base64() MUST be made before non-base64 writes (or writes of an independent block of base64 data) can be made.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to write to. |
buf | A buffer containing the data to write. |
count | The number of bytes to write. |
ssize_t guac_socket_write_int | ( | guac_socket * | socket, |
int64_t | i | ||
) |
Writes the given unsigned int to the given guac_socket object.
The data written may be buffered until the buffer is flushed automatically or manually.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to write to. |
i | The unsigned int to write. |
ssize_t guac_socket_write_string | ( | guac_socket * | socket, |
const char * | str | ||
) |
Writes the given string to the given guac_socket object.
The data written may be buffered until the buffer is flushed automatically or manually.
If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.
socket | The guac_socket object to write to. |
str | The string to write. |