GUACAMOLE-249: Document absolutely all parameters and return types for RDP support.

src/protocols/rdp/bitmap.h

@@ -60,6 +60,9 @@ typedef struct guac_rdp_bitmap {
  *
  * @param bitmap
  *     The bitmap to cache.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_cache_bitmap(rdpContext* context, rdpBitmap* bitmap);
 
@@ -71,6 +74,9 @@ BOOL guac_rdp_cache_bitmap(rdpContext* context, rdpBitmap* bitmap);
  *
  * @param bitmap
  *     The bitmap to initialize.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_bitmap_new(rdpContext* context, rdpBitmap* bitmap);
 
@@ -86,6 +92,9 @@ BOOL guac_rdp_bitmap_new(rdpContext* context, rdpBitmap* bitmap);
  *     The bitmap to paint. This structure will also contain the specifics of
  *     the paint operation to perform, including the destination X/Y
  *     coordinates.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_bitmap_paint(rdpContext* context, rdpBitmap* bitmap);
 
@@ -116,6 +125,9 @@ void guac_rdp_bitmap_free(rdpContext* context, rdpBitmap* bitmap);
  *     TRUE if the bitmap parameter should be ignored, and the current drawing
  *     surface should be reset to the primary drawing surface of the remote
  *     display, FALSE otherwise.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_bitmap_setsurface(rdpContext* context, rdpBitmap* bitmap,
         BOOL primary);

src/protocols/rdp/gdi.h

@@ -45,57 +45,94 @@ guac_composite_mode guac_rdp_rop3_transfer_function(guac_client* client,
         int rop3);
 
 /**
- * Handler for RDP DSTBLT update.
+ * Handler for the DstBlt Primary Drawing Order. A DstBlt Primary Drawing Order
+ * paints a rectangle of image data using a raster operation which considers
+ * the destination only. See:
+ *
+ * https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpegdi/87ea30df-59d6-438e-a735-83f0225fbf91
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
  *
  * @param dstblt
  *     The DSTBLT update to handle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_dstblt(rdpContext* context, const DSTBLT_ORDER* dstblt);
 
 /**
- * Handler for RDP PATBLT update.
+ * Handler for the PatBlt Primary Drawing Order. A PatBlt Primary Drawing Order
+ * paints a rectangle of image data, a brush pattern, and a three-way raster
+ * operation which considers the source data, the destination, AND the brush
+ * pattern. See:
+ *
+ * https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpegdi/bd4bf5e7-b988-45f9-8201-3b22cc9aeeb8
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
  *
  * @param patblt
  *     The PATBLT update to handle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_patblt(rdpContext* context, PATBLT_ORDER* patblt);
 
 /**
- * Handler for RDP SCRBLT update.
+ * Handler for the ScrBlt Primary Drawing Order. A ScrBlt Primary Drawing Order
+ * paints a rectangle of image data using a raster operation which considers
+ * the source and destination.  See:
+ *
+ * https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpegdi/a4e322b0-cd64-4dfc-8e1a-f24dc0edc99d
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
  *
  * @param scrblt
  *     The SCRBLT update to handle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_scrblt(rdpContext* context, const SCRBLT_ORDER* scrblt);
 
 /**
- * Handler for RDP MEMBLT update.
+ * Handler for the MemBlt Primary Drawing Order. A MemBlt Primary Drawing Order
+ * paints a rectangle of cached image data from a cached surface to the screen
+ * using a raster operation which considers the source and destination. See:
+ *
+ * https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpegdi/84c2ec2f-f776-405b-9b48-6894a28b1b14
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
  *
  * @param memblt
  *     The MEMBLT update to handle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_memblt(rdpContext* context, MEMBLT_ORDER* memblt);
 
 /**
- * Handler for RDP OPAQUE RECT update.
+ * Handler for the OpaqueRect Primary Drawing Order. An OpaqueRect Primary
+ * Drawing Order draws an opaque rectangle of a single solid color. Note that
+ * support for OpaqueRect cannot be claimed without also supporting PatBlt, as
+ * both use the same negotiation order number. See:
+ *
+ * https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpegdi/1eead7aa-ac63-411a-9f8c-b1b227526877
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
  *
  * @param opaque_rect
  *     The OPAQUE RECT update to handle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_opaquerect(rdpContext* context,
         const OPAQUE_RECT_ORDER* opaque_rect);
@@ -112,6 +149,9 @@ BOOL guac_rdp_gdi_opaquerect(rdpContext* context,
  * @param bounds
  *     The clipping rectangle to set, or NULL to remove any applied clipping
  *     rectangle.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_set_bounds(rdpContext* context, const rdpBounds* bounds);
 
@@ -121,6 +161,9 @@ BOOL guac_rdp_gdi_set_bounds(rdpContext* context, const rdpBounds* bounds);
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_end_paint(rdpContext* context);
 
@@ -135,6 +178,9 @@ BOOL guac_rdp_gdi_end_paint(rdpContext* context);
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_gdi_desktop_resize(rdpContext* context);
 

src/protocols/rdp/plugins/guacai/guacai-messages.c

@@ -107,6 +107,19 @@ static void guac_rdp_ai_send_incoming_data(IWTSVirtualChannel* channel) {
 
 }
 
+/**
+ * Sends a Data PDU along the given channel. A Data PDU is used by the client
+ * to send actual audio data following a Data Incoming PDU.
+ *
+ * @param channel
+ *     The channel along which the PDU should be sent.
+ *
+ * @param buffer
+ *     The audio data to send.
+ *
+ * @param length
+ *     The number of bytes of audio data to send.
+ */
 static void guac_rdp_ai_send_data(IWTSVirtualChannel* channel,
         char* buffer, int length) {
 
@@ -280,7 +293,7 @@ void guac_rdp_ai_process_formats(guac_client* client,
 
 }
 
-static void guac_rdp_ai_flush_packet(char* buffer, int length, void* data) {
+void guac_rdp_ai_flush_packet(char* buffer, int length, void* data) {
 
     IWTSVirtualChannel* channel = (IWTSVirtualChannel*) data;
 

src/protocols/rdp/plugins/guacai/guacai-messages.h

@@ -207,5 +207,14 @@ void guac_rdp_ai_process_open(guac_client* client,
 void guac_rdp_ai_process_formatchange(guac_client* client,
         IWTSVirtualChannel* channel, wStream* stream);
 
+/**
+ * Audio buffer flush handler which sends audio data along the active audio
+ * input channel using a Data Incoming PDU and Data PDU. The arbitrary data
+ * provided to the handler by the audio buffer implementation is in this case
+ * the IWTSVirtualChannel structure representing the active audio input
+ * channel.
+ */
+guac_rdp_audio_buffer_flush_handler guac_rdp_ai_flush_packet;
+
 #endif
 

src/protocols/rdp/pointer.h

@@ -51,6 +51,9 @@ typedef struct guac_rdp_pointer {
  *
  * @param pointer
  *     The pointer to cache.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_pointer_new(rdpContext* context, rdpPointer* pointer);
 
@@ -63,6 +66,9 @@ BOOL guac_rdp_pointer_new(rdpContext* context, rdpPointer* pointer);
  *
  * @param pointer
  *     The pointer to set as the current mouse pointer.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_pointer_set(rdpContext* context, const rdpPointer* pointer);
 
@@ -83,6 +89,9 @@ void guac_rdp_pointer_free(rdpContext* context, rdpPointer* pointer);
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_pointer_set_null(rdpContext* context);
 
@@ -92,6 +101,9 @@ BOOL guac_rdp_pointer_set_null(rdpContext* context);
  *
  * @param context
  *     The rdpContext associated with the current RDP session.
+ *
+ * @return
+ *     TRUE if successful, FALSE otherwise.
  */
 BOOL guac_rdp_pointer_set_default(rdpContext* context);
 

src/protocols/rdp/print-job.h

@@ -79,6 +79,9 @@ typedef enum guac_rdp_print_job_state {
  */
 typedef struct guac_rdp_print_job {
 
+    /**
+     * The Guacamole client associated with the RDP session.
+     */
     guac_client* client;
 
     /**

src/protocols/rdp/stream.c

@@ -39,6 +39,13 @@
 /**
  * Writes the given filename to the given upload path, sanitizing the filename
  * and translating the filename to the root directory.
+ *
+ * @param filename
+ *     The filename to sanitize and move to the root directory.
+ *
+ * @param path
+ *     A pointer to a buffer which should receive the sanitized path. The
+ *     buffer must hav at least GUAC_RDP_FS_MAX_PATH bytes available.
  */
 static void __generate_upload_path(const char* filename, char* path) {