libguac  0.9.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Data Structures | Macros | Typedefs | Enumerations | Functions
socket.h File Reference

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...

Macros

#define GUAC_SOCKET_OUTPUT_BUFFER_SIZE   8192
 The number of bytes to buffer within each socket before flushing.
#define GUAC_SOCKET_KEEP_ALIVE_INTERVAL   5000
 The number of milliseconds to wait between keep-alive pings on a socket with keep-alive enabled.

Typedefs

typedef ssize_t guac_socket_read_handler (guac_socket *socket, void *buf, size_t count)
 Generic read handler for socket read operations, modeled after the standard POSIX read() function.
typedef ssize_t guac_socket_write_handler (guac_socket *socket, const void *buf, size_t count)
 Generic write handler for socket write operations, modeled after the standard POSIX write() function.
typedef int guac_socket_select_handler (guac_socket *socket, int usec_timeout)
 Generic handler for socket select operations, similar to the POSIX select() function.
typedef int guac_socket_free_handler (guac_socket *socket)
 Generic handler for the closing of a socket, modeled after the standard POSIX close() function.

Enumerations

enum  guac_socket_state { GUAC_SOCKET_OPEN, GUAC_SOCKET_CLOSED }
 Possible current states of a guac_socket. More...

Functions

guac_socketguac_socket_alloc ()
 Allocates a new, completely blank guac_socket.
void guac_socket_free (guac_socket *socket)
 Frees the given guac_socket and all associated resources.
void guac_socket_require_threadsafe (guac_socket *socket)
 Declares that the given socket must behave in a threadsafe way.
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.
void guac_socket_instruction_begin (guac_socket *socket)
 Marks the beginning of a Guacamole protocol instruction.
void guac_socket_instruction_end (guac_socket *socket)
 Marks the end of a Guacamole protocol instruction.
void guac_socket_update_buffer_begin (guac_socket *socket)
 Marks the beginning of a socket's buffer modification.
void guac_socket_update_buffer_end (guac_socket *socket)
 Marks the end of a socket's buffer modification.
guac_socketguac_socket_open (int fd)
 Allocates and initializes a new guac_socket object with the given open file descriptor.
guac_socketguac_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.
ssize_t guac_socket_write_int (guac_socket *socket, int64_t i)
 Writes the given unsigned int to the given guac_socket object.
ssize_t guac_socket_write_string (guac_socket *socket, const char *str)
 Writes the given string to the given guac_socket object.
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.
ssize_t guac_socket_write (guac_socket *socket, const void *buf, size_t count)
 Writes the given data to the specified socket.
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.
ssize_t guac_socket_flush_base64 (guac_socket *socket)
 Flushes the base64 buffer, writing padding characters as necessary.
ssize_t guac_socket_flush (guac_socket *socket)
 Flushes the write buffer.
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.

Detailed Description

Defines the guac_socket object and functionss for using and manipulating it.

Typedef Documentation

typedef int guac_socket_free_handler(guac_socket *socket)

Generic handler for the closing of a socket, modeled after the standard POSIX close() function.

When set within a guac_socket, a handler of this type will be called when the socket is closed.

Parameters
socketThe guac_socket being closed.
Returns
Zero on success, or -1 if an error occurs.
typedef ssize_t guac_socket_read_handler(guac_socket *socket, void *buf, size_t count)

Generic read handler for socket read operations, modeled after the standard POSIX read() function.

When set within a guac_socket, a handler of this type will be called when data needs to be read into the socket.

Parameters
socketThe guac_socket being read from.
bufThe arbitrary buffer we must populate with data.
countThe maximum number of bytes to read into the buffer.
Returns
The number of bytes read, or -1 if an error occurs.
typedef int guac_socket_select_handler(guac_socket *socket, int usec_timeout)

Generic handler for socket select operations, similar to the POSIX select() function.

When guac_socket_select() is called on a guac_socket, its guac_socket_select_handler will be invoked, if defined.

Parameters
socketThe guac_socket being selected.
usec_timeoutThe maximum number of microseconds to wait for data, or -1 to potentially wait forever.
Returns
Positive on success, zero if the timeout elapsed and no data is available, negative on error.
typedef ssize_t guac_socket_write_handler(guac_socket *socket, const void *buf, size_t count)

Generic write handler for socket write operations, modeled after the standard POSIX write() function.

When set within a guac_socket, a handler of this type will be called when data needs to be write into the socket.

