libguac  1.0.0
Data Structures | Functions
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_parserguac_parser_alloc ()
 Allocates a new parser. More...
 
int guac_parser_append (guac_parser *parser, void *buffer, int length)
 Appends data from the given buffer to the given parser. More...
 
int guac_parser_length (guac_parser *parser)
 Returns the number of unparsed bytes stored in the given parser's internal buffers. More...
 
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. More...
 
void guac_parser_free (guac_parser *parser)
 Frees all memory allocated to the given parser. More...
 
int guac_parser_read (guac_parser *parser, guac_socket *socket, int usec_timeout)
 Reads a single instruction from the given guac_socket connection. More...
 
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. More...
 

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
parserThe parser to append data to.
bufferA buffer containing data that should be appended to this parser.
lengthThe 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
parserThe guac_parser to read instruction data from.
socketThe guac_socket connection to use.
usec_timeoutThe maximum number of microseconds to wait before giving up.
opcodeThe 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
parserThe 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
parserThe 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 interal 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
parserThe guac_parser to read instruction data from.
socketThe guac_socket connection to use.
usec_timeoutThe 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
parserThe parser to remove unparsed bytes from.
bufferThe buffer to store the unparsed bytes within.
lengthThe length of the given buffer.
Returns
The number of bytes stored in the given buffer.