GUAC-1389: Document settings. Use macros to remove struct members if their settings are not applicable.

This commit is contained in:
Michael Jumper 2016-03-03 12:58:46 -08:00
parent f6feec8c84
commit 05e8bf3195
2 changed files with 152 additions and 4 deletions

View File

@ -76,40 +76,155 @@ const char* GUAC_VNC_CLIENT_ARGS[] = {
enum VNC_ARGS_IDX { enum VNC_ARGS_IDX {
/**
* The hostname of the VNC server (or repeater) to connect to.
*/
IDX_HOSTNAME, IDX_HOSTNAME,
/**
* The port of the VNC server (or repeater) to connect to.
*/
IDX_PORT, IDX_PORT,
/**
* "true" if this connection should be read-only (user input should be
* dropped), "false" or blank otherwise.
*/
IDX_READ_ONLY, 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, IDX_ENCODINGS,
/**
* The password to send to the VNC server if authentication is requested.
*/
IDX_PASSWORD, 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, IDX_SWAP_RED_BLUE,
/**
* The color depth to request, in bits.
*/
IDX_COLOR_DEPTH, 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, IDX_CURSOR,
/**
* The number of connection attempts to make before giving up. By default,
* this will be 0.
*/
IDX_AUTORETRY, 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, IDX_CLIPBOARD_ENCODING,
#ifdef ENABLE_VNC_REPEATER #ifdef ENABLE_VNC_REPEATER
/**
* The VNC host to connect to, if using a repeater.
*/
IDX_DEST_HOST, IDX_DEST_HOST,
/**
* The VNC port to connect to, if using a repeater.
*/
IDX_DEST_PORT, IDX_DEST_PORT,
#endif #endif
#ifdef ENABLE_PULSE #ifdef ENABLE_PULSE
/**
* "true" if audio should be enabled, "false" or blank otherwise.
*/
IDX_ENABLE_AUDIO, 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, IDX_AUDIO_SERVERNAME,
#endif #endif
#ifdef ENABLE_VNC_LISTEN #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, 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, IDX_LISTEN_TIMEOUT,
#endif #endif
#ifdef ENABLE_COMMON_SSH #ifdef ENABLE_COMMON_SSH
/**
* "true" if SFTP should be enabled for the VNC connection, "false" or
* blank otherwise.
*/
IDX_ENABLE_SFTP, 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, 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, IDX_SFTP_PORT,
/**
* The username to provide when authenticating with the SSH server for
* SFTP.
*/
IDX_SFTP_USERNAME, IDX_SFTP_USERNAME,
/**
* The password to provide when authenticating with the SSH server for
* SFTP (if not using a private key).
*/
IDX_SFTP_PASSWORD, 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, IDX_SFTP_PRIVATE_KEY,
/**
* The passphrase to use to decrypt the provided base64-encoded private
* key.
*/
IDX_SFTP_PASSPHRASE, 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, IDX_SFTP_DIRECTORY,
#endif #endif
@ -183,7 +298,8 @@ guac_vnc_settings* guac_vnc_parse_args(guac_user* user,
/* Set encodings if specified */ /* Set encodings if specified */
settings->encodings = settings->encodings =
guac_user_parse_args_string(user, GUAC_VNC_CLIENT_ARGS, argv, 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 */ /* Parse autoretry */
settings->retries = settings->retries =

View File

@ -70,6 +70,7 @@ typedef struct guac_vnc_settings {
*/ */
bool read_only; bool read_only;
#ifdef ENABLE_VNC_REPEATER
/** /**
* The VNC host to connect to, if using a 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. * The VNC port to connect to, if using a repeater.
*/ */
int dest_port; int dest_port;
#endif
#ifdef ENABLE_VNC_LISTEN #ifdef ENABLE_VNC_LISTEN
/** /**
@ -99,13 +101,13 @@ typedef struct guac_vnc_settings {
* client (local). * client (local).
*/ */
int remote_cursor; int remote_cursor;
#ifdef ENABLE_PULSE
/** /**
* Whether audio is enabled. * Whether audio is enabled.
*/ */
bool audio_enabled; bool audio_enabled;
#ifdef ENABLE_PULSE
/** /**
* The name of the PulseAudio server to connect to. * The name of the PulseAudio server to connect to.
*/ */
@ -124,20 +126,50 @@ typedef struct guac_vnc_settings {
char* clipboard_encoding; char* clipboard_encoding;
#ifdef ENABLE_COMMON_SSH #ifdef ENABLE_COMMON_SSH
/**
* Whether SFTP should be enabled for the VNC connection.
*/
bool enable_sftp; bool enable_sftp;
/**
* The hostname of the SSH server to connect to for SFTP.
*/
char* sftp_hostname; char* sftp_hostname;
/**
* The port of the SSH server to connect to for SFTP.
*/
char* sftp_port; char* sftp_port;
/**
* The username to provide when authenticating with the SSH server for
* SFTP.
*/
char* sftp_username; char* sftp_username;
/**
* The password to provide when authenticating with the SSH server for
* SFTP (if not using a private key).
*/
char* sftp_password; 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; char* sftp_private_key;
/**
* The passphrase to use to decrypt the provided base64-encoded private
* key.
*/
char* sftp_passphrase; 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; char* sftp_directory;
#endif #endif