diff --git a/include/config/config.h.in b/include/config/config.h.in index 460389b92..1310ec8f4 100644 --- a/include/config/config.h.in +++ b/include/config/config.h.in @@ -11,6 +11,11 @@ #cmakedefine AVRESAMPLE_FOUND /* Options */ +/** If set the rdpSettings struct is opaque and internals can only be accessed + * through getters/setters + * + * \version 3.0.0 + */ #cmakedefine WITH_OPAQUE_SETTINGS #cmakedefine WITH_ADD_PLUGIN_TO_RPATH @@ -35,6 +40,10 @@ #cmakedefine WITH_OPENSLES #cmakedefine WITH_GSM #cmakedefine WITH_LAME +/** If defined Opus codec support is available. + * + * \version 3.0.0 + */ #cmakedefine WITH_OPUS #cmakedefine WITH_FAAD2 #cmakedefine WITH_FAAC @@ -92,8 +101,20 @@ #cmakedefine CHANNEL_GFXREDIR #cmakedefine CHANNEL_GFXREDIR_CLIENT #cmakedefine CHANNEL_GFXREDIR_SERVER +/** If defined location channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_LOCATION +/** If defined location client side channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_LOCATION_CLIENT +/** If defined location server side channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_LOCATION_SERVER #cmakedefine CHANNEL_PARALLEL #cmakedefine CHANNEL_PARALLEL_CLIENT @@ -119,8 +140,22 @@ #cmakedefine CHANNEL_RDPGFX #cmakedefine CHANNEL_RDPGFX_CLIENT #cmakedefine CHANNEL_RDPGFX_SERVER +/** If defined mouse cursor channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_RDPEMSC + +/** If defined mouse cursor channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_RDPEMSC_CLIENT + +/** If defined mouse cursor channel support is available. + * + * \version 3.0.0 + */ #cmakedefine CHANNEL_RDPEMSC_SERVER #cmakedefine CHANNEL_RDPSND #cmakedefine CHANNEL_RDPSND_CLIENT @@ -186,6 +221,10 @@ #cmakedefine WITH_PROXY_MODULES #cmakedefine WITH_PROXY_EMULATE_SMARTCARD +/** If defined linux/vm_sockets.h support is available. + * + * \version 3.0.0 + */ #cmakedefine HAVE_AF_VSOCK_H #endif /* FREERDP_CONFIG_H */ diff --git a/include/config/settings_keys.h.in b/include/config/settings_keys.h.in index 7f02c6c41..50525ca29 100644 --- a/include/config/settings_keys.h.in +++ b/include/config/settings_keys.h.in @@ -28,52 +28,92 @@ extern "C" { #endif +/** A list of available settings keys of type BOOL + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_BOOL@ } FreeRDP_Settings_Keys_Bool; +/** A list of available settings keys of type INT16 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_INT16@ } FreeRDP_Settings_Keys_Int16; +/** A list of available settings keys of type UINT16 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_UINT16@ } FreeRDP_Settings_Keys_UInt16; +/** A list of available settings keys of type INT32 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_INT32@ } FreeRDP_Settings_Keys_Int32; +/** A list of available settings keys of type UINT32 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_UINT32@ } FreeRDP_Settings_Keys_UInt32; +/** A list of available settings keys of type INT64 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_INT64@ } FreeRDP_Settings_Keys_Int64; +/** A list of available settings keys of type UINT64 + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_UINT64@ } FreeRDP_Settings_Keys_UInt64; +/** A list of available settings keys of type STRING + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_STRING@ } FreeRDP_Settings_Keys_String; +/** A list of available settings keys of type POINTER + * + * \version 3.0.0 + */ typedef enum { @SETTINGS_KEYS_POINTER@ } FreeRDP_Settings_Keys_Pointer; +/** Highest indes in the rdpSettings stable API + * + * \version 3.0.0 + */ #define FreeRDP_Settings_StableAPI_MAX 5312 #ifdef __cplusplus diff --git a/include/freerdp/channels/audin.h b/include/freerdp/channels/audin.h index 17254e650..e00e9e19a 100644 --- a/include/freerdp/channels/audin.h +++ b/include/freerdp/channels/audin.h @@ -26,7 +26,16 @@ #include #include +/** The command line name of the channel + * + * \version 3.0.0 + */ #define AUDIN_CHANNEL_NAME "audin" + +/** The name of the channel (protocol internal) + * + * \version 3.0.0 + */ #define AUDIN_DVC_CHANNEL_NAME "AUDIO_INPUT" typedef struct diff --git a/include/freerdp/channels/cliprdr.h b/include/freerdp/channels/cliprdr.h index 297a9774d..4f766e52d 100644 --- a/include/freerdp/channels/cliprdr.h +++ b/include/freerdp/channels/cliprdr.h @@ -26,6 +26,10 @@ #include +/** The command line name of the channel + * + * \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 5afc3b2aa..41d4906c8 100644 --- a/include/freerdp/channels/drdynvc.h +++ b/include/freerdp/channels/drdynvc.h @@ -25,6 +25,10 @@ #include #include +/** The command line name of the channel + * + * \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 263de658a..18cbc8620 100644 --- a/include/freerdp/channels/echo.h +++ b/include/freerdp/channels/echo.h @@ -25,6 +25,10 @@ #include #include +/** The command line name of the channel + * + * \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 7fde7738e..bde6c3191 100644 --- a/include/freerdp/channels/encomsp.h +++ b/include/freerdp/channels/encomsp.h @@ -28,6 +28,10 @@ extern "C" { #endif +/** The command line name of the channel + * + * \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 1b00f0ffa..d9ffb1cc5 100644 --- a/include/freerdp/channels/geometry.h +++ b/include/freerdp/channels/geometry.h @@ -23,6 +23,10 @@ #include #include +/** The command line name of the channel + * + * \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 45682b074..6f0007834 100644 --- a/include/freerdp/channels/location.h +++ b/include/freerdp/channels/location.h @@ -24,7 +24,12 @@ #include #include +/** The command line name of the channel + * + * \version 3.0.0 + */ #define LOCATION_CHANNEL_NAME "location" + #define LOCATION_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Location" #ifdef __cplusplus diff --git a/include/freerdp/channels/rdpdr.h b/include/freerdp/channels/rdpdr.h index 6315ab7b9..1e2691c0f 100644 --- a/include/freerdp/channels/rdpdr.h +++ b/include/freerdp/channels/rdpdr.h @@ -42,6 +42,10 @@ extern "C" { #endif +/** The command line name of the channel + * + * \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 2e41efcd4..615d8eebe 100644 --- a/include/freerdp/channels/rdpecam.h +++ b/include/freerdp/channels/rdpecam.h @@ -24,6 +24,10 @@ #include #include +/** The command line name of the channel + * + * \version 3.0.0 + */ #define RDPECAM_CHANNEL_NAME "rdpecam" #define RDPECAM_DVC_CHANNEL_NAME "rdpecam" #define RDPECAM_CONTROL_DVC_CHANNEL_NAME "RDCamera_Device_Enumerator" diff --git a/include/freerdp/channels/rdpei.h b/include/freerdp/channels/rdpei.h index 1c4fca5de..388a7f183 100644 --- a/include/freerdp/channels/rdpei.h +++ b/include/freerdp/channels/rdpei.h @@ -31,6 +31,10 @@ extern "C" #define RDPINPUT_HEADER_LENGTH 6 +/** The command line name of the channel + * + * \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 462035848..9c0614d19 100644 --- a/include/freerdp/channels/rdpemsc.h +++ b/include/freerdp/channels/rdpemsc.h @@ -20,10 +20,19 @@ #ifndef FREERDP_CHANNEL_RDPEMSC_H #define FREERDP_CHANNEL_RDPEMSC_H +/** \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 + */ #include #include #include +/** The command line name of the channel + * + * \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 a056f9d2c..37895c64c 100644 --- a/include/freerdp/channels/rdpewa.h +++ b/include/freerdp/channels/rdpewa.h @@ -25,6 +25,10 @@ #include #include +/** The command line name of the channel + * + * \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 b608e0fef..a7f8555e5 100644 --- a/include/freerdp/channels/rdpgfx.h +++ b/include/freerdp/channels/rdpgfx.h @@ -24,6 +24,10 @@ #include #include +/** The command line name of the channel + * + * \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 281317a7d..05eeedc30 100644 --- a/include/freerdp/channels/remdesk.h +++ b/include/freerdp/channels/remdesk.h @@ -28,6 +28,10 @@ extern "C" { #endif +/** The command line name of the channel + * + * \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 cf96d6ddf..5a809f7b6 100644 --- a/include/freerdp/channels/telemetry.h +++ b/include/freerdp/channels/telemetry.h @@ -24,6 +24,10 @@ #include #include +/** The command line name of the channel + * + * \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 aa943c9a0..6a9a8d3a8 100644 --- a/include/freerdp/channels/tsmf.h +++ b/include/freerdp/channels/tsmf.h @@ -30,6 +30,10 @@ #include +/** The command line name of the channel + * + * \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 f3d918da6..5efdfbd1d 100644 --- a/include/freerdp/channels/urbdrc.h +++ b/include/freerdp/channels/urbdrc.h @@ -25,6 +25,10 @@ #include #include +/** The command line name of the channel + * + * \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 b552475ba..01d1a3356 100644 --- a/include/freerdp/channels/video.h +++ b/include/freerdp/channels/video.h @@ -23,6 +23,10 @@ #include #include +/** The command line name of the channel + * + * \version 3.0.0 + */ #define VIDEO_CHANNEL_NAME "video" #define VIDEO_CONTROL_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Video::Control::v08.01" #define VIDEO_DATA_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Video::Data::v08.01" diff --git a/include/freerdp/client/cmdline.h b/include/freerdp/client/cmdline.h index 36c849912..2b05e530b 100644 --- a/include/freerdp/client/cmdline.h +++ b/include/freerdp/client/cmdline.h @@ -56,6 +56,8 @@ 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 + * * \return \b 0 in case of success, a negative number in case of failure. */ FREERDP_API int freerdp_client_settings_parse_command_line_arguments_ex( @@ -73,8 +75,22 @@ extern "C" const COMMAND_LINE_ARGUMENT_A* custom); FREERDP_API BOOL freerdp_client_load_addins(rdpChannels* channels, rdpSettings* settings); + /** Print a command line warning about the component being unmaintained. + * + * \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 + */ 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 + */ FREERDP_API void freerdp_client_warn_deprecated(int argc, char* argv[]); FREERDP_API BOOL freerdp_client_print_version(void); diff --git a/include/freerdp/codec/audio.h b/include/freerdp/codec/audio.h index 1d4b36f64..d47cdc3e5 100644 --- a/include/freerdp/codec/audio.h +++ b/include/freerdp/codec/audio.h @@ -190,6 +190,10 @@ extern "C" #define WAVE_FORMAT_SOUNDSPACE_MUSICOMPRESS 0x1500 #define WAVE_FORMAT_DVM 0x2000 #endif /* !WAVE_FORMAT_LUCENT_G723 */ + + /** Opus format identifier + * \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 c24f53ab2..1066d76ef 100644 --- a/include/freerdp/codec/progressive.h +++ b/include/freerdp/codec/progressive.h @@ -70,6 +70,15 @@ extern "C" FREERDP_API PROGRESSIVE_CONTEXT* progressive_context_new_ex(BOOL Compressor, UINT32 ThreadingFlags); + /** Write a RFX message as simple progressive message to a stream. + * Forward wrapper for \link rfx_write_message_progressive_simple + * @param progressive The progressive codec context + * @param s The stream to write to + * @param msg The message to encode + * + * @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( PROGRESSIVE_CONTEXT* progressive, wStream* s, const RFX_MESSAGE* msg); diff --git a/include/freerdp/codec/rfx.h b/include/freerdp/codec/rfx.h index 2b122be67..6b20cf1b6 100644 --- a/include/freerdp/codec/rfx.h +++ b/include/freerdp/codec/rfx.h @@ -124,16 +124,49 @@ extern "C" FREERDP_API BOOL rfx_context_reset(RFX_CONTEXT* context, UINT32 width, UINT32 height); FREERDP_API BOOL rfx_context_set_mode(RFX_CONTEXT* context, RLGR_MODE mode); + + /** Getter for RFX mode + * @param context The RFX context to query + * + * @version 3.0.0 + * + * @return The RFX mode that is currently in use + */ FREERDP_API RLGR_MODE rfx_context_get_mode(RFX_CONTEXT* context); FREERDP_API void rfx_context_set_pixel_format(RFX_CONTEXT* context, UINT32 pixel_format); + + /** Getter for RFX pixel format + * @param context The RFX context to query + * + * @version 3.0.0 + * + * @return The RFX pixel format that is currently in use + */ FREERDP_API UINT32 rfx_context_get_pixel_format(RFX_CONTEXT* context); FREERDP_API void rfx_context_set_palette(RFX_CONTEXT* context, const BYTE* palette); + + /** Getter for RFX palette + * @param context The RFX context to query + * + * @version 3.0.0 + * + * @return The RFX palette that is currently in use or \b NULL + */ FREERDP_API const BYTE* rfx_context_get_palette(RFX_CONTEXT* context); FREERDP_API UINT32 rfx_context_get_frame_idx(const RFX_CONTEXT* context); + /** Write a RFX message as simple progressive message to a stream. + * + * @param rfx The RFX codec context + * @param s The stream to write to + * @param msg The message to encode + * + * @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, const RFX_MESSAGE* msg); diff --git a/include/freerdp/crypto/certificate_store.h b/include/freerdp/crypto/certificate_store.h index e7e43e17a..4779c37fa 100644 --- a/include/freerdp/crypto/certificate_store.h +++ b/include/freerdp/crypto/certificate_store.h @@ -62,6 +62,16 @@ extern "C" FREERDP_API const char* freerdp_certificate_store_get_hosts_path(const rdpCertificateStore* store); + /** Query the certificate store path + * + * @param store The certificate store to query + * @param host The hostname to look up + * @param port The port to look up + * + * @version 3.0.0 + * + * @return The certificate store file path or \b NULL + */ FREERDP_API char* freerdp_certificate_store_get_cert_path(const rdpCertificateStore* store, const char* host, UINT16 port); diff --git a/include/freerdp/crypto/crypto.h b/include/freerdp/crypto/crypto.h index e3b7b0dc6..31029355c 100644 --- a/include/freerdp/crypto/crypto.h +++ b/include/freerdp/crypto/crypto.h @@ -39,6 +39,17 @@ extern "C" typedef struct rdp_CertInfo rdpCertInfo; FREERDP_API char* crypto_base64_encode(const BYTE* WINPR_RESTRICT data, size_t length); + + /** BASE64 encode data + * + * @param data The data to encode + * @param length The lenght of the data in bytes + * @param withCrLf Option to split the encoded data with CRLF linebreaks + * + * @version 3.0.0 + * + * @return The encoded BASE64 string or \b NULL if failed + */ FREERDP_API char* crypto_base64_encode_ex(const BYTE* WINPR_RESTRICT data, size_t length, BOOL withCrLf); diff --git a/include/freerdp/utils/aad.h b/include/freerdp/utils/aad.h index c59e83cb5..2f552dec3 100644 --- a/include/freerdp/utils/aad.h +++ b/include/freerdp/utils/aad.h @@ -21,6 +21,9 @@ #ifndef FREERDP_UTILS_AAD_H #define FREERDP_UTILS_AAD_H +/** \file AAD related helper utilities + * \version 3.0.0 + */ #include #include @@ -28,6 +31,15 @@ #ifdef WITH_AAD +/** Helper to retrieve the AAD access token from JSON input + * + * @param data The JSON to parse + * @param length The number of bytes of the JSON data + * + * @version 3.0.0 + * + * @return The token string or \b NULL + */ FREERDP_API char* freerdp_utils_aad_get_access_token(wLog* log, const char* data, size_t length); #endif diff --git a/include/freerdp/utils/encoded_types.h b/include/freerdp/utils/encoded_types.h index c1f45e612..b9ff14b39 100644 --- a/include/freerdp/utils/encoded_types.h +++ b/include/freerdp/utils/encoded_types.h @@ -21,6 +21,10 @@ #ifndef FREERDP_UTILS_ENCODED_TYPES_H #define FREERDP_UTILS_ENCODED_TYPES_H +/** \file Encoded Types helpers + * \version 3.0.0 + */ + #include #include @@ -29,15 +33,47 @@ extern "C" { #endif +/** Maximum value of a 4 byte signed integer + * \version 3.x.0 + */ #define FREERDP_FOUR_BYTE_SIGNED_INT_MAX 0x1FFFFFFFl + +/** Minimum value of a 4 byte signed integer + * \version 3.x.0 + */ #define FREERDP_FOUR_BYTE_SIGNED_INT_MIN -0x1FFFFFFFl +/** Maximum value of a 4 byte float + * \version 3.x.0 + */ #define FREERDP_FOUR_BYTE_FLOAT_MAX 0x3FFFFFF + +/** Minimum value of a 4 byte float + * \version 3.x.0 + */ #define FREERDP_FOUR_BYTE_FLOAT_MIN -0x3FFFFFF + /** Read a 4 byte signed integer from a stream and store the decoded value + * + * @param s The steam to read from + * @param value A pointer to an INT32 to hold the result + * + * @version 3.0.0 + * + * @return \bTRUE for successful reading, \b FALSE otherwise + */ FREERDP_API BOOL freerdp_read_four_byte_signed_integer(wStream* s, INT32* value); 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 + * + * @param s The steam to read from + * @param value A pointer to a double to hold the result + * + * @version 3.0.0 + * + * @return \bTRUE for successful reading, \b FALSE otherwise + */ FREERDP_API BOOL freerdp_read_four_byte_float(wStream* s, double* value); FREERDP_API BOOL freerdp_read_four_byte_float_exp(wStream* s, double* value, BYTE* exp); FREERDP_API BOOL freerdp_write_four_byte_float(wStream* s, double value);