GUACAMOLE-249: Document absolutely all parameters and return types for RDP support.
diff --git a/src/protocols/rdp/bitmap.h b/src/protocols/rdp/bitmap.h
index 6ccd04f..70068b5 100644
--- a/src/protocols/rdp/bitmap.h
+++ b/src/protocols/rdp/bitmap.h
@@ -60,6 +60,9 @@
*
* @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 @@
*
* @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 @@
* 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 @@
* 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);
diff --git a/src/protocols/rdp/gdi.h b/src/protocols/rdp/gdi.h
index 983a6e6..006e61e 100644
--- a/src/protocols/rdp/gdi.h
+++ b/src/protocols/rdp/gdi.h
@@ -45,57 +45,94 @@
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 @@
* @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 @@
*
* @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 @@
*
* @param context
* The rdpContext associated with the current RDP session.
+ *
+ * @return
+ * TRUE if successful, FALSE otherwise.
*/
BOOL guac_rdp_gdi_desktop_resize(rdpContext* context);
diff --git a/src/protocols/rdp/plugins/guacai/guacai-messages.c b/src/protocols/rdp/plugins/guacai/guacai-messages.c
index 083d7ae..bb759e5 100644
--- a/src/protocols/rdp/plugins/guacai/guacai-messages.c
+++ b/src/protocols/rdp/plugins/guacai/guacai-messages.c
@@ -107,6 +107,19 @@
}
+/**
+ * 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 @@
}
-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;
diff --git a/src/protocols/rdp/plugins/guacai/guacai-messages.h b/src/protocols/rdp/plugins/guacai/guacai-messages.h
index a2d3505..91173c3 100644
--- a/src/protocols/rdp/plugins/guacai/guacai-messages.h
+++ b/src/protocols/rdp/plugins/guacai/guacai-messages.h
@@ -207,5 +207,14 @@
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
diff --git a/src/protocols/rdp/pointer.h b/src/protocols/rdp/pointer.h
index 7f4547b..c5ba319 100644
--- a/src/protocols/rdp/pointer.h
+++ b/src/protocols/rdp/pointer.h
@@ -51,6 +51,9 @@
*
* @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 @@
*
* @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 @@
*
* @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 @@
*
* @param context
* The rdpContext associated with the current RDP session.
+ *
+ * @return
+ * TRUE if successful, FALSE otherwise.
*/
BOOL guac_rdp_pointer_set_default(rdpContext* context);
diff --git a/src/protocols/rdp/print-job.h b/src/protocols/rdp/print-job.h
index 5682f18..98897ec 100644
--- a/src/protocols/rdp/print-job.h
+++ b/src/protocols/rdp/print-job.h
@@ -79,6 +79,9 @@
*/
typedef struct guac_rdp_print_job {
+ /**
+ * The Guacamole client associated with the RDP session.
+ */
guac_client* client;
/**
diff --git a/src/protocols/rdp/stream.c b/src/protocols/rdp/stream.c
index 21391a5..71fd035 100644
--- a/src/protocols/rdp/stream.c
+++ b/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) {
