recording.h File Reference

Provides functions and structures to be use for session recording. More...

Go to the source code of this file.

Data Structures
struct	guac_recording
	An in-progress session recording, attached to a guac_client instance such that output Guacamole instructions may be dynamically intercepted and written to a file. More...

Macros
#define	GUAC_COMMON_RECORDING_MAX_SUFFIX   255
	The maximum numeric value allowed for the .1, .2, .3, etc.
#define	GUAC_COMMON_RECORDING_MAX_SUFFIX_LENGTH   4
	The maximum length of the string containing a sequential numeric suffix between 1 and GUAC_COMMON_RECORDING_MAX_SUFFIX inclusive, in bytes, including NULL terminator.
#define	GUAC_COMMON_RECORDING_MAX_NAME_LENGTH   2048
	The maximum overall length of the full path to the session recording file, including any additional suffix and NULL terminator, in bytes.

Functions
guac_recording *	guac_recording_create (guac_client *client, const char *path, const char *name, int create_path, int include_output, int include_mouse, int include_touch, int include_keys)
	Replaces the socket of the given client such that all further Guacamole protocol output will be copied into a file within the given path and having the given name.
void	guac_recording_free (guac_recording *recording)
	Frees the resources associated with the given in-progress recording.
void	guac_recording_report_mouse (guac_recording *recording, int x, int y, int button_mask)
	Reports the current mouse position and button state within the recording.
void	guac_recording_report_touch (guac_recording *recording, int id, int x, int y, int x_radius, int y_radius, double angle, double force)
	Reports the current state of a touch contact within the recording.
void	guac_recording_report_key (guac_recording *recording, int keysym, int pressed)
	Reports a change in the state of an individual key within the recording.

Detailed Description

Provides functions and structures to be use for session recording.

Macro Definition Documentation

GUAC_COMMON_RECORDING_MAX_SUFFIX

#define GUAC_COMMON_RECORDING_MAX_SUFFIX   255

The maximum numeric value allowed for the .1, .2, .3, etc.

suffix appended to the end of the session recording filename if a recording having the requested name already exists.

Function Documentation

guac_recording_create()

guac_recording * guac_recording_create	(	guac_client *	client,
		const char *	path,
		const char *	name,
		int	create_path,
		int	include_output,
		int	include_mouse,
		int	include_touch,
		int	include_keys )

Replaces the socket of the given client such that all further Guacamole protocol output will be copied into a file within the given path and having the given name.

If the create_path flag is non-zero, the given path will be created if it does not yet exist. If creation of the recording file or path fails, error messages will automatically be logged, and no recording will be written. The recording will automatically be closed once the client is freed.

Parameters

client	The client whose output should be copied to a recording file.
path	The full absolute path to a directory in which the recording file should be created.
name	The base name to use for the recording file created within the specified path.
create_path	Zero if the specified path MUST exist for the recording file to be written, or non-zero if the path should be created if it does not yet exist.
include_output	Non-zero if output which is broadcast to each connected client (graphics, streams, etc.) should be included in the session recording, zero otherwise. Including output is necessary for any recording which must later be viewable as video.
include_mouse	Non-zero if changes to mouse state, such as position and buttons pressed or released, should be included in the session recording, zero otherwise. Including mouse state is necessary for the mouse cursor to be rendered in any resulting video.
include_touch	Non-zero if touch events should be included in the session recording, zero otherwise. Depending on whether the remote desktop will automatically provide graphical feedback for touches, including touch events may be necessary for multi-touch interactions to be rendered in any resulting video.
include_keys	Non-zero if keys pressed and released should be included in the session recording, zero otherwise. Including key events within the recording may be necessary in certain auditing contexts, but should only be done with caution. Key events can easily contain sensitive information, such as passwords, credit card numbers, etc.

Returns

A new guac_recording structure representing the in-progress recording if the recording file has been successfully created and a recording will be written, NULL otherwise.

guac_recording_free()

void guac_recording_free

(

guac_recording *

recording

)

Frees the resources associated with the given in-progress recording.

Note that, due to the manner that recordings are attached to the guac_client, the underlying guac_socket is not freed. The guac_socket will be automatically freed when the guac_client is freed.

Parameters

recording

The guac_recording to free.

guac_recording_report_key()

void guac_recording_report_key	(	guac_recording *	recording,
		int	keysym,
		int	pressed )

Reports a change in the state of an individual key within the recording.

Parameters

recording	The guac_recording associated with the key that was pressed or released.
keysym	The X11 keysym of the key that was pressed or released.
pressed	Non-zero if the key represented by the given keysym is currently pressed, zero if it is released.

guac_recording_report_mouse()

void guac_recording_report_mouse	(	guac_recording *	recording,
		int	x,
		int	y,
		int	button_mask )

Reports the current mouse position and button state within the recording.

Parameters

recording	The guac_recording associated with the mouse that has moved.
x	The new X coordinate of the mouse cursor, in pixels.
y	The new Y coordinate of the mouse cursor, in pixels.
button_mask	An integer value representing the current state of each button, where the Nth bit within the integer is set to 1 if and only if the Nth mouse button is currently pressed. The lowest-order bit is the left mouse button, followed by the middle button, right button, and finally the up and down buttons of the scroll wheel.

See also

GUAC_CLIENT_MOUSE_LEFT

GUAC_CLIENT_MOUSE_MIDDLE

GUAC_CLIENT_MOUSE_RIGHT

GUAC_CLIENT_MOUSE_SCROLL_UP

GUAC_CLIENT_MOUSE_SCROLL_DOWN

guac_recording_report_touch()

void guac_recording_report_touch	(	guac_recording *	recording,
		int	id,
		int	x,
		int	y,
		int	x_radius,
		int	y_radius,
		double	angle,
		double	force )

Reports the current state of a touch contact within the recording.

Parameters

recording	The guac_recording associated with the touch contact that has changed state.
id	An arbitrary integer ID which uniquely identifies this contact relative to other active contacts.
x	The X coordinate of the center of the touch contact.
y	The Y coordinate of the center of the touch contact.
x_radius	The X radius of the ellipse covering the general area of the touch contact, in pixels.
y_radius	The Y radius of the ellipse covering the general area of the touch contact, in pixels.
angle	The rough angle of clockwise rotation of the general area of the touch contact, in degrees.
force	The relative force exerted by the touch contact, where 0 is no force (the touch has been lifted) and 1 is maximum force (the maximum amount of force representable by the device).