From 7aa80cb751c495f0d36b1cc91a2d33d4045d68ea Mon Sep 17 00:00:00 2001 From: akallabeth Date: Thu, 12 Sep 2024 10:50:38 +0200 Subject: [PATCH] [documentation] update * Fix wrong tag @version, replace with @since * Document some functions --- include/config/config.h.in | 18 ++++---- include/config/settings_keys.h.in | 20 ++++----- include/freerdp/channels/audin.h | 4 +- include/freerdp/channels/cliprdr.h | 2 +- include/freerdp/channels/drdynvc.h | 2 +- include/freerdp/channels/echo.h | 2 +- include/freerdp/channels/encomsp.h | 2 +- include/freerdp/channels/geometry.h | 2 +- include/freerdp/channels/location.h | 2 +- include/freerdp/channels/rdpdr.h | 2 +- include/freerdp/channels/rdpecam.h | 2 +- include/freerdp/channels/rdpei.h | 2 +- include/freerdp/channels/rdpemsc.h | 4 +- include/freerdp/channels/rdpewa.h | 2 +- include/freerdp/channels/rdpgfx.h | 2 +- include/freerdp/channels/remdesk.h | 2 +- include/freerdp/channels/telemetry.h | 2 +- include/freerdp/channels/tsmf.h | 2 +- include/freerdp/channels/urbdrc.h | 2 +- include/freerdp/channels/video.h | 2 +- include/freerdp/client/cmdline.h | 8 ++-- include/freerdp/codec/audio.h | 2 +- include/freerdp/codec/progressive.h | 2 +- include/freerdp/codec/rfx.h | 8 ++-- include/freerdp/crypto/certificate_store.h | 2 +- include/freerdp/crypto/crypto.h | 2 +- include/freerdp/utils/aad.h | 4 +- include/freerdp/utils/encoded_types.h | 49 ++++++++++++++++++---- 28 files changed, 93 insertions(+), 62 deletions(-) diff --git a/include/config/config.h.in b/include/config/config.h.in index 1310ec8f4..a0a73f32d 100644 --- a/include/config/config.h.in +++ b/include/config/config.h.in @@ -14,7 +14,7 @@ /** If set the rdpSettings struct is opaque and internals can only be accessed * through getters/setters * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine WITH_OPAQUE_SETTINGS @@ -42,7 +42,7 @@ #cmakedefine WITH_LAME /** If defined Opus codec support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine WITH_OPUS #cmakedefine WITH_FAAD2 @@ -103,17 +103,17 @@ #cmakedefine CHANNEL_GFXREDIR_SERVER /** If defined location channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_LOCATION /** If defined location client side channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_LOCATION_CLIENT /** If defined location server side channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_LOCATION_SERVER #cmakedefine CHANNEL_PARALLEL @@ -142,19 +142,19 @@ #cmakedefine CHANNEL_RDPGFX_SERVER /** If defined mouse cursor channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_RDPEMSC /** If defined mouse cursor channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_RDPEMSC_CLIENT /** If defined mouse cursor channel support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine CHANNEL_RDPEMSC_SERVER #cmakedefine CHANNEL_RDPSND @@ -223,7 +223,7 @@ /** If defined linux/vm_sockets.h support is available. * - * \version 3.0.0 + * \since version 3.0.0 */ #cmakedefine HAVE_AF_VSOCK_H diff --git a/include/config/settings_keys.h.in b/include/config/settings_keys.h.in index 50525ca29..32fd2353b 100644 --- a/include/config/settings_keys.h.in +++ b/include/config/settings_keys.h.in @@ -30,7 +30,7 @@ extern "C" /** A list of available settings keys of type BOOL * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -39,7 +39,7 @@ typedef enum /** A list of available settings keys of type INT16 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -48,7 +48,7 @@ typedef enum /** A list of available settings keys of type UINT16 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -57,7 +57,7 @@ typedef enum /** A list of available settings keys of type INT32 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -66,7 +66,7 @@ typedef enum /** A list of available settings keys of type UINT32 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -75,7 +75,7 @@ typedef enum /** A list of available settings keys of type INT64 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -84,7 +84,7 @@ typedef enum /** A list of available settings keys of type UINT64 * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -93,7 +93,7 @@ typedef enum /** A list of available settings keys of type STRING * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -102,7 +102,7 @@ typedef enum /** A list of available settings keys of type POINTER * - * \version 3.0.0 + * \since version 3.0.0 */ typedef enum { @@ -112,7 +112,7 @@ typedef enum /** Highest indes in the rdpSettings stable API * - * \version 3.0.0 + * \since version 3.0.0 */ #define FreeRDP_Settings_StableAPI_MAX 5312 diff --git a/include/freerdp/channels/audin.h b/include/freerdp/channels/audin.h index e00e9e19a..1bb0e86c3 100644 --- a/include/freerdp/channels/audin.h +++ b/include/freerdp/channels/audin.h @@ -28,13 +28,13 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define AUDIN_CHANNEL_NAME "audin" /** The name of the channel (protocol internal) * - * \version 3.0.0 + * \since version 3.0.0 */ #define AUDIN_DVC_CHANNEL_NAME "AUDIO_INPUT" diff --git a/include/freerdp/channels/cliprdr.h b/include/freerdp/channels/cliprdr.h index 4f766e52d..9e3d62b3a 100644 --- a/include/freerdp/channels/cliprdr.h +++ b/include/freerdp/channels/cliprdr.h @@ -28,7 +28,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define CLIPRDR_CHANNEL_NAME "cliprdr" #define CLIPRDR_SVC_CHANNEL_NAME "cliprdr" diff --git a/include/freerdp/channels/drdynvc.h b/include/freerdp/channels/drdynvc.h index 41d4906c8..7d49e157c 100644 --- a/include/freerdp/channels/drdynvc.h +++ b/include/freerdp/channels/drdynvc.h @@ -27,7 +27,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define DRDYNVC_CHANNEL_NAME "drdynvc" #define DRDYNVC_SVC_CHANNEL_NAME "drdynvc" diff --git a/include/freerdp/channels/echo.h b/include/freerdp/channels/echo.h index 18cbc8620..346be31f8 100644 --- a/include/freerdp/channels/echo.h +++ b/include/freerdp/channels/echo.h @@ -27,7 +27,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define ECHO_CHANNEL_NAME "echo" #define ECHO_DVC_CHANNEL_NAME "ECHO" diff --git a/include/freerdp/channels/encomsp.h b/include/freerdp/channels/encomsp.h index bde6c3191..d13570bbf 100644 --- a/include/freerdp/channels/encomsp.h +++ b/include/freerdp/channels/encomsp.h @@ -30,7 +30,7 @@ extern "C" /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define ENCOMSP_CHANNEL_NAME "encomsp" #define ENCOMSP_SVC_CHANNEL_NAME "encomsp" diff --git a/include/freerdp/channels/geometry.h b/include/freerdp/channels/geometry.h index d9ffb1cc5..14ada2452 100644 --- a/include/freerdp/channels/geometry.h +++ b/include/freerdp/channels/geometry.h @@ -25,7 +25,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define GEOMETRY_CHANNEL_NAME "geometry" #define GEOMETRY_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Geometry::v08.01" diff --git a/include/freerdp/channels/location.h b/include/freerdp/channels/location.h index 6f0007834..f724fbbdc 100644 --- a/include/freerdp/channels/location.h +++ b/include/freerdp/channels/location.h @@ -26,7 +26,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define LOCATION_CHANNEL_NAME "location" diff --git a/include/freerdp/channels/rdpdr.h b/include/freerdp/channels/rdpdr.h index 1e2691c0f..f97aea6d8 100644 --- a/include/freerdp/channels/rdpdr.h +++ b/include/freerdp/channels/rdpdr.h @@ -44,7 +44,7 @@ extern "C" /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPDR_CHANNEL_NAME "rdpdr" #define RDPDR_SVC_CHANNEL_NAME "rdpdr" diff --git a/include/freerdp/channels/rdpecam.h b/include/freerdp/channels/rdpecam.h index 615d8eebe..534f3210e 100644 --- a/include/freerdp/channels/rdpecam.h +++ b/include/freerdp/channels/rdpecam.h @@ -26,7 +26,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPECAM_CHANNEL_NAME "rdpecam" #define RDPECAM_DVC_CHANNEL_NAME "rdpecam" diff --git a/include/freerdp/channels/rdpei.h b/include/freerdp/channels/rdpei.h index 388a7f183..0555d911f 100644 --- a/include/freerdp/channels/rdpei.h +++ b/include/freerdp/channels/rdpei.h @@ -33,7 +33,7 @@ extern "C" /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPEI_CHANNEL_NAME "rdpei" #define RDPEI_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Input" diff --git a/include/freerdp/channels/rdpemsc.h b/include/freerdp/channels/rdpemsc.h index 9c0614d19..2bdfb5812 100644 --- a/include/freerdp/channels/rdpemsc.h +++ b/include/freerdp/channels/rdpemsc.h @@ -23,7 +23,7 @@ /** \file [MS-RDPEMSC] Mouse Cursor Virtual Channel Extension * \link * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpemsc/2591b507-cd5a-4537-be29-b45540543dc8 - * \version 3.0.0 + * \since version 3.0.0 */ #include #include @@ -31,7 +31,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPEMSC_CHANNEL_NAME "mousecursor" #define RDPEMSC_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::MouseCursor" diff --git a/include/freerdp/channels/rdpewa.h b/include/freerdp/channels/rdpewa.h index 37895c64c..6005d5673 100644 --- a/include/freerdp/channels/rdpewa.h +++ b/include/freerdp/channels/rdpewa.h @@ -27,7 +27,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPEWA_CHANNEL_NAME "rdpewa" #define RDPEWA_DVC_CHANNEL_NAME "rdpewa" diff --git a/include/freerdp/channels/rdpgfx.h b/include/freerdp/channels/rdpgfx.h index a7f8555e5..6efe3bdb8 100644 --- a/include/freerdp/channels/rdpgfx.h +++ b/include/freerdp/channels/rdpgfx.h @@ -26,7 +26,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define RDPGFX_CHANNEL_NAME "rdpgfx" #define RDPGFX_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Graphics" diff --git a/include/freerdp/channels/remdesk.h b/include/freerdp/channels/remdesk.h index 05eeedc30..a259e6f44 100644 --- a/include/freerdp/channels/remdesk.h +++ b/include/freerdp/channels/remdesk.h @@ -30,7 +30,7 @@ extern "C" /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define REMDESK_CHANNEL_NAME "remdesk" #define REMDESK_SVC_CHANNEL_NAME "remdesk" diff --git a/include/freerdp/channels/telemetry.h b/include/freerdp/channels/telemetry.h index 5a809f7b6..df992d020 100644 --- a/include/freerdp/channels/telemetry.h +++ b/include/freerdp/channels/telemetry.h @@ -26,7 +26,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define TELEMETRY_CHANNEL_NAME "telemetry" #define TELEMETRY_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Telemetry" diff --git a/include/freerdp/channels/tsmf.h b/include/freerdp/channels/tsmf.h index 6a9a8d3a8..6d58080d9 100644 --- a/include/freerdp/channels/tsmf.h +++ b/include/freerdp/channels/tsmf.h @@ -32,7 +32,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define TSMF_CHANNEL_NAME "tsmf" #define TSMF_DVC_CHANNEL_NAME "TSMF" diff --git a/include/freerdp/channels/urbdrc.h b/include/freerdp/channels/urbdrc.h index 5efdfbd1d..1dc51ff48 100644 --- a/include/freerdp/channels/urbdrc.h +++ b/include/freerdp/channels/urbdrc.h @@ -27,7 +27,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define URBDRC_CHANNEL_NAME "urbdrc" #define URBDRC_DVC_CHANNEL_NAME "urbdrc" diff --git a/include/freerdp/channels/video.h b/include/freerdp/channels/video.h index 01d1a3356..72686357b 100644 --- a/include/freerdp/channels/video.h +++ b/include/freerdp/channels/video.h @@ -25,7 +25,7 @@ /** The command line name of the channel * - * \version 3.0.0 + * \since version 3.0.0 */ #define VIDEO_CHANNEL_NAME "video" #define VIDEO_CONTROL_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Video::Control::v08.01" diff --git a/include/freerdp/client/cmdline.h b/include/freerdp/client/cmdline.h index 2b05e530b..7079692e2 100644 --- a/include/freerdp/client/cmdline.h +++ b/include/freerdp/client/cmdline.h @@ -56,7 +56,7 @@ extern "C" * \param handle_option the handler function for custom arguments. * \param handle_userdata custom data supplied to \b handle_option as context * - * \version 3.0.0 + * \since version 3.0.0 * * \return \b 0 in case of success, a negative number in case of failure. */ @@ -77,19 +77,19 @@ extern "C" /** Print a command line warning about the component being unmaintained. * - * \version 3.0.0 + * \since version 3.0.0 */ FREERDP_API void freerdp_client_warn_unmaintained(int argc, char* argv[]); /** Print a command line warning about the component being experimental. * - * \version 3.0.0 + * \since version 3.0.0 */ FREERDP_API void freerdp_client_warn_experimental(int argc, char* argv[]); /** Print a command line warning about the component being deprecated. * - * \version 3.0.0 + * \since version 3.0.0 */ FREERDP_API void freerdp_client_warn_deprecated(int argc, char* argv[]); diff --git a/include/freerdp/codec/audio.h b/include/freerdp/codec/audio.h index d47cdc3e5..f5e5040b2 100644 --- a/include/freerdp/codec/audio.h +++ b/include/freerdp/codec/audio.h @@ -192,7 +192,7 @@ extern "C" #endif /* !WAVE_FORMAT_LUCENT_G723 */ /** Opus format identifier - * \version 3.0.0 + * \since version 3.0.0 */ #define WAVE_FORMAT_OPUS 0x704F #define WAVE_FORMAT_AAC_MS 0xA106 diff --git a/include/freerdp/codec/progressive.h b/include/freerdp/codec/progressive.h index 1066d76ef..5aff2a22a 100644 --- a/include/freerdp/codec/progressive.h +++ b/include/freerdp/codec/progressive.h @@ -76,7 +76,7 @@ extern "C" * @param s The stream to write to * @param msg The message to encode * - * @version 3.0.0 + * @since version 3.0.0 * @return \b TRUE in case of success, \b FALSE for any error */ FREERDP_API BOOL progressive_rfx_write_message_progressive_simple( diff --git a/include/freerdp/codec/rfx.h b/include/freerdp/codec/rfx.h index 6b20cf1b6..9b9031a28 100644 --- a/include/freerdp/codec/rfx.h +++ b/include/freerdp/codec/rfx.h @@ -128,7 +128,7 @@ extern "C" /** Getter for RFX mode * @param context The RFX context to query * - * @version 3.0.0 + * @since version 3.0.0 * * @return The RFX mode that is currently in use */ @@ -139,7 +139,7 @@ extern "C" /** Getter for RFX pixel format * @param context The RFX context to query * - * @version 3.0.0 + * @since version 3.0.0 * * @return The RFX pixel format that is currently in use */ @@ -150,7 +150,7 @@ extern "C" /** Getter for RFX palette * @param context The RFX context to query * - * @version 3.0.0 + * @since version 3.0.0 * * @return The RFX palette that is currently in use or \b NULL */ @@ -164,7 +164,7 @@ extern "C" * @param s The stream to write to * @param msg The message to encode * - * @version 3.0.0 + * @since version 3.0.0 * @return \b TRUE in case of success, \b FALSE for any error */ FREERDP_API BOOL rfx_write_message_progressive_simple(RFX_CONTEXT* rfx, wStream* s, diff --git a/include/freerdp/crypto/certificate_store.h b/include/freerdp/crypto/certificate_store.h index 4779c37fa..fc84da105 100644 --- a/include/freerdp/crypto/certificate_store.h +++ b/include/freerdp/crypto/certificate_store.h @@ -68,7 +68,7 @@ extern "C" * @param host The hostname to look up * @param port The port to look up * - * @version 3.0.0 + * @since version 3.0.0 * * @return The certificate store file path or \b NULL */ diff --git a/include/freerdp/crypto/crypto.h b/include/freerdp/crypto/crypto.h index 31029355c..ef6020340 100644 --- a/include/freerdp/crypto/crypto.h +++ b/include/freerdp/crypto/crypto.h @@ -46,7 +46,7 @@ extern "C" * @param length The lenght of the data in bytes * @param withCrLf Option to split the encoded data with CRLF linebreaks * - * @version 3.0.0 + * @since version 3.0.0 * * @return The encoded BASE64 string or \b NULL if failed */ diff --git a/include/freerdp/utils/aad.h b/include/freerdp/utils/aad.h index 2f552dec3..1c69a3fc9 100644 --- a/include/freerdp/utils/aad.h +++ b/include/freerdp/utils/aad.h @@ -22,7 +22,7 @@ #define FREERDP_UTILS_AAD_H /** \file AAD related helper utilities - * \version 3.0.0 + * \since version 3.0.0 */ #include @@ -36,7 +36,7 @@ * @param data The JSON to parse * @param length The number of bytes of the JSON data * - * @version 3.0.0 + * @since version 3.0.0 * * @return The token string or \b NULL */ diff --git a/include/freerdp/utils/encoded_types.h b/include/freerdp/utils/encoded_types.h index b9ff14b39..d2b35de6c 100644 --- a/include/freerdp/utils/encoded_types.h +++ b/include/freerdp/utils/encoded_types.h @@ -22,7 +22,7 @@ #define FREERDP_UTILS_ENCODED_TYPES_H /** \file Encoded Types helpers - * \version 3.0.0 + * \since version 3.0.0 */ #include @@ -34,22 +34,22 @@ extern "C" #endif /** Maximum value of a 4 byte signed integer - * \version 3.x.0 + * \since version 3.5.0 */ #define FREERDP_FOUR_BYTE_SIGNED_INT_MAX 0x1FFFFFFFl /** Minimum value of a 4 byte signed integer - * \version 3.x.0 + * \since version 3.5.0 */ #define FREERDP_FOUR_BYTE_SIGNED_INT_MIN -0x1FFFFFFFl /** Maximum value of a 4 byte float - * \version 3.x.0 + * \since version 3.5.0 */ #define FREERDP_FOUR_BYTE_FLOAT_MAX 0x3FFFFFF /** Minimum value of a 4 byte float - * \version 3.x.0 + * \since version 3.5.0 */ #define FREERDP_FOUR_BYTE_FLOAT_MIN -0x3FFFFFF @@ -58,11 +58,21 @@ extern "C" * @param s The steam to read from * @param value A pointer to an INT32 to hold the result * - * @version 3.0.0 + * @since version 3.0.0 * - * @return \bTRUE for successful reading, \b FALSE otherwise + * @return \b TRUE for successful reading, \b FALSE otherwise */ FREERDP_API BOOL freerdp_read_four_byte_signed_integer(wStream* s, INT32* value); + + /** Write a 4 byte signed integer to a stream + * + * @param s The steam to read from + * @param value The INT32 value to encode and write + * + * @since version 3.4.0 + * + * @return \b TRUE for successful writing, \b FALSE otherwise + */ FREERDP_API BOOL freerdp_write_four_byte_signed_integer(wStream* s, INT32 value); /** Read a 4 byte float from a stream and store the decoded value @@ -70,12 +80,33 @@ extern "C" * @param s The steam to read from * @param value A pointer to a double to hold the result * - * @version 3.0.0 + * @since version 3.0.0 * - * @return \bTRUE for successful reading, \b FALSE otherwise + * @return \b TRUE for successful reading, \b FALSE otherwise */ FREERDP_API BOOL freerdp_read_four_byte_float(wStream* s, double* value); + + /** Read a 4 byte float from a stream and store the decoded value and exponent + * + * @param s The steam to read from + * @param value A pointer to a double to hold the result + * @param exp A pointer to a BYTE to hold the exponent result + * + * @since version 3.5.0 + * + * @return \b TRUE for successful reading, \b FALSE otherwise + */ FREERDP_API BOOL freerdp_read_four_byte_float_exp(wStream* s, double* value, BYTE* exp); + + /** Write a 4 byte float to a stream + * + * @param s The steam to read from + * @param value The float value to encode and write + * + * @since version 3.4.0 + * + * @return \b TRUE for successful writing, \b FALSE otherwise + */ FREERDP_API BOOL freerdp_write_four_byte_float(wStream* s, double value); #ifdef __cplusplus