GUAC-1389: Update comments to match latest standard.

This commit is contained in:
Michael Jumper 2016-03-07 15:05:31 -08:00
parent 5a6c16ab24
commit 12f166c0fc
16 changed files with 355 additions and 144 deletions

View File

@ -64,16 +64,22 @@ typedef struct guac_rdp_bitmap {
* destroyed, we defer actual remote-side caching of RDP bitmaps until they are * destroyed, we defer actual remote-side caching of RDP bitmaps until they are
* used at least once. * used at least once.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param bitmap The bitmap to cache. * The rdpContext associated with the current RDP session.
*
* @param bitmap
* The bitmap to cache.
*/ */
void guac_rdp_cache_bitmap(rdpContext* context, rdpBitmap* bitmap); void guac_rdp_cache_bitmap(rdpContext* context, rdpBitmap* bitmap);
/** /**
* Initializes the given newly-created rdpBitmap. * Initializes the given newly-created rdpBitmap.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param bitmap The bitmap to initialize. * The rdpContext associated with the current RDP session.
*
* @param bitmap
* The bitmap to initialize.
*/ */
void guac_rdp_bitmap_new(rdpContext* context, rdpBitmap* bitmap); void guac_rdp_bitmap_new(rdpContext* context, rdpBitmap* bitmap);
@ -82,7 +88,8 @@ void guac_rdp_bitmap_new(rdpContext* context, rdpBitmap* bitmap);
* operation does NOT draw to the "current" surface set by calls to * operation does NOT draw to the "current" surface set by calls to
* guac_rdp_bitmap_setsurface(). * guac_rdp_bitmap_setsurface().
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param bitmap * @param bitmap
* The bitmap to paint. This structure will also contain the specifics of * The bitmap to paint. This structure will also contain the specifics of
@ -94,8 +101,11 @@ void guac_rdp_bitmap_paint(rdpContext* context, rdpBitmap* bitmap);
/** /**
* Frees any Guacamole-specific data associated with the given rdpBitmap. * Frees any Guacamole-specific data associated with the given rdpBitmap.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param bitmap The bitmap whose Guacamole-specific data is to be freed. * The rdpContext associated with the current RDP session.
*
* @param bitmap
* The bitmap whose Guacamole-specific data is to be freed.
*/ */
void guac_rdp_bitmap_free(rdpContext* context, rdpBitmap* bitmap); void guac_rdp_bitmap_free(rdpContext* context, rdpBitmap* bitmap);
@ -104,7 +114,8 @@ void guac_rdp_bitmap_free(rdpContext* context, rdpBitmap* bitmap);
* if the primary flag is set, resets the current drawing surface to the * if the primary flag is set, resets the current drawing surface to the
* primary drawing surface of the remote display. * primary drawing surface of the remote display.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param bitmap * @param bitmap
* The rdpBitmap to set as the current drawing surface. This parameter is * The rdpBitmap to set as the current drawing surface. This parameter is
@ -125,17 +136,29 @@ void guac_rdp_bitmap_setsurface(rdpContext* context, rdpBitmap* bitmap,
* received data is not compressed, it is the duty of this function to also * received data is not compressed, it is the duty of this function to also
* flip received data, if the row order is backwards. * flip received data, if the row order is backwards.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param bitmap * @param bitmap
* The bitmap in which the decompressed/copied data should be stored. * The bitmap in which the decompressed/copied data should be stored.
* *
* @param data Possibly-compressed image data. * @param data
* @param width The width of the image data, in pixels. * Possibly-compressed image data.
* @param height The height of the image data, in pixels. *
* @param bpp The number of bits per pixel in the image data. * @param width
* @param length The length of the image data, in bytes. * The width of the image data, in pixels.
* @param compressed TRUE if the image data is compressed, FALSE otherwise. *
* @param height
* The height of the image data, in pixels.
*
* @param bpp
* The number of bits per pixel in the image data.
*
* @param length
* The length of the image data, in bytes.
*
* @param compressed
* TRUE if the image data is compressed, FALSE otherwise.
*/ */
void guac_rdp_bitmap_decompress(rdpContext* context, rdpBitmap* bitmap, void guac_rdp_bitmap_decompress(rdpContext* context, rdpBitmap* bitmap,
UINT8* data, int width, int height, int bpp, int length, UINT8* data, int width, int height, int bpp, int length,
@ -147,17 +170,29 @@ void guac_rdp_bitmap_decompress(rdpContext* context, rdpBitmap* bitmap,
* received data is not compressed, it is the duty of this function to also * received data is not compressed, it is the duty of this function to also
* flip received data, if the row order is backwards. * flip received data, if the row order is backwards.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param bitmap * @param bitmap
* The bitmap in which the decompressed/copied data should be stored. * The bitmap in which the decompressed/copied data should be stored.
* *
* @param data Possibly-compressed image data. * @param data
* @param width The width of the image data, in pixels. * Possibly-compressed image data.
* @param height The height of the image data, in pixels. *
* @param bpp The number of bits per pixel in the image data. * @param width
* @param length The length of the image data, in bytes. * The width of the image data, in pixels.
* @param compressed TRUE if the image data is compressed, FALSE otherwise. *
* @param height
* The height of the image data, in pixels.
*
* @param bpp
* The number of bits per pixel in the image data.
*
* @param length
* The length of the image data, in bytes.
*
* @param compressed
* TRUE if the image data is compressed, FALSE otherwise.
* *
* @param codec_id * @param codec_id
* The ID of the codec used to compress the image data. This parameter is * The ID of the codec used to compress the image data. This parameter is

View File

@ -116,7 +116,9 @@ void guac_rdp_process_cb_monitor_ready(guac_client* client, wMessage* event) {
/** /**
* Sends a clipboard data request for the given format. * Sends a clipboard data request for the given format.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
*
* @param format * @param format
* The clipboard format to request. This format must be one of the * The clipboard format to request. This format must be one of the
* documented values used by the CLIPRDR channel for clipboard format IDs. * documented values used by the CLIPRDR channel for clipboard format IDs.

View File

@ -55,8 +55,11 @@
* received. This function will dispatch that message to an appropriate * received. This function will dispatch that message to an appropriate
* function, specific to that message type. * function, specific to that message type.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param event The received CLIPRDR message. * The guac_client associated with the current RDP session.
*
* @param event
* The received CLIPRDR message.
*/ */
void guac_rdp_process_cliprdr_event(guac_client* client, wMessage* event); void guac_rdp_process_cliprdr_event(guac_client* client, wMessage* event);
@ -65,7 +68,8 @@ void guac_rdp_process_cliprdr_event(guac_client* client, wMessage* event);
* is the responsibility of this function to respond to the Monitor Ready * is the responsibility of this function to respond to the Monitor Ready
* event with a list of supported clipboard formats. * event with a list of supported clipboard formats.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
* *
* @param event * @param event
* The received CLIPRDR message, which must be a Monitor Ready event. * The received CLIPRDR message, which must be a Monitor Ready event.
@ -78,7 +82,8 @@ void guac_rdp_process_cb_monitor_ready(guac_client* client, wMessage* event);
* event with a request for clipboard data in one of the enumerated formats. * event with a request for clipboard data in one of the enumerated formats.
* This event is fired whenever remote clipboard data is available. * This event is fired whenever remote clipboard data is available.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
* *
* @param event * @param event
* The received CLIPRDR message, which must be a Format List event. * The received CLIPRDR message, which must be a Format List event.
@ -91,7 +96,8 @@ void guac_rdp_process_cb_format_list(guac_client* client,
* is the responsibility of this function to respond to the Data Request * is the responsibility of this function to respond to the Data Request
* event with a data response containing the current clipoard contents. * event with a data response containing the current clipoard contents.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
* *
* @param event * @param event
* The received CLIPRDR message, which must be a Data Request event. * The received CLIPRDR message, which must be a Data Request event.
@ -104,7 +110,8 @@ void guac_rdp_process_cb_data_request(guac_client* client,
* is the responsibility of this function to read and forward the received * is the responsibility of this function to read and forward the received
* clipboard data to connected clients. * clipboard data to connected clients.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
* *
* @param event * @param event
* The received CLIPRDR message, which must be a Data Response event. * The received CLIPRDR message, which must be a Data Response event.

View File

@ -36,8 +36,12 @@
* referring to the palette, a 16-bit or 32-bit color, etc. all depending on * referring to the palette, a 16-bit or 32-bit color, etc. all depending on
* the current color depth of the RDP session. * the current color depth of the RDP session.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param color A color value in the format of the current RDP session. * The rdpContext associated with the current RDP session.
*
* @param color
* A color value in the format of the current RDP session.
*
* @return * @return
* A 32-bit ARGB color, where the low 8 bits are the blue component and * A 32-bit ARGB color, where the low 8 bits are the blue component and
* the high 8 bits are alpha. * the high 8 bits are alpha.

View File

@ -113,7 +113,8 @@ void* guac_rdp_fs_expose(guac_user* user, void* data) {
* on the path provided, which is assumed to have already been normalized and * on the path provided, which is assumed to have already been normalized and
* validated as absolute. * validated as absolute.
* *
* @param fs The filesystem containing the file whose path is being translated. * @param fs
* The filesystem containing the file whose path is being translated.
* *
* @param virtual_path * @param virtual_path
* The absolute path to the file on the simulated filesystem, relative to * The absolute path to the file on the simulated filesystem, relative to

View File

@ -340,7 +340,8 @@ guac_rdp_fs* guac_rdp_fs_alloc(guac_client* client, const char* drive_path,
/** /**
* Frees the given filesystem. * Frees the given filesystem.
* *
* @param fs The filesystem to free. * @param fs
* The filesystem to free.
*/ */
void guac_rdp_fs_free(guac_rdp_fs* fs); void guac_rdp_fs_free(guac_rdp_fs* fs);
@ -392,9 +393,14 @@ void* guac_rdp_fs_expose(guac_user* user, void* data);
* Converts the given relative path to an absolute path based on the given * Converts the given relative path to an absolute path based on the given
* parent path. If the path cannot be converted, non-zero is returned. * parent path. If the path cannot be converted, non-zero is returned.
* *
* @param parent The parent directory of the relative path. * @param parent
* @param rel_path The relative path to convert. * The parent directory of the relative path.
* @return Zero if the path was converted successfully, non-zero otherwise. *
* @param rel_path
* The relative path to convert.
*
* @return
* Zero if the path was converted successfully, non-zero otherwise.
*/ */
int guac_rdp_fs_convert_path(const char* parent, const char* rel_path, int guac_rdp_fs_convert_path(const char* parent, const char* rel_path,
char* abs_path); char* abs_path);
@ -402,7 +408,8 @@ int guac_rdp_fs_convert_path(const char* parent, const char* rel_path,
/** /**
* Translates the given errno error code to a GUAC_RDP_FS error code. * Translates the given errno error code to a GUAC_RDP_FS error code.
* *
* @param err The error code, as returned within errno by a system call. * @param err
* The error code, as returned within errno by a system call.
* *
* @return * @return
* A GUAC_RDP_FS error code, such as GUAC_RDP_FS_ENFILE, * A GUAC_RDP_FS error code, such as GUAC_RDP_FS_ENFILE,
@ -428,8 +435,11 @@ int guac_rdp_fs_get_status(int err);
* than zero if an error occurs. The given path MUST be absolute, and will be * than zero if an error occurs. The given path MUST be absolute, and will be
* translated to be relative to the drive path of the simulated filesystem. * translated to be relative to the drive path of the simulated filesystem.
* *
* @param fs The filesystem to use when opening the file. * @param fs
* @param path The absolute path to the file within the simulated filesystem. * The filesystem to use when opening the file.
*
* @param path
* The absolute path to the file within the simulated filesystem.
* *
* @param access * @param access
* A bitwise-OR of various RDPDR access flags, such as ACCESS_GENERIC_ALL * A bitwise-OR of various RDPDR access flags, such as ACCESS_GENERIC_ALL
@ -466,14 +476,20 @@ int guac_rdp_fs_open(guac_rdp_fs* fs, const char* path,
* file having the given ID. Returns the number of bytes read, zero on EOF, * file having the given ID. Returns the number of bytes read, zero on EOF,
* and an error code if an error occurs. * and an error code if an error occurs.
* *
* @param fs The filesystem containing the file from which data is to be read. * @param fs
* The filesystem containing the file from which data is to be read.
* *
* @param file_id * @param file_id
* The ID of the file to read data from, as returned by guac_rdp_fs_open(). * The ID of the file to read data from, as returned by guac_rdp_fs_open().
* *
* @param offset The byte offset within the file to start reading from. * @param offset
* @param buffer The buffer to fill with data from the file. * The byte offset within the file to start reading from.
* @param length The maximum number of bytes to read from the file. *
* @param buffer
* The buffer to fill with data from the file.
*
* @param length
* The maximum number of bytes to read from the file.
* *
* @return * @return
* The number of bytes actually read, zero on EOF, or an error code if an * The number of bytes actually read, zero on EOF, or an error code if an
@ -488,14 +504,20 @@ int guac_rdp_fs_read(guac_rdp_fs* fs, int file_id, int offset,
* file having the given ID. Returns the number of bytes written, and an * file having the given ID. Returns the number of bytes written, and an
* error code if an error occurs. * error code if an error occurs.
* *
* @param fs The filesystem containing the file to which data is to be written. * @param fs
* The filesystem containing the file to which data is to be written.
* *
* @param file_id * @param file_id
* The ID of the file to write data to, as returned by guac_rdp_fs_open(). * The ID of the file to write data to, as returned by guac_rdp_fs_open().
* *
* @param offset The byte offset within the file to start writinging at. * @param offset
* @param buffer The buffer containing the data to write. * The byte offset within the file to start writinging at.
* @param length The maximum number of bytes to write to the file. *
* @param buffer
* The buffer containing the data to write.
*
* @param length
* The maximum number of bytes to write to the file.
* *
* @return * @return
* The number of bytes actually written, or an error code if an error * The number of bytes actually written, or an error code if an error
@ -509,12 +531,14 @@ int guac_rdp_fs_write(guac_rdp_fs* fs, int file_id, int offset,
* Renames (moves) the file with the given ID to the new path specified. * Renames (moves) the file with the given ID to the new path specified.
* Returns zero on success, or an error code if an error occurs. * Returns zero on success, or an error code if an error occurs.
* *
* @param fs The filesystem containing the file to rename. * @param fs
* The filesystem containing the file to rename.
* *
* @param file_id * @param file_id
* The ID of the file to rename, as returned by guac_rdp_fs_open(). * The ID of the file to rename, as returned by guac_rdp_fs_open().
* *
* @param new_path The absolute path to move the file to. * @param new_path
* The absolute path to move the file to.
* *
* @return * @return
* Zero if the rename succeeded, or an error code if an error occurs. All * Zero if the rename succeeded, or an error code if an error occurs. All
@ -527,7 +551,8 @@ int guac_rdp_fs_rename(guac_rdp_fs* fs, int file_id,
/** /**
* Deletes the file with the given ID. * Deletes the file with the given ID.
* *
* @param fs The filesystem containing the file to delete. * @param fs
* The filesystem containing the file to delete.
* *
* @param file_id * @param file_id
* The ID of the file to delete, as returned by guac_rdp_fs_open(). * The ID of the file to delete, as returned by guac_rdp_fs_open().
@ -543,7 +568,8 @@ int guac_rdp_fs_delete(guac_rdp_fs* fs, int file_id);
* Truncates the file with the given ID to the given length (in bytes), which * Truncates the file with the given ID to the given length (in bytes), which
* may be larger. * may be larger.
* *
* @param fs The filesystem containing the file to truncate. * @param fs
* The filesystem containing the file to truncate.
* *
* @param file_id * @param file_id
* The ID of the file to truncate, as returned by guac_rdp_fs_open(). * The ID of the file to truncate, as returned by guac_rdp_fs_open().
@ -562,7 +588,8 @@ int guac_rdp_fs_truncate(guac_rdp_fs* fs, int file_id, int length);
/** /**
* Frees the given file ID, allowing future open operations to reuse it. * Frees the given file ID, allowing future open operations to reuse it.
* *
* @param fs The filesystem containing the file to close. * @param fs
* The filesystem containing the file to close.
* *
* @param file_id * @param file_id
* The ID of the file to close, as returned by guac_rdp_fs_open(). * The ID of the file to close, as returned by guac_rdp_fs_open().
@ -574,12 +601,15 @@ void guac_rdp_fs_close(guac_rdp_fs* fs, int file_id);
* absolute path which does NOT contain ".." or ".". The given path MUST * absolute path which does NOT contain ".." or ".". The given path MUST
* be absolute. * be absolute.
* *
* @param path The absolute path to normalize. * @param path
* The absolute path to normalize.
*
* @param abs_path * @param abs_path
* The buffer to populate with the normalized path. The normalized path * The buffer to populate with the normalized path. The normalized path
* will not contain relative path components like ".." or ".". * will not contain relative path components like ".." or ".".
* *
* @return Zero if normalization succeeded, non-zero otherwise. * @return
* Zero if normalization succeeded, non-zero otherwise.
*/ */
int guac_rdp_fs_normalize_path(const char* path, char* abs_path); int guac_rdp_fs_normalize_path(const char* path, char* abs_path);
@ -590,14 +620,16 @@ int guac_rdp_fs_normalize_path(const char* path, char* abs_path);
* @param parent * @param parent
* The absolute path of the parent directory of the relative path. * The absolute path of the parent directory of the relative path.
* *
* @param rel_path The relative path to convert. * @param rel_path
* The relative path to convert.
* *
* @param abs_path * @param abs_path
* The buffer to populate with the absolute, normalized path. The * The buffer to populate with the absolute, normalized path. The
* normalized path will not contain relative path components like ".." or * normalized path will not contain relative path components like ".." or
* ".". * ".".
* *
* @return Zero if conversion succeeded, non-zero otherwise. * @return
* Zero if conversion succeeded, non-zero otherwise.
*/ */
int guac_rdp_fs_convert_path(const char* parent, const char* rel_path, int guac_rdp_fs_convert_path(const char* parent, const char* rel_path,
char* abs_path); char* abs_path);
@ -606,7 +638,8 @@ int guac_rdp_fs_convert_path(const char* parent, const char* rel_path,
* Returns the next filename within the directory having the given file ID, * Returns the next filename within the directory having the given file ID,
* or NULL if no more files. * or NULL if no more files.
* *
* @param fs The filesystem containing the file to read directory entries from. * @param fs
* The filesystem containing the file to read directory entries from.
* *
* @param file_id * @param file_id
* The ID of the file to read directory entries from, as returned by * The ID of the file to read directory entries from, as returned by
@ -621,9 +654,14 @@ const char* guac_rdp_fs_read_dir(guac_rdp_fs* fs, int file_id);
/** /**
* Returns the file having the given ID, or NULL if no such file exists. * Returns the file having the given ID, or NULL if no such file exists.
* *
* @param fs The filesystem containing the desired file. * @param fs
* @param file_id The ID of the desired, as returned by guac_rdp_fs_open(). * The filesystem containing the desired file.
* @return The file having the given ID, or NULL is no such file exists. *
* @param file_id
* The ID of the desired, as returned by guac_rdp_fs_open().
*
* @return
* The file having the given ID, or NULL is no such file exists.
*/ */
guac_rdp_fs_file* guac_rdp_fs_get_file(guac_rdp_fs* fs, int file_id); guac_rdp_fs_file* guac_rdp_fs_get_file(guac_rdp_fs* fs, int file_id);
@ -633,9 +671,14 @@ guac_rdp_fs_file* guac_rdp_fs_get_file(guac_rdp_fs* fs, int file_id);
* function. Backslashes will be interpreted as literal backslashes, not * function. Backslashes will be interpreted as literal backslashes, not
* escape characters. * escape characters.
* *
* @param filename The filename to check * @param filename
* @param pattern The pattern to check the filename against. * The filename to check
* @return Non-zero if the pattern matches, zero otherwise. *
* @param pattern
* The pattern to check the filename against.
*
* @return
* Non-zero if the pattern matches, zero otherwise.
*/ */
int guac_rdp_fs_matches(const char* filename, const char* pattern); int guac_rdp_fs_matches(const char* filename, const char* pattern);
@ -643,8 +686,11 @@ int guac_rdp_fs_matches(const char* filename, const char* pattern);
* Populates the given structure with information about the filesystem, * Populates the given structure with information about the filesystem,
* particularly the amount of space available. * particularly the amount of space available.
* *
* @param fs The filesystem to obtain information from. * @param fs
* @param info The guac_rdp_fs_info structure to populate. * The filesystem to obtain information from.
*
* @param info
* The guac_rdp_fs_info structure to populate.
* *
* @return * @return
* Zero if information retrieval succeeded, or an error code if an error * Zero if information retrieval succeeded, or an error code if an error

View File

@ -344,7 +344,8 @@ void guac_rdp_gdi_opaquerect(rdpContext* context, OPAQUE_RECT_ORDER* opaque_rect
* Updates the palette within a FreeRDP CLRCONV object using the new palette * Updates the palette within a FreeRDP CLRCONV object using the new palette
* entries provided by an RDP palette update. * entries provided by an RDP palette update.
* *
* @param clrconv The FreeRDP CLRCONV object to update. * @param clrconv
* The FreeRDP CLRCONV object to update.
* *
* @param palette * @param palette
* An RDP palette update message containing the palette to store within the * An RDP palette update message containing the palette to store within the

View File

@ -35,8 +35,11 @@
* *
* http://msdn.microsoft.com/en-us/library/cc241583.aspx * http://msdn.microsoft.com/en-us/library/cc241583.aspx
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param rop3 The ROP3 operation index to translate. * The guac_client associated with the current RDP session.
*
* @param rop3
* The ROP3 operation index to translate.
* *
* @return * @return
* The guac_composite_mode that equates to, or most closely approximates, * The guac_composite_mode that equates to, or most closely approximates,
@ -48,40 +51,55 @@ guac_composite_mode guac_rdp_rop3_transfer_function(guac_client* client,
/** /**
* Handler for RDP DSTBLT update. * Handler for RDP DSTBLT update.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param dstblt The DSTBLT update to handle. * The rdpContext associated with the current RDP session.
*
* @param dstblt
* The DSTBLT update to handle.
*/ */
void guac_rdp_gdi_dstblt(rdpContext* context, DSTBLT_ORDER* dstblt); void guac_rdp_gdi_dstblt(rdpContext* context, DSTBLT_ORDER* dstblt);
/** /**
* Handler for RDP PATBLT update. * Handler for RDP PATBLT update.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param patblt The PATBLT update to handle. * The rdpContext associated with the current RDP session.
*
* @param patblt
* The PATBLT update to handle.
*/ */
void guac_rdp_gdi_patblt(rdpContext* context, PATBLT_ORDER* patblt); void guac_rdp_gdi_patblt(rdpContext* context, PATBLT_ORDER* patblt);
/** /**
* Handler for RDP SCRBLT update. * Handler for RDP SCRBLT update.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param scrblt The SCRBLT update to handle. * The rdpContext associated with the current RDP session.
*
* @param scrblt
* The SCRBLT update to handle.
*/ */
void guac_rdp_gdi_scrblt(rdpContext* context, SCRBLT_ORDER* scrblt); void guac_rdp_gdi_scrblt(rdpContext* context, SCRBLT_ORDER* scrblt);
/** /**
* Handler for RDP MEMBLT update. * Handler for RDP MEMBLT update.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param memblt The MEMBLT update to handle. * The rdpContext associated with the current RDP session.
*
* @param memblt
* The MEMBLT update to handle.
*/ */
void guac_rdp_gdi_memblt(rdpContext* context, MEMBLT_ORDER* memblt); void guac_rdp_gdi_memblt(rdpContext* context, MEMBLT_ORDER* memblt);
/** /**
* Handler for RDP OPAQUE RECT update. * Handler for RDP OPAQUE RECT update.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param opaque_rect The OPAQUE RECT update to handle. * The rdpContext associated with the current RDP session.
*
* @param opaque_rect
* The OPAQUE RECT update to handle.
*/ */
void guac_rdp_gdi_opaquerect(rdpContext* context, void guac_rdp_gdi_opaquerect(rdpContext* context,
OPAQUE_RECT_ORDER* opaque_rect); OPAQUE_RECT_ORDER* opaque_rect);
@ -89,8 +107,11 @@ void guac_rdp_gdi_opaquerect(rdpContext* context,
/** /**
* Handler called when the remote color palette is changing. * Handler called when the remote color palette is changing.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param palette The PALETTE update containing the new palette. * The rdpContext associated with the current RDP session.
*
* @param palette
* The PALETTE update containing the new palette.
*/ */
void guac_rdp_gdi_palette_update(rdpContext* context, PALETTE_UPDATE* palette); void guac_rdp_gdi_palette_update(rdpContext* context, PALETTE_UPDATE* palette);
@ -100,7 +121,8 @@ void guac_rdp_gdi_palette_update(rdpContext* context, PALETTE_UPDATE* palette);
* update, but is called by FreeRDP before and after any update involving * update, but is called by FreeRDP before and after any update involving
* clipping. * clipping.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param bounds * @param bounds
* The clipping rectangle to set, or NULL to remove any applied clipping * The clipping rectangle to set, or NULL to remove any applied clipping
@ -112,7 +134,8 @@ void guac_rdp_gdi_set_bounds(rdpContext* context, rdpBounds* bounds);
* Handler called when a paint operation is complete. We don't actually * Handler called when a paint operation is complete. We don't actually
* use this, but FreeRDP requires it. Calling this function has no effect. * use this, but FreeRDP requires it. Calling this function has no effect.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
*/ */
void guac_rdp_gdi_end_paint(rdpContext* context); void guac_rdp_gdi_end_paint(rdpContext* context);
@ -125,7 +148,8 @@ void guac_rdp_gdi_end_paint(rdpContext* context);
* The new screen size will be made available within the settings associated * The new screen size will be made available within the settings associated
* with the given context. * with the given context.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
*/ */
void guac_rdp_gdi_desktop_resize(rdpContext* context); void guac_rdp_gdi_desktop_resize(rdpContext* context);

View File

@ -56,8 +56,11 @@ typedef struct guac_rdp_glyph {
* Caches the given glyph. Note that this caching currently only occurs server- * Caches the given glyph. Note that this caching currently only occurs server-
* side, as it is more efficient to transmit the text as PNG. * side, as it is more efficient to transmit the text as PNG.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param glyph The glyph to cache. * The rdpContext associated with the current RDP session.
*
* @param glyph
* The glyph to cache.
*/ */
void guac_rdp_glyph_new(rdpContext* context, rdpGlyph* glyph); void guac_rdp_glyph_new(rdpContext* context, rdpGlyph* glyph);
@ -65,10 +68,17 @@ void guac_rdp_glyph_new(rdpContext* context, rdpGlyph* glyph);
* Draws a previously-cached glyph at the given coordinates within the current * Draws a previously-cached glyph at the given coordinates within the current
* drawing surface. * drawing surface.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param glyph The cached glyph to draw. * The rdpContext associated with the current RDP session.
* @param x The destination X coordinate of the upper-left corner of the glyph. *
* @param y The destination Y coordinate of the upper-left corner of the glyph. * @param glyph
* The cached glyph to draw.
*
* @param x
* The destination X coordinate of the upper-left corner of the glyph.
*
* @param y
* The destination Y coordinate of the upper-left corner of the glyph.
*/ */
void guac_rdp_glyph_draw(rdpContext* context, rdpGlyph* glyph, int x, int y); void guac_rdp_glyph_draw(rdpContext* context, rdpGlyph* glyph, int x, int y);
@ -76,8 +86,11 @@ void guac_rdp_glyph_draw(rdpContext* context, rdpGlyph* glyph, int x, int y);
* Frees any Guacamole-specific data associated with the given glyph, such that * Frees any Guacamole-specific data associated with the given glyph, such that
* it can be safely freed by FreeRDP. * it can be safely freed by FreeRDP.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param glyph The cached glyph to free. * The rdpContext associated with the current RDP session.
*
* @param glyph
* The cached glyph to free.
*/ */
void guac_rdp_glyph_free(rdpContext* context, rdpGlyph* glyph); void guac_rdp_glyph_free(rdpContext* context, rdpGlyph* glyph);
@ -86,7 +99,8 @@ void guac_rdp_glyph_free(rdpContext* context, rdpGlyph* glyph);
* called, the glyphs will be individually rendered by calls to * called, the glyphs will be individually rendered by calls to
* guac_rdp_glyph_draw(). * guac_rdp_glyph_draw().
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param x * @param x
* The X coordinate of the upper-left corner of the background rectangle of * The X coordinate of the upper-left corner of the background rectangle of
@ -124,7 +138,8 @@ void guac_rdp_glyph_begindraw(rdpContext* context,
* of this function whether the background color is opaque or transparent. We * of this function whether the background color is opaque or transparent. We
* currently do NOT implement this function. * currently do NOT implement this function.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
* *
* @param x * @param x
* The X coordinate of the upper-left corner of the background rectangle of * The X coordinate of the upper-left corner of the background rectangle of

View File

@ -113,8 +113,11 @@ typedef int guac_rdp_keysym_state_map[0x200][0x100];
* Simple macro for determing whether a keysym can be stored (or retrieved) * Simple macro for determing whether a keysym can be stored (or retrieved)
* from any keymap. * from any keymap.
* *
* @param keysym The keysym to check. * @param keysym
* @return Non-zero if the keysym can be stored or retrieved, zero otherwise. * The keysym to check.
*
* @return
* Non-zero if the keysym can be stored or retrieved, zero otherwise.
*/ */
#define GUAC_RDP_KEYSYM_STORABLE(keysym) ((keysym) <= 0xFFFF || ((keysym) & 0xFFFF0000) == 0x01000000) #define GUAC_RDP_KEYSYM_STORABLE(keysym) ((keysym) <= 0xFFFF || ((keysym) & 0xFFFF0000) == 0x01000000)
@ -128,7 +131,8 @@ typedef int guac_rdp_keysym_state_map[0x200][0x100];
* A 512-entry array of 256-entry arrays of arbitrary values, where the * A 512-entry array of 256-entry arrays of arbitrary values, where the
* location of each array and value is determined by the given keysym. * location of each array and value is determined by the given keysym.
* *
* @param keysym The keysym of the entry to look up. * @param keysym
* The keysym of the entry to look up.
*/ */
#define GUAC_RDP_KEYSYM_LOOKUP(keysym_mapping, keysym) ( \ #define GUAC_RDP_KEYSYM_LOOKUP(keysym_mapping, keysym) ( \
(keysym_mapping) \ (keysym_mapping) \
@ -206,8 +210,11 @@ extern const guac_rdp_keymap* GUAC_KEYMAPS[];
/** /**
* Return the keymap having the given name, if any, or NULL otherwise. * Return the keymap having the given name, if any, or NULL otherwise.
* *
* @param name The name of the keymap to find. * @param name
* @return The keymap having the given name, or NULL if no such keymap exists. * The name of the keymap to find.
*
* @return
* The keymap having the given name, or NULL if no such keymap exists.
*/ */
const guac_rdp_keymap* guac_rdp_keymap_find(const char* name); const guac_rdp_keymap* guac_rdp_keymap_find(const char* name);

View File

@ -50,8 +50,11 @@ typedef struct guac_rdp_pointer {
* Caches a new pointer, which can later be set via guac_rdp_pointer_set() as * Caches a new pointer, which can later be set via guac_rdp_pointer_set() as
* the current mouse pointer. * the current mouse pointer.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param pointer The pointer to cache. * The rdpContext associated with the current RDP session.
*
* @param pointer
* The pointer to cache.
*/ */
void guac_rdp_pointer_new(rdpContext* context, rdpPointer* pointer); void guac_rdp_pointer_new(rdpContext* context, rdpPointer* pointer);
@ -59,8 +62,11 @@ void guac_rdp_pointer_new(rdpContext* context, rdpPointer* pointer);
* Sets the given cached pointer as the current pointer. The given pointer must * Sets the given cached pointer as the current pointer. The given pointer must
* have already been initialized through a call to guac_rdp_pointer_new(). * have already been initialized through a call to guac_rdp_pointer_new().
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param pointer The pointer to set as the current mouse pointer. * The rdpContext associated with the current RDP session.
*
* @param pointer
* The pointer to set as the current mouse pointer.
*/ */
void guac_rdp_pointer_set(rdpContext* context, rdpPointer* pointer); void guac_rdp_pointer_set(rdpContext* context, rdpPointer* pointer);
@ -68,15 +74,19 @@ void guac_rdp_pointer_set(rdpContext* context, rdpPointer* pointer);
* Frees all Guacamole-related data associated with the given pointer, allowing * Frees all Guacamole-related data associated with the given pointer, allowing
* FreeRDP to free the rest safely. * FreeRDP to free the rest safely.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* @param pointer The pointer to free. * The rdpContext associated with the current RDP session.
*
* @param pointer
* The pointer to free.
*/ */
void guac_rdp_pointer_free(rdpContext* context, rdpPointer* pointer); void guac_rdp_pointer_free(rdpContext* context, rdpPointer* pointer);
/** /**
* Hides the current mouse pointer. * Hides the current mouse pointer.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
*/ */
void guac_rdp_pointer_set_null(rdpContext* context); void guac_rdp_pointer_set_null(rdpContext* context);
@ -84,7 +94,8 @@ void guac_rdp_pointer_set_null(rdpContext* context);
* Sets the system-dependent (as in dependent on the client system) default * Sets the system-dependent (as in dependent on the client system) default
* pointer as the current pointer, rather than a cached pointer. * pointer as the current pointer, rather than a cached pointer.
* *
* @param context The rdpContext associated with the current RDP session. * @param context
* The rdpContext associated with the current RDP session.
*/ */
void guac_rdp_pointer_set_default(rdpContext* context); void guac_rdp_pointer_set_default(rdpContext* context);

View File

@ -37,8 +37,11 @@
/** /**
* Dispatches a given RAIL event to the appropriate handler. * Dispatches a given RAIL event to the appropriate handler.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param event The RAIL event to process. * The guac_client associated with the current RDP session.
*
* @param event
* The RAIL event to process.
*/ */
void guac_rdp_process_rail_event(guac_client* client, wMessage* event); void guac_rdp_process_rail_event(guac_client* client, wMessage* event);
@ -46,8 +49,11 @@ void guac_rdp_process_rail_event(guac_client* client, wMessage* event);
* Handles the event sent when updating system parameters. The event given * Handles the event sent when updating system parameters. The event given
* MUST be a SYSPARAM event. * MUST be a SYSPARAM event.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param event The system parameter event to process. * The guac_client associated with the current RDP session.
*
* @param event
* The system parameter event to process.
*/ */
void guac_rdp_process_rail_get_sysparam(guac_client* client, wMessage* event); void guac_rdp_process_rail_get_sysparam(guac_client* client, wMessage* event);

View File

@ -369,32 +369,44 @@ extern const char* GUAC_RDP_CLIENT_ARGS[];
/** /**
* Save all given settings to the given freerdp instance. * Save all given settings to the given freerdp instance.
* *
* @param guac_settings The guac_rdp_settings object to save. * @param guac_settings
* @param rdp The RDP instance to save settings to. * The guac_rdp_settings object to save.
*
* @param rdp
* The RDP instance to save settings to.
*/ */
void guac_rdp_push_settings(guac_rdp_settings* guac_settings, freerdp* rdp); void guac_rdp_push_settings(guac_rdp_settings* guac_settings, freerdp* rdp);
/** /**
* Returns the width of the RDP session display. * Returns the width of the RDP session display.
* *
* @param rdp The RDP instance to retrieve the width from. * @param rdp
* @return The current width of the RDP display, in pixels. * The RDP instance to retrieve the width from.
*
* @return
* The current width of the RDP display, in pixels.
*/ */
int guac_rdp_get_width(freerdp* rdp); int guac_rdp_get_width(freerdp* rdp);
/** /**
* Returns the height of the RDP session display. * Returns the height of the RDP session display.
* *
* @param rdp The RDP instance to retrieve the height from. * @param rdp
* @return The current height of the RDP display, in pixels. * The RDP instance to retrieve the height from.
*
* @return
* The current height of the RDP display, in pixels.
*/ */
int guac_rdp_get_height(freerdp* rdp); int guac_rdp_get_height(freerdp* rdp);
/** /**
* Returns the depth of the RDP session display. * Returns the depth of the RDP session display.
* *
* @param rdp The RDP instance to retrieve the depth from. * @param rdp
* @return The current depth of the RDP display, in bits per pixel. * The RDP instance to retrieve the depth from.
*
* @return
* The current depth of the RDP display, in bits per pixel.
*/ */
int guac_rdp_get_depth(freerdp* rdp); int guac_rdp_get_depth(freerdp* rdp);

View File

@ -66,16 +66,22 @@ typedef struct guac_rdp_svc {
/** /**
* Allocate a new SVC with the given name. * Allocate a new SVC with the given name.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param name The name of the virtual channel to allocate. * The guac_client associated with the current RDP session.
* @return A newly-allocated static virtual channel. *
* @param name
* The name of the virtual channel to allocate.
*
* @return
* A newly-allocated static virtual channel.
*/ */
guac_rdp_svc* guac_rdp_alloc_svc(guac_client* client, char* name); guac_rdp_svc* guac_rdp_alloc_svc(guac_client* client, char* name);
/** /**
* Free the given SVC. * Free the given SVC.
* *
* @param svc The static virtual channel to free. * @param svc
* The static virtual channel to free.
*/ */
void guac_rdp_free_svc(guac_rdp_svc* svc); void guac_rdp_free_svc(guac_rdp_svc* svc);
@ -107,7 +113,8 @@ void guac_rdp_svc_send_pipes(guac_user* user);
/** /**
* Add the given SVC to the list of all available SVCs. * Add the given SVC to the list of all available SVCs.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* The guac_client associated with the current RDP session.
* *
* @param svc * @param svc
* The static virtual channel to add to the list of all such channels * The static virtual channel to add to the list of all such channels
@ -118,8 +125,11 @@ void guac_rdp_add_svc(guac_client* client, guac_rdp_svc* svc);
/** /**
* Retrieve the SVC with the given name from the list stored in the client. * Retrieve the SVC with the given name from the list stored in the client.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param name The name of the static virtual channel to retrieve. * The guac_client associated with the current RDP session.
*
* @param name
* The name of the static virtual channel to retrieve.
* *
* @return * @return
* The static virtual channel with the given name, or NULL if no such * The static virtual channel with the given name, or NULL if no such
@ -130,8 +140,11 @@ guac_rdp_svc* guac_rdp_get_svc(guac_client* client, const char* name);
/** /**
* Remove the SVC with the given name from the list stored in the client. * Remove the SVC with the given name from the list stored in the client.
* *
* @param client The guac_client associated with the current RDP session. * @param client
* @param name The name of the static virtual channel to remove. * The guac_client associated with the current RDP session.
*
* @param name
* The name of the static virtual channel to remove.
* *
* @return * @return
* The static virtual channel that was removed, or NULL if no such virtual * The static virtual channel that was removed, or NULL if no such virtual
@ -142,9 +155,14 @@ guac_rdp_svc* guac_rdp_remove_svc(guac_client* client, const char* name);
/** /**
* Write the given blob of data to the virtual channel. * Write the given blob of data to the virtual channel.
* *
* @param svc The static virtual channel to write data to. * @param svc
* @param data The data to write. * The static virtual channel to write data to.
* @param length The number of bytes to write. *
* @param data
* The data to write.
*
* @param length
* The number of bytes to write.
*/ */
void guac_rdp_svc_write(guac_rdp_svc* svc, void* data, int length); void guac_rdp_svc_write(guac_rdp_svc* svc, void* data, int length);

View File

@ -29,9 +29,14 @@
* Returns whether the given resolution is reasonable for the given user, * Returns whether the given resolution is reasonable for the given user,
* based on arbitrary criteria for reasonability. * based on arbitrary criteria for reasonability.
* *
* @param user The guac_user to test the given resolution against. * @param user
* @param resolution The resolution to test, in DPI. * The guac_user to test the given resolution against.
* @return Non-zero if the resolution is reasonable, zero otherwise. *
* @param resolution
* The resolution to test, in DPI.
*
* @return
* Non-zero if the resolution is reasonable, zero otherwise.
*/ */
int guac_rdp_resolution_reasonable(guac_user* user, int resolution); int guac_rdp_resolution_reasonable(guac_user* user, int resolution);
@ -39,9 +44,12 @@ int guac_rdp_resolution_reasonable(guac_user* user, int resolution);
* Returns a reasonable resolution for the remote display, given the size and * Returns a reasonable resolution for the remote display, given the size and
* resolution of a guac_user. * resolution of a guac_user.
* *
* @param user The guac_user whose size and resolution shall be used to * @param user
* determine an appropriate remote display resolution. * The guac_user whose size and resolution shall be used to determine an
* @return A reasonable resolution for the remote display, in DPI. * appropriate remote display resolution.
*
* @return
* A reasonable resolution for the remote display, in DPI.
*/ */
int guac_rdp_suggest_resolution(guac_user* user); int guac_rdp_suggest_resolution(guac_user* user);

View File

@ -26,10 +26,17 @@
/** /**
* Convert the given number of UTF-16 characters to UTF-8 characters. * Convert the given number of UTF-16 characters to UTF-8 characters.
* *
* @param utf16 Arbitrary UTF-16 data. * @param utf16
* @param length The length of the UTF-16 data, in characters. * Arbitrary UTF-16 data.
* @param utf8 Buffer to which the converted UTF-8 data will be written. *
* @param size The maximum number of bytes available in the UTF-8 buffer. * @param length
* The length of the UTF-16 data, in characters.
*
* @param utf8
* Buffer to which the converted UTF-8 data will be written.
*
* @param size
* The maximum number of bytes available in the UTF-8 buffer.
*/ */
void guac_rdp_utf16_to_utf8(const unsigned char* utf16, int length, void guac_rdp_utf16_to_utf8(const unsigned char* utf16, int length,
char* utf8, int size); char* utf8, int size);
@ -37,10 +44,17 @@ void guac_rdp_utf16_to_utf8(const unsigned char* utf16, int length,
/** /**
* Convert the given number of UTF-8 characters to UTF-16 characters. * Convert the given number of UTF-8 characters to UTF-16 characters.
* *
* @param utf8 Arbitrary UTF-8 data. * @param utf8
* @param length The length of the UTF-8 data, in characters. * Arbitrary UTF-8 data.
* @param utf16 Buffer to which the converted UTF-16 data will be written. *
* @param size The maximum number of bytes available in the UTF-16 buffer. * @param length
* The length of the UTF-8 data, in characters.
*
* @param utf16
* Buffer to which the converted UTF-16 data will be written.
*
* @param size
* The maximum number of bytes available in the UTF-16 buffer.
*/ */
void guac_rdp_utf8_to_utf16(const unsigned char* utf8, int length, void guac_rdp_utf8_to_utf16(const unsigned char* utf8, int length,
char* utf16, int size); char* utf16, int size);