Parameters
socketThe guac_socket being written to.
bufThe arbitrary buffer containing data to be written.
countThe maximum number of bytes to write from the buffer.
Returns
The number of bytes written, or -1 if an error occurs.

Enumeration Type Documentation

Possible current states of a guac_socket.

Enumerator:
GUAC_SOCKET_OPEN 

The socket is open and can be written to / read from.

GUAC_SOCKET_CLOSED 

The socket is closed.

Reads and writes will fail.

Function Documentation

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.

Returns
A newly-allocated guac_socket, or NULL if the guac_socket could not be allocated.
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.

Parameters
socketThe guac_socket object to flush
Returns
Zero on success, or non-zero if an error occurs during 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.

Parameters
socketThe guac_socket object to flush
Returns
Zero on success, or non-zero if an error occurs during flush.
void guac_socket_free ( guac_socket socket)

Frees the given guac_socket and all associated resources.

Parameters
socketThe guac_socket to free.
void guac_socket_instruction_begin ( guac_socket socket)

Marks the beginning of a Guacamole protocol instruction.

If threadsafety is enabled on the socket, other instructions will be blocked from sending until this instruction is complete.

Parameters
socketThe guac_socket beginning an instruction.
void guac_socket_instruction_end ( guac_socket socket)

Marks the end of a Guacamole protocol instruction.

If threadsafety is enabled on the socket, other instructions will be allowed to send.

Parameters
socketThe 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.

If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.

Parameters
parentThe guac_socket this new guac_socket should write nest instructions to.
indexThe stream index to use for the written nest instructions.
Returns
A newly allocated guac_socket object associated with the given guac_socket and stream index, or NULL if an error occurs while allocating the guac_socket object.
guac_socket* guac_socket_open ( int  fd)

Allocates and initializes a new guac_socket object with the given open file descriptor.

If an error occurs while allocating the guac_socket object, NULL is returned, and guac_error is set appropriately.

Parameters
fdAn open file descriptor that this guac_socket object should manage.
Returns
A newly allocated guac_socket object associated with the given file descriptor, or NULL if an error occurs while allocating the guac_socket object.
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.

Parameters
socketThe guac_socket to read from.
bufThe buffer to read bytes into.
countThe maximum number of bytes to read.
Returns
The number of bytes read, or non-zero if an error occurs while reading.
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. Enabling keep-alive automatically enables threadsafety.

Parameters
socketThe guac_socket to declare as requiring an automatic keep-alive ping.
void guac_socket_require_threadsafe ( guac_socket socket)

Declares that the given socket must behave in a threadsafe way.

Calling this function on a socket guarantees that the socket will send instructions atomically. Without automatic threadsafe sockets, multiple threads writing to the same socket must ensure that instructions will not potentially overlap.

Parameters
socketThe guac_socket to declare as threadsafe.
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.

Parameters
socketThe guac_socket object to wait for.
usec_timeoutThe maximum number of microseconds to wait for data, or -1 to potentially wait forever.
Returns
Positive on success, zero if the timeout elapsed and no data is available, negative on error.
void guac_socket_update_buffer_begin ( guac_socket socket)

Marks the beginning of a socket's buffer modification.

If threadsafety is enabled on the socket, other functions which modify the buffer will be blocked until this modification is complete.

Parameters
socketThe guac_socket whose buffer is being updated.
void guac_socket_update_buffer_end ( guac_socket socket)

Marks the end of a socket's buffer modification.

If threadsafety is enabled on the socket, other functions which modify the buffer will now be allowed to continue.

Parameters
socketThe guac_socket whose buffer is done being updated.
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 is not buffered, and will be sent immediately.

If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket object to write to.
bufA buffer containing the data to write.
countThe number of bytes to write.
Returns
Zero on success, or non-zero if an error occurs while writing.
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.

Parameters
socketThe guac_socket object to write to.
bufA buffer containing the data to write.
countThe number of bytes to write.
Returns
Zero on success, or non-zero if an error occurs while writing.
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.

Parameters
socketThe guac_socket object to write to.
iThe unsigned int to write.
Returns
Zero on success, or non-zero if an error occurs while writing.
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. Note that if the string can contain characters used internally by the Guacamole protocol (commas, semicolons, or backslashes) it will need to be escaped.

If an error occurs while writing, a non-zero value is returned, and guac_error is set appropriately.

Parameters
socketThe guac_socket object to write to.
strThe string to write.
Returns
Zero on success, or non-zero if an error occurs while writing.