From 63f3652c54c8a1d13689baa147ae8a405c2f84d8 Mon Sep 17 00:00:00 2001
From: Michael Jumper <mike.jumper@guac-dev.org>
Date: Mon, 2 Nov 2015 17:15:35 -0800
Subject: [PATCH] GUAC-1196: Document RDPSND message handlers.

---
 .../rdp/guac_rdpsnd/rdpsnd_messages.h         | 82 +++++++++++++++++--
 1 file changed, 77 insertions(+), 5 deletions(-)

diff --git a/src/protocols/rdp/guac_rdpsnd/rdpsnd_messages.h b/src/protocols/rdp/guac_rdpsnd/rdpsnd_messages.h
index 8050c4a9..f75235a9 100644
--- a/src/protocols/rdp/guac_rdpsnd/rdpsnd_messages.h
+++ b/src/protocols/rdp/guac_rdpsnd/rdpsnd_messages.h
@@ -120,31 +120,103 @@ typedef struct guac_rdpsnd_pdu_header {
 } guac_rdpsnd_pdu_header;
 
 /**
- * Handler for the SNDC_FORMATS (Server Audio Formats and Version) PDU.
+ * Handler for the SNDC_FORMATS (Server Audio Formats and Version) PDU. The
+ * SNDC_FORMATS PDU describes all audio formats supported by the RDP server, as
+ * well as the version of RDPSND implemented.
+ *
+ * @param rdpsnd
+ *     The Guacamole RDPSND plugin receiving the SNDC_FORMATS PDU.
+ *
+ * @param input_stream
+ *     The FreeRDP input stream containing the remaining raw bytes (after the
+ *     common header) of the SNDC_FORMATS PDU.
+ *
+ * @param header
+ *     The header content of the SNDC_FORMATS PDU. All RDPSND messages contain
+ *     the same header information.
  */
 void guac_rdpsnd_formats_handler(guac_rdpsndPlugin* rdpsnd,
         wStream* input_stream, guac_rdpsnd_pdu_header* header);
 
 /**
- * Handler for the SNDC_TRAINING (Training) PDU.
+ * Handler for the SNDC_TRAINING (Training) PDU. The SNDC_TRAINING PDU is used
+ * to by RDP servers to test audio streaming latency, etc. without actually
+ * sending audio data. See:
+ *
+ * https://msdn.microsoft.com/en-us/library/cc240961.aspx
+ *
+ * @param rdpsnd
+ *     The Guacamole RDPSND plugin receiving the SNDC_TRAINING PDU.
+ *
+ * @param input_stream
+ *     The FreeRDP input stream containing the remaining raw bytes (after the
+ *     common header) of the SNDC_TRAINING PDU.
+ *
+ * @param header
+ *     The header content of the SNDC_TRAINING PDU. All RDPSND messages contain
+ *     the same header information.
  */
 void guac_rdpsnd_training_handler(guac_rdpsndPlugin* rdpsnd,
         wStream* input_stream, guac_rdpsnd_pdu_header* header);
 
 /**
- * Handler for the SNDC_WAVE (WaveInfo) PDU.
+ * Handler for the SNDC_WAVE (WaveInfo) PDU. The SNDC_WAVE immediately precedes
+ * a SNDWAV PDU and describes the data about to be received. It also (very
+ * strangely) contains exactly 4 bytes of audio data. The following SNDWAV PDU
+ * then contains 4 bytes of padding prior to the audio data where it would make
+ * perfect sense for this data to go. See:
+ *
+ * https://msdn.microsoft.com/en-us/library/cc240963.aspx
+ *
+ * @param rdpsnd
+ *     The Guacamole RDPSND plugin receiving the SNDC_WAVE PDU.
+ *
+ * @param input_stream
+ *     The FreeRDP input stream containing the remaining raw bytes (after the
+ *     common header) of the SNDC_WAVE PDU.
+ *
+ * @param header
+ *     The header content of the SNDC_WAVE PDU. All RDPSND messages contain
+ *     the same header information.
  */
 void guac_rdpsnd_wave_info_handler(guac_rdpsndPlugin* rdpsnd,
         wStream* input_stream, guac_rdpsnd_pdu_header* header);
 
 /**
- * Handler for the SNDWAV (Wave) PDU which follows any WaveInfo PDU.
+ * Handler for the SNDWAV (Wave) PDU which follows any WaveInfo PDU. The SNDWAV
+ * PDU contains the actual audio data, less the four bytes of audio data
+ * included in the SNDC_WAVE PDU.
+ *
+ * @param rdpsnd
+ *     The Guacamole RDPSND plugin receiving the SNDWAV PDU.
+ *
+ * @param input_stream
+ *     The FreeRDP input stream containing the remaining raw bytes (after the
+ *     common header) of the SNDWAV PDU.
+ *
+ * @param header
+ *     The header content of the SNDWAV PDU. All RDPSND messages contain
+ *     the same header information.
  */
 void guac_rdpsnd_wave_handler(guac_rdpsndPlugin* rdpsnd,
         wStream* input_stream, guac_rdpsnd_pdu_header* header);
 
 /**
- * Handler for the SNDC_CLOSE (Close) PDU.
+ * Handler for the SNDC_CLOSE (Close) PDU. This PDU is sent when audio
+ * streaming has stopped. This PDU is currently ignored by Guacamole. See:
+ *
+ * https://msdn.microsoft.com/en-us/library/cc240970.aspx
+ *
+ * @param rdpsnd
+ *     The Guacamole RDPSND plugin receiving the SNDC_CLOSE PDU.
+ *
+ * @param input_stream
+ *     The FreeRDP input stream containing the remaining raw bytes (after the
+ *     common header) of the SNDC_CLOSE PDU.
+ *
+ * @param header
+ *     The header content of the SNDC_CLOSE PDU. All RDPSND messages contain
+ *     the same header information.
  */
 void guac_rdpsnd_close_handler(guac_rdpsndPlugin* rdpsnd,
         wStream* input_stream, guac_rdpsnd_pdu_header* header);