From 05e8bf3195733bc29d4091665f7ad3d49b84ece8 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Thu, 3 Mar 2016 12:58:46 -0800 Subject: [PATCH] GUAC-1389: Document settings. Use macros to remove struct members if their settings are not applicable. --- src/protocols/vnc/settings.c | 118 ++++++++++++++++++++++++++++++++++- src/protocols/vnc/settings.h | 38 ++++++++++- 2 files changed, 152 insertions(+), 4 deletions(-) diff --git a/src/protocols/vnc/settings.c b/src/protocols/vnc/settings.c index 8afdfaa7..74912ede 100644 --- a/src/protocols/vnc/settings.c +++ b/src/protocols/vnc/settings.c @@ -76,40 +76,155 @@ const char* GUAC_VNC_CLIENT_ARGS[] = { enum VNC_ARGS_IDX { + /** + * The hostname of the VNC server (or repeater) to connect to. + */ IDX_HOSTNAME, + + /** + * The port of the VNC server (or repeater) to connect to. + */ IDX_PORT, + + /** + * "true" if this connection should be read-only (user input should be + * dropped), "false" or blank otherwise. + */ IDX_READ_ONLY, + + /** + * Space-separated list of encodings to use within the VNC session. If not + * specified, this will be: + * + * "zrle ultra copyrect hextile zlib corre rre raw". + */ IDX_ENCODINGS, + + /** + * The password to send to the VNC server if authentication is requested. + */ IDX_PASSWORD, + + /** + * "true" if the red and blue components of each color should be swapped, + * "false" or blank otherwise. This is mainly used for VNC servers that do + * not properly handle colors. + */ IDX_SWAP_RED_BLUE, + + /** + * The color depth to request, in bits. + */ IDX_COLOR_DEPTH, + + /** + * "remote" if the cursor should be rendered on the server instead of the + * client. All other values will default to local rendering. + */ IDX_CURSOR, + + /** + * The number of connection attempts to make before giving up. By default, + * this will be 0. + */ IDX_AUTORETRY, + + /** + * The encoding to use for clipboard data sent to the VNC server if we are + * going to be deviating from the standard (which mandates ISO 8829-1). + * Valid values are "ISO8829-1" (the only legal value with respect to the + * VNC standard), "UTF-8", "UTF-16", and "CP2252". + */ IDX_CLIPBOARD_ENCODING, #ifdef ENABLE_VNC_REPEATER + /** + * The VNC host to connect to, if using a repeater. + */ IDX_DEST_HOST, + + /** + * The VNC port to connect to, if using a repeater. + */ IDX_DEST_PORT, #endif #ifdef ENABLE_PULSE + /** + * "true" if audio should be enabled, "false" or blank otherwise. + */ IDX_ENABLE_AUDIO, + + /** + * The name of the PulseAudio server to connect to. If left blank, the + * default sink of the local machine will be used as the source for audio. + */ IDX_AUDIO_SERVERNAME, #endif #ifdef ENABLE_VNC_LISTEN + /** + * "true" if not actually connecting to a VNC server, but rather listening + * for a connection from the VNC server (reverse connection), "false" or + * blank otherwise. + */ IDX_REVERSE_CONNECT, + + /** + * The maximum amount of time to wait when listening for connections, in + * milliseconds. If unspecified, this will default to 5000. + */ IDX_LISTEN_TIMEOUT, #endif #ifdef ENABLE_COMMON_SSH + /** + * "true" if SFTP should be enabled for the VNC connection, "false" or + * blank otherwise. + */ IDX_ENABLE_SFTP, + + /** + * The hostname of the SSH server to connect to for SFTP. If blank, the + * hostname of the VNC server will be used. + */ IDX_SFTP_HOSTNAME, + + /** + * The port of the SSH server to connect to for SFTP. If blank, the default + * SSH port of "22" will be used. + */ IDX_SFTP_PORT, + + /** + * The username to provide when authenticating with the SSH server for + * SFTP. + */ IDX_SFTP_USERNAME, + + /** + * The password to provide when authenticating with the SSH server for + * SFTP (if not using a private key). + */ IDX_SFTP_PASSWORD, + + /** + * The base64-encoded private key to use when authenticating with the SSH + * server for SFTP (if not using a password). + */ IDX_SFTP_PRIVATE_KEY, + + /** + * The passphrase to use to decrypt the provided base64-encoded private + * key. + */ IDX_SFTP_PASSPHRASE, + + /** + * The default location for file uploads within the SSH server. This will + * apply only to uploads which do not use the filesystem guac_object (where + * the destination directory is otherwise ambiguous). + */ IDX_SFTP_DIRECTORY, #endif @@ -183,7 +298,8 @@ guac_vnc_settings* guac_vnc_parse_args(guac_user* user, /* Set encodings if specified */ settings->encodings = guac_user_parse_args_string(user, GUAC_VNC_CLIENT_ARGS, argv, - IDX_ENCODINGS, NULL); + IDX_ENCODINGS, + "zrle ultra copyrect hextile zlib corre rre raw"); /* Parse autoretry */ settings->retries = diff --git a/src/protocols/vnc/settings.h b/src/protocols/vnc/settings.h index 9d3034b5..e69c5fea 100644 --- a/src/protocols/vnc/settings.h +++ b/src/protocols/vnc/settings.h @@ -70,6 +70,7 @@ typedef struct guac_vnc_settings { */ bool read_only; +#ifdef ENABLE_VNC_REPEATER /** * The VNC host to connect to, if using a repeater. */ @@ -79,6 +80,7 @@ typedef struct guac_vnc_settings { * The VNC port to connect to, if using a repeater. */ int dest_port; +#endif #ifdef ENABLE_VNC_LISTEN /** @@ -99,13 +101,13 @@ typedef struct guac_vnc_settings { * client (local). */ int remote_cursor; - + +#ifdef ENABLE_PULSE /** * Whether audio is enabled. */ bool audio_enabled; - -#ifdef ENABLE_PULSE + /** * The name of the PulseAudio server to connect to. */ @@ -124,20 +126,50 @@ typedef struct guac_vnc_settings { char* clipboard_encoding; #ifdef ENABLE_COMMON_SSH + /** + * Whether SFTP should be enabled for the VNC connection. + */ bool enable_sftp; + /** + * The hostname of the SSH server to connect to for SFTP. + */ char* sftp_hostname; + /** + * The port of the SSH server to connect to for SFTP. + */ char* sftp_port; + /** + * The username to provide when authenticating with the SSH server for + * SFTP. + */ char* sftp_username; + /** + * The password to provide when authenticating with the SSH server for + * SFTP (if not using a private key). + */ char* sftp_password; + /** + * The base64-encoded private key to use when authenticating with the SSH + * server for SFTP (if not using a password). + */ char* sftp_private_key; + /** + * The passphrase to use to decrypt the provided base64-encoded private + * key. + */ char* sftp_passphrase; + /** + * The default location for file uploads within the SSH server. This will + * apply only to uploads which do not use the filesystem guac_object (where + * the destination directory is otherwise ambiguous). + */ char* sftp_directory; #endif