parser.h File Reference

Provides functions and structures for parsing the Guacamole protocol. More...

Go to the source code of this file.

Data Structures
struct	guac_parser
	A Guacamole protocol parser, which reads individual instructions, filling its own internal structure with the most recently read instruction data. More...

Functions
guac_parser *	guac_parser_alloc ()
	Allocates a new parser.
int	guac_parser_append (guac_parser *parser, void *buffer, int length)
	Appends data from the given buffer to the given parser.
int	guac_parser_length (guac_parser *parser)
	Returns the number of unparsed bytes stored in the given parser's internal buffers.
int	guac_parser_shift (guac_parser *parser, void *buffer, int length)
	Removes up to length bytes from internal buffer of unparsed bytes, storing them in the given buffer.
void	guac_parser_free (guac_parser *parser)
	Frees all memory allocated to the given parser.
int	guac_parser_read (guac_parser *parser, guac_socket *socket, int usec_timeout)
	Reads a single instruction from the given guac_socket connection.
int	guac_parser_expect (guac_parser *parser, guac_socket *socket, int usec_timeout, const char *opcode)
	Reads a single instruction from the given guac_socket.

Detailed Description

Provides functions and structures for parsing the Guacamole protocol.

Function Documentation

guac_parser_alloc()

guac_parser * guac_parser_alloc

(

)

Allocates a new parser.

Returns

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

guac_parser_append()

int guac_parser_append	(	guac_parser *	parser,
		void *	buffer,
		int	length )

Appends data from the given buffer to the given parser.

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

Parameters

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

Returns

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

guac_parser_expect()

int guac_parser_expect	(	guac_parser *	parser,
		guac_socket *	socket,
		int	usec_timeout,
		const char *	opcode )

Reads a single instruction from the given guac_socket.

This operates identically to guac_parser_read(), except that an error is returned if the expected opcode is not received.

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

parser	The guac_parser to read instruction data from.
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

Zero if an instruction with the given opcode was read, non-zero otherwise. If an instruction was read, but the instruction had a different opcode, non-zero is returned and guac_error is set to GUAC_STATUS_BAD_STATE.

guac_parser_free()

void guac_parser_free

(

guac_parser *

parser

)

Frees all memory allocated to the given parser.

Parameters

parser

The parser to free.

guac_parser_length()

int guac_parser_length

(

guac_parser *

parser

)

Returns the number of unparsed bytes stored in the given parser's internal buffers.

Parameters

parser

The parser to return the length of.

Returns

The number of unparsed bytes stored in the given parser.

guac_parser_read()

int guac_parser_read	(	guac_parser *	parser,
		guac_socket *	socket,
		int	usec_timeout )

Reads a single instruction from the given guac_socket connection.

This may result in additional data being read from the guac_socket, stored internally within a buffer for future parsing. Future calls to guac_parser_read() will read from the internal buffer before reading from the guac_socket. Data from the internal buffer can be removed and used elsewhere through guac_parser_shift().

If an error occurs reading the instruction, non-zero is returned, and guac_error is set appropriately.

Parameters

parser	The guac_parser to read instruction data from.
socket	The guac_socket connection to use.
usec_timeout	The maximum number of microseconds to wait before giving up.

Returns

Zero if an instruction was read within the time allowed, or non-zero if no instruction could be read. 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 additional calls to guac_parser_read() will be required.

guac_parser_shift()

int guac_parser_shift	(	guac_parser *	parser,
		void *	buffer,
		int	length )

Removes up to length bytes from internal buffer of unparsed bytes, storing them in the given buffer.

Parameters

parser	The parser to remove unparsed bytes from.
buffer	The buffer to store the unparsed bytes within.
length	The length of the given buffer.

Returns

The number of bytes stored in the given buffer.