instruction.h File Reference

Provides functions and structures for reading, writing, and manipulating Guacamole instructions. More...

Go to the source code of this file.

Data Structures
struct	guac_instruction
	Represents a single instruction within the Guacamole protocol. More...

Macros
#define	GUAC_INSTRUCTION_MAX_LENGTH   8192
	The maximum number of characters per instruction.
#define	GUAC_INSTRUCTION_MAX_DIGITS   5
	The maximum number of digits to allow per length prefix.
#define	GUAC_INSTRUCTION_MAX_ELEMENTS   64
	The maximum number of elements per instruction, including the opcode.

Enumerations
enum	guac_instruction_parse_state { GUAC_INSTRUCTION_PARSE_LENGTH, GUAC_INSTRUCTION_PARSE_CONTENT, GUAC_INSTRUCTION_PARSE_COMPLETE, GUAC_INSTRUCTION_PARSE_ERROR }
	All possible states of the instruction parser. More...

Functions
guac_instruction *	guac_instruction_alloc ()
	Allocates a new instruction.
void	guac_instruction_reset (guac_instruction *instruction)
	Resets the parse state and contents of the given instruction, such that the memory of that instruction can be reused for another parse cycle.
int	guac_instruction_append (guac_instruction *instruction, void *buffer, int length)
	Appends data from the given buffer to the given instruction.
void	guac_instruction_free (guac_instruction *instruction)
	Frees all memory allocated to the given instruction.
int	guac_instruction_waiting (guac_socket *socket, int usec_timeout)
	Returns whether new instruction data is available on the given guac_socket connection for parsing.
guac_instruction *	guac_instruction_read (guac_socket *socket, int usec_timeout)
	Reads a single instruction from the given guac_socket connection.
guac_instruction *	guac_instruction_expect (guac_socket *socket, int usec_timeout, const char *opcode)
	Reads a single instruction with the given opcode from the given guac_socket connection.

Detailed Description

Provides functions and structures for reading, writing, and manipulating Guacamole instructions.

Enumeration Type Documentation

enum guac_instruction_parse_state

All possible states of the instruction parser.

Enumerator:

GUAC_INSTRUCTION_PARSE_LENGTH	The parser is currently waiting for data to complete the length prefix of the current element of the instruction.
GUAC_INSTRUCTION_PARSE_CONTENT	The parser has finished reading the length prefix and is currently waiting for data to complete the content of the instruction.
GUAC_INSTRUCTION_PARSE_COMPLETE	The instruction has been fully parsed.
GUAC_INSTRUCTION_PARSE_ERROR	The instruction cannot be parsed because of a protocol error.

Function Documentation

guac_instruction* guac_instruction_alloc

(

)

Allocates a new instruction.

Each instruction contains within itself the necessary facilities to parse instruction data.

Returns

The newly allocated instruction, or NULL if an error occurs during allocation, in which case guac_error will be set appropriately.

int guac_instruction_append	(	guac_instruction *	instruction,
		void *	buffer,
		int	length
	)

Appends data from the given buffer to the given instruction.

The data will be appended, if possible, to this instruction as a reference and thus the buffer must remain valid throughout the life of the instruction. This function may modify the contents of the buffer when those contents are part of an element within the instruction being read.

Parameters

instruction	The instruction to append data to.
buffer	A buffer containing data that should be appended to this instruction.
length	The number of bytes available for appending within the buffer.

Returns

The number of bytes appended to this instruction, which may be zero if more data is needed.

guac_instruction* guac_instruction_expect	(	guac_socket *	socket,
		int	usec_timeout,
		const char *	opcode
	)

Reads a single instruction with the given opcode from the given guac_socket connection.

If an error occurs reading the instruction, NULL is returned, and guac_error is set appropriately.

If the instruction read is not the expected instruction, NULL is returned, and guac_error is set to GUAC_STATUS_BAD_STATE.

Parameters

socket	The guac_socket connection to use.
usec_timeout	The maximum number of microseconds to wait before giving up.
opcode	The opcode of the instruction to read.

Returns

A new instruction if an instruction with the given opcode was read, NULL otherwise. If an instruction was read, but the instruction had a different opcode, NULL is returned and guac_error is set to GUAC_STATUS_BAD_STATE.

void guac_instruction_free

(

guac_instruction *

instruction

)

Frees all memory allocated to the given instruction.

Parameters

instruction

The instruction to free.

guac_instruction* guac_instruction_read	(	guac_socket *	socket,
		int	usec_timeout
	)

Reads a single instruction from the given guac_socket connection.

If an error occurs reading the instruction, NULL is returned, and guac_error is set appropriately.

Parameters

socket	The guac_socket connection to use.
usec_timeout	The maximum number of microseconds to wait before giving up.

Returns

A new instruction if data was successfully read, NULL on error or if the instruction could not be read completely because the timeout elapsed, in which case guac_error will be set to GUAC_STATUS_INPUT_TIMEOUT and subsequent calls to guac_protocol_read_instruction() will return the parsed instruction once enough data is available.

void guac_instruction_reset

(

guac_instruction *

instruction

)

Resets the parse state and contents of the given instruction, such that the memory of that instruction can be reused for another parse cycle.

Parameters

instruction

The instruction to reset.

int guac_instruction_waiting	(	guac_socket *	socket,
		int	usec_timeout
	)

Returns whether new instruction data is available on the given guac_socket connection for parsing.

Parameters

socket	The guac_socket connection to use.
usec_timeout	The maximum number of microseconds to wait before giving up.

Returns

A positive value if data is available, negative on error, or zero if no data is currently available.