From 63f3652c54c8a1d13689baa147ae8a405c2f84d8 Mon Sep 17 00:00:00 2001 From: Michael Jumper 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);