From fb5934007ada0482e5ad4a4c0c81b0c6a7e939ec Mon Sep 17 00:00:00 2001 From: akallabeth Date: Thu, 12 Sep 2024 14:45:02 +0200 Subject: [PATCH] [doxygen] add basic documentation for new API * Add basic documentation for new functions/structs/data types since 3.0.0 --- include/config/build-config.h.in | 6 +- include/freerdp/channels/location.h | 8 +- include/freerdp/channels/rdpemsc.h | 9 +- include/freerdp/client.h | 13 + include/freerdp/client/location.h | 10 + include/freerdp/codec/color.h | 39 ++- include/freerdp/codec/h264.h | 28 +- include/freerdp/codecs.h | 16 +- include/freerdp/crypto/certificate.h | 17 ++ include/freerdp/locale/keyboard.h | 2 +- include/freerdp/locale/locale.h | 32 ++- include/freerdp/primitives.h | 35 ++- include/freerdp/rail.h | 9 + include/freerdp/server/proxy/proxy_config.h | 16 +- include/freerdp/server/shadow.h | 35 ++- include/freerdp/settings.h | 54 ++-- include/freerdp/settings_types.h | 43 +-- include/freerdp/settings_types_private.h | 45 ++- include/freerdp/transport_io.h | 66 ++++- include/freerdp/utils/gfx.h | 6 + libfreerdp/utils/passphrase.c | 12 +- winpr/include/config/config.h.in | 10 +- winpr/include/winpr/collections.h | 17 ++ winpr/include/winpr/image.h | 76 ++++- winpr/include/winpr/json.h | 303 +++++++++++++++++++- winpr/include/winpr/library.h | 8 + winpr/include/winpr/ncrypt.h | 1 + winpr/include/winpr/platform.h | 34 +-- winpr/include/winpr/secapi.h | 2 +- winpr/include/winpr/stream.h | 168 +++++++++++ winpr/include/winpr/sysinfo.h | 47 +-- winpr/include/winpr/thread.h | 31 +- winpr/include/winpr/timezone.h | 5 + winpr/include/winpr/winpr.h | 27 +- winpr/libwinpr/utils/image.c | 1 + 35 files changed, 1056 insertions(+), 175 deletions(-) diff --git a/include/config/build-config.h.in b/include/config/build-config.h.in index 9f16f02c5..5df41112d 100644 --- a/include/config/build-config.h.in +++ b/include/config/build-config.h.in @@ -14,9 +14,9 @@ #define FREERDP_SHARED_LIBRARY_SUFFIX "${CMAKE_SHARED_LIBRARY_SUFFIX}" #define FREERDP_SHARED_LIBRARY_PREFIX "${CMAKE_SHARED_LIBRARY_PREFIX}" -#define FREERDP_VENDOR_STRING "${VENDOR}" -#define FREERDP_PRODUCT_STRING "${PRODUCT}" +#define FREERDP_VENDOR_STRING "${VENDOR}" /** @since version 3.3.0 */ +#define FREERDP_PRODUCT_STRING "${PRODUCT}" /** @since version 3.3.0 */ -#define FREERDP_PROXY_PLUGINDIR "${NATIVE_FREERDP_PROXY_PLUGINDIR}" +#define FREERDP_PROXY_PLUGINDIR "${NATIVE_FREERDP_PROXY_PLUGINDIR}" /** @since version 3.3.0 */ #endif /* FREERDP_BUILD_CONFIG_H */ diff --git a/include/freerdp/channels/location.h b/include/freerdp/channels/location.h index f724fbbdc..622bd6b1b 100644 --- a/include/freerdp/channels/location.h +++ b/include/freerdp/channels/location.h @@ -24,11 +24,15 @@ #include #include +/** @defgroup channel_location + * @{ + */ + /** The command line name of the channel * * \since version 3.0.0 */ -#define LOCATION_CHANNEL_NAME "location" +#define LOCATION_CHANNEL_NAME "location" /** @since version 3.4.0 */ #define LOCATION_DVC_CHANNEL_NAME "Microsoft::Windows::RDS::Location" @@ -117,4 +121,6 @@ extern "C" #ifdef __cplusplus } #endif +/** @} */ + #endif /* FREERDP_CHANNEL_LOCATION_H */ diff --git a/include/freerdp/channels/rdpemsc.h b/include/freerdp/channels/rdpemsc.h index 2bdfb5812..8acd31f65 100644 --- a/include/freerdp/channels/rdpemsc.h +++ b/include/freerdp/channels/rdpemsc.h @@ -20,6 +20,10 @@ #ifndef FREERDP_CHANNEL_RDPEMSC_H #define FREERDP_CHANNEL_RDPEMSC_H +/** @defgroup channel_rdpemsc + * @{ + */ + /** \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 @@ -70,7 +74,7 @@ extern "C" typedef enum { - RDP_MOUSE_CURSOR_CAPVERSION_INVALID = 0x00000000, + RDP_MOUSE_CURSOR_CAPVERSION_INVALID = 0x00000000, /** @since version 3.3.0 */ RDP_MOUSE_CURSOR_CAPVERSION_1 = 0x00000001, } RDP_MOUSE_CURSOR_CAPVERSION; @@ -144,4 +148,7 @@ extern "C" #ifdef __cplusplus } #endif + +/** @} */ + #endif /* FREERDP_CHANNEL_RDPEMSC_H */ diff --git a/include/freerdp/client.h b/include/freerdp/client.h index a1ea628b8..08e4c2125 100644 --- a/include/freerdp/client.h +++ b/include/freerdp/client.h @@ -154,6 +154,19 @@ extern "C" FREERDP_API int freerdp_client_settings_parse_command_line(rdpSettings* settings, int argc, char** argv, BOOL allowUnknown); + /** + * @brief freerdp_client_settings_parse_command_line_ex + * @param settings Pointer to the settings to populate + * @param argc Number of command line arguments + * @param argv Array of command line arguments + * @param allowUnknown Skip unknown arguments instead of aborting parser + * @param args The allowed command line arguments (client specific, client-common ones are added + * internally) + * @param count Number of client specific command line arguments + * @param handle_userdata Custom user data pointer, will be passed to callback + * @return >=0 for success, <0 in case of parsing failures + * @since version 3.9.0 + */ FREERDP_API int freerdp_client_settings_parse_command_line_ex( rdpSettings* settings, int argc, char** argv, BOOL allowUnknown, COMMAND_LINE_ARGUMENT_A* args, size_t count, diff --git a/include/freerdp/client/location.h b/include/freerdp/client/location.h index 67db65531..0135029d7 100644 --- a/include/freerdp/client/location.h +++ b/include/freerdp/client/location.h @@ -23,18 +23,28 @@ #include +/** @file + * @since version 3.4.0 + */ #ifdef __cplusplus extern "C" { #endif + /** @since version 3.4.0 */ typedef struct s_location_client_context LocationClientContext; + /** @since version 3.4.0 */ typedef UINT (*pcLocationStart)(LocationClientContext* context, UINT32 version, UINT32 flags); + + /** @since version 3.4.0 */ typedef UINT (*pcLocationStop)(LocationClientContext* context); + + /** @since version 3.4.0 */ typedef UINT (*pcLocationSend)(LocationClientContext* context, LOCATION_PDUTYPE type, size_t count, ...); + /** @since version 3.4.0 */ struct s_location_client_context { void* handle; diff --git a/include/freerdp/codec/color.h b/include/freerdp/codec/color.h index fd9532cad..35ed3ebc6 100644 --- a/include/freerdp/codec/color.h +++ b/include/freerdp/codec/color.h @@ -38,13 +38,14 @@ extern "C" #define FREERDP_PIXEL_FORMAT_IS_ABGR(_format) \ (FREERDP_PIXEL_FORMAT_TYPE(_format) == FREERDP_PIXEL_FORMAT_TYPE_ABGR) -enum FREERDP_IMAGE_FLAGS -{ - FREERDP_FLIP_NONE = 0, - FREERDP_FLIP_VERTICAL = 1, - FREERDP_FLIP_HORIZONTAL = 2, - FREERDP_KEEP_DST_ALPHA = 4 -}; + /** @brief Flags for image copy operations */ + enum FREERDP_IMAGE_FLAGS + { + FREERDP_FLIP_NONE = 0, + FREERDP_FLIP_VERTICAL = 1, + FREERDP_FLIP_HORIZONTAL = 2, + FREERDP_KEEP_DST_ALPHA = 4 + }; #define FREERDP_PIXEL_FORMAT(_bpp, _type, _a, _r, _g, _b) \ ((_bpp << 24) | (_type << 16) | (_a << 12) | (_r << 8) | (_g << 4) | (_b)) @@ -65,6 +66,9 @@ enum FREERDP_IMAGE_FLAGS * X for alpha channel denotes unused (but existing) alpha channel data. */ +/** @defgroup PIXEL_FORMAT + * @{ + */ /* 32bpp formats */ #define PIXEL_FORMAT_ARGB32 FREERDP_PIXEL_FORMAT(32, FREERDP_PIXEL_FORMAT_TYPE_ARGB, 8, 8, 8, 8) #define PIXEL_FORMAT_XRGB32 FREERDP_PIXEL_FORMAT(32, FREERDP_PIXEL_FORMAT_TYPE_ARGB, 0, 8, 8, 8) @@ -100,11 +104,13 @@ enum FREERDP_IMAGE_FLAGS /* 1bpp formats */ #define PIXEL_FORMAT_MONO FREERDP_PIXEL_FORMAT(1, FREERDP_PIXEL_FORMAT_TYPE_A, 1, 0, 0, 0) -struct gdi_palette -{ - UINT32 format; - UINT32 palette[256]; -}; + /** @} */ + + struct gdi_palette + { + UINT32 format; + UINT32 palette[256]; + }; typedef struct gdi_palette gdiPalette; /* Compare two color formats but ignore differences in alpha channel. @@ -379,21 +385,24 @@ typedef struct gdi_palette gdiPalette; UINT32 nXSrc, UINT32 nYSrc, const gdiPalette* WINPR_RESTRICT palette, UINT32 flags); - /*** Same as freerdp_image_copy() but only for overlapping source and destination + /*** Same as @freerdp_image_copy but only for overlapping source and destination + * @since version 3.6.0 */ FREERDP_API BOOL freerdp_image_copy_overlap( BYTE* pDstData, DWORD DstFormat, UINT32 nDstStep, UINT32 nXDst, UINT32 nYDst, UINT32 nWidth, UINT32 nHeight, const BYTE* pSrcData, DWORD SrcFormat, UINT32 nSrcStep, UINT32 nXSrc, UINT32 nYSrc, const gdiPalette* WINPR_RESTRICT palette, UINT32 flags); - /*** Same as freerdp_image_copy() but only for non overlapping source and destination + /*** Same as @freerdp_image_copy but only for non overlapping source and destination + * @since version 3.6.0 */ FREERDP_API BOOL freerdp_image_copy_no_overlap( BYTE* WINPR_RESTRICT pDstData, DWORD DstFormat, UINT32 nDstStep, UINT32 nXDst, UINT32 nYDst, UINT32 nWidth, UINT32 nHeight, const BYTE* WINPR_RESTRICT pSrcData, DWORD SrcFormat, UINT32 nSrcStep, UINT32 nXSrc, UINT32 nYSrc, const gdiPalette* WINPR_RESTRICT palette, UINT32 flags); - /*** + + /*** Scale an image to destination * * @param pDstData destination buffer * @param DstFormat destination buffer format diff --git a/include/freerdp/codec/h264.h b/include/freerdp/codec/h264.h index 7f56c2fa0..add267849 100644 --- a/include/freerdp/codec/h264.h +++ b/include/freerdp/codec/h264.h @@ -41,6 +41,10 @@ extern "C" H264_RATECONTROL_CQP } H264_RATECONTROL_MODE; + /** + * @brief The usage types for H264 encoding + * @since version 3.6.0 + */ typedef enum { H264_SCREEN_CONTENT_REAL_TIME = 0, @@ -56,7 +60,7 @@ extern "C" H264_CONTEXT_OPTION_BITRATE, H264_CONTEXT_OPTION_FRAMERATE, H264_CONTEXT_OPTION_QP, - H264_CONTEXT_OPTION_USAGETYPE, + H264_CONTEXT_OPTION_USAGETYPE, /** @since version 3.6.0 */ } H264_CONTEXT_OPTION; FREERDP_API void free_h264_metablock(RDPGFX_H264_METABLOCK* meta); @@ -70,9 +74,29 @@ extern "C" const RECTANGLE_16* regionRect, BYTE** ppDstData, UINT32* pDstSize, RDPGFX_H264_METABLOCK* meta); - /* API for user to fill YUV I420 buffer before encoding */ + /** @brief API for user to fill YUV I420 buffer before encoding + * + * @param h264 The h264 context to query + * @param nSrcStride The size of a line in bytes of the source image + * @param nSrcWidth The width of the source image in pixels + * @param nSrcHeight The height of the source image + * @param YUVData A pointer to hold the current YUV buffers + * @param stride A pointer to hold the byte length of a line in the YUV buffers + * @return \b >= 0 for success, \b <0 for an error + * @since version 3.6.0 + */ FREERDP_API INT32 h264_get_yuv_buffer(H264_CONTEXT* h264, UINT32 nSrcStride, UINT32 nSrcWidth, UINT32 nSrcHeight, BYTE* YUVData[3], UINT32 stride[3]); + + /** + * @brief Compress currently filled image data to H264 stream + * + * @param h264 The H264 context to use for compression + * @param ppDstData A pointer that will hold the allocated result buffer + * @param pDstSize A pointer for the destination buffer size in bytes + * @return \b >= 0 for success, \b <0 for an error + * @since version 3.6.0 + */ FREERDP_API INT32 h264_compress(H264_CONTEXT* h264, BYTE** ppDstData, UINT32* pDstSize); FREERDP_API INT32 avc420_decompress(H264_CONTEXT* h264, const BYTE* pSrcData, UINT32 SrcSize, diff --git a/include/freerdp/codecs.h b/include/freerdp/codecs.h index 99c5c0f77..95e20d84d 100644 --- a/include/freerdp/codecs.h +++ b/include/freerdp/codecs.h @@ -54,7 +54,7 @@ extern "C" struct rdp_codecs { - UINT32 ThreadingFlags; + UINT32 ThreadingFlags; /** @since version 3.6.0 */ RFX_CONTEXT* rfx; NSC_CONTEXT* nsc; @@ -71,15 +71,25 @@ extern "C" FREERDP_API BOOL freerdp_client_codecs_reset(rdpCodecs* codecs, UINT32 flags, UINT32 width, UINT32 height); + /** + * @brief Free a rdpCodecs instance + * @param codecs A pointer to a rdpCodecs instance or NULL + * @since version 3.6.0 + */ FREERDP_API void freerdp_client_codecs_free(rdpCodecs* codecs); + /** + * @brief Allocate a rdpCodecs instance. + * @return A newly allocated instance or \b NULL in case of failure. + * @since version 3.6.0 + */ WINPR_ATTR_MALLOC(freerdp_client_codecs_free, 1) FREERDP_API rdpCodecs* freerdp_client_codecs_new(UINT32 TheadingFlags); - FREERDP_API WINPR_DEPRECATED_VAR("Use freerdp_client_codecs_free", + FREERDP_API WINPR_DEPRECATED_VAR("[since 3.6.0] Use freerdp_client_codecs_free", void codecs_free(rdpCodecs* codecs)); - FREERDP_API WINPR_DEPRECATED_VAR("Use freerdp_client_codecs_new", + FREERDP_API WINPR_DEPRECATED_VAR("[since 3.6.0] Use freerdp_client_codecs_new", rdpCodecs* codecs_new(rdpContext* context)); #ifdef __cplusplus diff --git a/include/freerdp/crypto/certificate.h b/include/freerdp/crypto/certificate.h index 2e6da8eb7..7a8f43403 100644 --- a/include/freerdp/crypto/certificate.h +++ b/include/freerdp/crypto/certificate.h @@ -65,6 +65,16 @@ extern "C" FREERDP_API char* freerdp_certificate_get_fingerprint(const rdpCertificate* certificate); FREERDP_API char* freerdp_certificate_get_pem(const rdpCertificate* certificate, size_t* pLength); + + /** + * @brief Get the certificate as PEM string + * @param certificate A certificate instance to query + * @param pLength A pointer to the size in bytes of the PEM string + * @param withCertChain \b TRUE to export a full chain PEM, \b FALSE for only the last + * certificate in the chain + * @return A newly allocated string containing the requested PEM (free to deallocate) or NULL + * @since version 3.8.0 + */ FREERDP_API char* freerdp_certificate_get_pem_ex(const rdpCertificate* certificate, size_t* pLength, BOOL withCertChain); FREERDP_API BYTE* freerdp_certificate_get_der(const rdpCertificate* certificate, @@ -76,6 +86,13 @@ extern "C" FREERDP_API char* freerdp_certificate_get_upn(const rdpCertificate* certificate); FREERDP_API char* freerdp_certificate_get_email(const rdpCertificate* certificate); + /** + * @brief return the date string of the certificate validity + * @param certificate The certificate instance to query + * @param startDate \b TRUE return the start date, \b FALSE for the end date + * @return A newly allocated string containing the date, use \b free to deallocate + * @since version 3.8.0 + */ FREERDP_API char* freerdp_certificate_get_validity(const rdpCertificate* certificate, BOOL startDate); diff --git a/include/freerdp/locale/keyboard.h b/include/freerdp/locale/keyboard.h index d109d0a4d..ee614522e 100644 --- a/include/freerdp/locale/keyboard.h +++ b/include/freerdp/locale/keyboard.h @@ -177,7 +177,7 @@ typedef struct #define KBD_CZECH_PROGRAMMERS 0x00020405 #define KBD_GREEK_319 0x00020408 #define KBD_UNITED_STATES_INTERNATIONAL 0x00020409 -#define KBD_HEBREW_STANDARD 0x0002040D +#define KBD_HEBREW_STANDARD 0x0002040D /** @since version 3.6.0 */ #define KBD_RUSSIAN_PHONETIC 0x00020419 #define KBD_THAI_KEDMANEE_NON_SHIFTLOCK 0x0002041E #define KBD_BANGLA 0x00020445 diff --git a/include/freerdp/locale/locale.h b/include/freerdp/locale/locale.h index 4499d6da0..8b2c2a5e0 100644 --- a/include/freerdp/locale/locale.h +++ b/include/freerdp/locale/locale.h @@ -30,6 +30,9 @@ #include #include +/** @defgroup keyboard-identifiers + * @{ + */ #define AFRIKAANS 0x0436 #define ALBANIAN 0x041C #define ALSATIAN 0x0484 @@ -233,15 +236,20 @@ #define YI 0x0478 #define YORUBA 0x046A #define ZULU 0x0435 +/** @} */ -#define LOCALE_LANGUAGE_LEN 6 -#define LOCALE_COUNTRY_LEN 10 +#define LOCALE_LANGUAGE_LEN 6 /** @since version 3.6.0 */ +#define LOCALE_COUNTRY_LEN 10 /** @since version 3.6.0 */ #ifdef __cplusplus extern "C" { #endif + /** + * @brief A SYSTEM_LOCALE holding details about a locale + * @since version 3.6.0 + */ typedef struct { char language[LOCALE_LANGUAGE_LEN]; /* Two or three letter language code */ @@ -254,9 +262,29 @@ extern "C" FREERDP_API const char* freerdp_get_system_locale_name_from_id(DWORD localeId); FREERDP_API int freerdp_detect_keyboard_layout_from_system_locale(DWORD* keyboardLayoutId); + /** + * @brief Query the list of supported system locales + * @param count A pointer to hold the number of locales found + * @return A pointer to @SYSTEM_LOCALE or \b NULL in case none found + * @since version 3.6.0 + */ FREERDP_API const SYSTEM_LOCALE* freerdp_get_system_locale_list(size_t* count); + /** + * @brief Query the list of system locales and return a matching one + * + * @param locale A locale string to query + * @return A locale index >= 0 in case of success, <0 for failure + * @since version 3.6.0 + */ FREERDP_API INT64 freerdp_get_locale_id_from_string(const char* locale); + + /** + * @brief Return the default @keyboard-identifiers for a provided locale + * @param locale The locale to query + * @return The @keyboard-identifiers to use + * @since version 3.6.0 + */ FREERDP_API DWORD freerdp_get_keyboard_default_layout_for_locale(DWORD locale); #ifdef __cplusplus diff --git a/include/freerdp/primitives.h b/include/freerdp/primitives.h index 7cea33b32..7823e5863 100644 --- a/include/freerdp/primitives.h +++ b/include/freerdp/primitives.h @@ -102,8 +102,37 @@ typedef pstatus_t (*__alphaComp_argb_t)(const BYTE* WINPR_RESTRICT pSrc1, UINT32 typedef pstatus_t (*__add_16s_t)(const INT16* WINPR_RESTRICT pSrc1, const INT16* WINPR_RESTRICT pSrc2, INT16* WINPR_RESTRICT pDst, UINT32 len); +/** + * @brief Add INT16 from pSrcDst2 to pSrcDst1 and store in both arrays + * @param pSrcDst1 A pointer to the array of INT16 to add to + * @param pSrcDst2 A pointer to the array of INT16 to add to + * @param len The number of INT16 in the arrays + * @return \b <=0 for failure, success otherwise + * @since version 3.6.0 + */ typedef pstatus_t (*__add_16s_inplace_t)(INT16* WINPR_RESTRICT pSrcDst1, INT16* WINPR_RESTRICT pSrcDst2, UINT32 len); + +/** + * @brief Copy (sub)image data without overlapping + * + * @param pDstData The destination image buffer + * @param DstFormat The destination image format @PIXEL_FORMAT + * @param nDstStep The destination image line width in bytes (including padding) + * @param nXDst The X coordinate to start copying to + * @param nYDst The Y coordinate to start copying to + * @param nWidth The width in pixels to copy + * @param nHeight The height in pixels to copy + * @param pSrcData The source image buffer + * @param SrcFormat The source image format @PIXEL_FORMAT + * @param nSrcStep The source image line with in bytes (including padding) + * @param nXSrc The X coordinate to start copying from + * @param nYSrc The Y coordinate to start copying from + * @param palette A color palette for 8 bit colors + * @param flags Copy flags @FREERDP_IMAGE_FLAGS + * @return \b <=0 for failure, success otherwise + * @since version 3.6.0 + */ typedef pstatus_t (*__copy_no_overlap_t)(BYTE* WINPR_RESTRICT pDstData, DWORD DstFormat, UINT32 nDstStep, UINT32 nXDst, UINT32 nYDst, UINT32 nWidth, UINT32 nHeight, const BYTE* WINPR_RESTRICT pSrcData, @@ -224,9 +253,9 @@ typedef struct /** \brief Do vecotor addition, store result in both input buffers * pSrcDst1 = pSrcDst2 = pSrcDst1 + pSrcDst2 */ - __add_16s_inplace_t add_16s_inplace; - __lShiftC_16s_inplace_t lShiftC_16s_inplace; - __copy_no_overlap_t copy_no_overlap; + __add_16s_inplace_t add_16s_inplace; /** @since version 3.6.0 */ + __lShiftC_16s_inplace_t lShiftC_16s_inplace; /** @since version 3.6.0 */ + __copy_no_overlap_t copy_no_overlap; /** @since version 3.6.0 */ } primitives_t; typedef enum diff --git a/include/freerdp/rail.h b/include/freerdp/rail.h index 64a01e51f..223aa0b4c 100644 --- a/include/freerdp/rail.h +++ b/include/freerdp/rail.h @@ -583,6 +583,15 @@ typedef enum FREERDP_API BOOL utf8_string_to_rail_string(const char* string, RAIL_UNICODE_STRING* unicode_string); + /** @brief convert rails handshake flags to a string representation + * + * @param flags The flags to stringify + * @param buffer a string buffer to write to + * @param len the size in bytes of the string buffer + * + * @return A pointer to buffer or \b NULL in case of failure + * @since version 3.5.0 + */ FREERDP_API const char* rail_handshake_ex_flags_to_string(UINT32 flags, char* buffer, size_t len); diff --git a/include/freerdp/server/proxy/proxy_config.h b/include/freerdp/server/proxy/proxy_config.h index ffb92372d..d6b50caea 100644 --- a/include/freerdp/server/proxy/proxy_config.h +++ b/include/freerdp/server/proxy/proxy_config.h @@ -26,6 +26,11 @@ #include #include +/** @defgroup proxy_config + * @ingroup proxy + * @{ + */ + #ifdef __cplusplus extern "C" { @@ -81,11 +86,11 @@ extern "C" size_t InterceptCount; /* clipboard specific settings */ - WINPR_DEPRECATED_VAR("Unused, ignore", BOOL TextOnly); - WINPR_DEPRECATED_VAR("Unused, ignore", UINT32 MaxTextLength); + WINPR_DEPRECATED_VAR("[since 3.6.0] Unused, ignore", BOOL TextOnly); + WINPR_DEPRECATED_VAR("[since 3.6.0] Unused, ignore", UINT32 MaxTextLength); /* gfx settings */ - WINPR_DEPRECATED_VAR("Unused, ignore", BOOL DecodeGFX); + WINPR_DEPRECATED_VAR("[since 3.6.0] Unused, ignore", BOOL DecodeGFX); /* modules */ char** Modules; /* module file names to load */ @@ -111,7 +116,7 @@ extern "C" wIniFile* ini; /* target continued */ - UINT32 TargetTlsSecLevel; + UINT32 TargetTlsSecLevel; /** @since version 3.2.0 */ }; /** @@ -232,4 +237,7 @@ extern "C" #ifdef __cplusplus } #endif + +/** @} */ + #endif /* FREERDP_SERVER_PROXY_CONFIG_H */ diff --git a/include/freerdp/server/shadow.h b/include/freerdp/server/shadow.h index 329591a69..302b92ea1 100644 --- a/include/freerdp/server/shadow.h +++ b/include/freerdp/server/shadow.h @@ -135,7 +135,7 @@ extern "C" BOOL resizeRequested; UINT32 resizeWidth; UINT32 resizeHeight; - BOOL areGfxCapsReady; + BOOL areGfxCapsReady; /** @since version 3.3.0 */ }; struct rdp_shadow_server @@ -303,11 +303,24 @@ extern "C" FREERDP_API void shadow_subsystem_set_entry(pfnShadowSubsystemEntry pEntry); FREERDP_API WINPR_DEPRECATED_VAR( - "Use shadow_subsystem_pointer_convert_alpha_pointer_data_to_format instead", + "[since 3.4.0] Use shadow_subsystem_pointer_convert_alpha_pointer_data_to_format instead", int shadow_subsystem_pointer_convert_alpha_pointer_data( const BYTE* WINPR_RESTRICT pixels, BOOL premultiplied, UINT32 width, UINT32 height, SHADOW_MSG_OUT_POINTER_ALPHA_UPDATE* WINPR_RESTRICT pointerColor)); + /** @brief Convert a pointer image from input format to RDP specific encoding + * + * @param pixels A pointer to the pixel data + * @param format The pixel format of the pointer image + * @param premultiplied Premultiplied format, requires scaling of pixel colors + * @param width The width in pixels of the pointer + * @param height The height of the pointer + * @param pointerColor A pointer to the struct that can hold the encoded data + * + * @return \b >=0 for success, \b <0 for any failure + * + * @since version 3.4.0 + */ FREERDP_API int shadow_subsystem_pointer_convert_alpha_pointer_data_to_format( const BYTE* WINPR_RESTRICT pixels, UINT32 format, BOOL premultiplied, UINT32 width, UINT32 height, SHADOW_MSG_OUT_POINTER_ALPHA_UPDATE* WINPR_RESTRICT pointerColor); @@ -334,11 +347,27 @@ extern "C" FREERDP_API int shadow_capture_align_clip_rect(RECTANGLE_16* rect, const RECTANGLE_16* clip); FREERDP_API WINPR_DEPRECATED_VAR( - "Use shadow_capture_compare_with_format", + "[since 3.4.0] Use shadow_capture_compare_with_format", int shadow_capture_compare(const BYTE* WINPR_RESTRICT pData1, UINT32 nStep1, UINT32 nWidth, UINT32 nHeight, const BYTE* WINPR_RESTRICT pData2, UINT32 nStep2, RECTANGLE_16* WINPR_RESTRICT rect)); + /** @brief Compare two framebuffer images of possibly different formats with each other + * + * @param pData1 A pointer to the data of image 1 + * @param format1 The format of image 1 + * @param nStep1 The line width in bytes of image 1 + * @param nWidth The line width in pixels of image 1 + * @param nHeight The height of image 1 + * @param pData2 A pointer to the data of image 2 + * @param format2 The format of image 2 + * @param nStep2 The line width in bytes of image 2 + * @param rect A pointer to the rectangle of the images to compare + * + * @return \b 0 if equal, \b >0 if not equal and \b <0 for any error + * + * @since version 3.4.0 + */ FREERDP_API int shadow_capture_compare_with_format(const BYTE* WINPR_RESTRICT pData1, UINT32 format1, UINT32 nStep1, UINT32 nWidth, UINT32 nHeight, diff --git a/include/freerdp/settings.h b/include/freerdp/settings.h index c3fa6803b..527cd96ca 100644 --- a/include/freerdp/settings.h +++ b/include/freerdp/settings.h @@ -47,30 +47,32 @@ extern "C" { #endif -/** \file - * \brief This is the FreeRDP settings module. - * - * Settings are used to store configuration data for an RDP connection. - * There are 3 different settings for each client and server: - * - * 1. The initial connection supplied by the user - * 2. The settings sent from client or server during capability exchange - * 3. The settings merged from the capability exchange and the initial configuration. - * - * The lifetime of the settings is as follows: - * 1. Initial configuration is saved and will be valid for the whole application lifecycle - * 2. The client or server settings from the other end are valid from capability exchange until the - * connection is ended (disconnect/redirect/...) - * 3. The merged settings are created from the initial configuration and server settings and have - * the same lifetime, until the connection ends - * - * - * So, when accessing the settings always ensure to know which one you are operating on! (this is - * especially important for the proxy where you have a RDP client and RDP server in the same - * application context) - */ + /** \defgroup rdpSettings + * \brief This is the FreeRDP settings module. + * + * Settings are used to store configuration data for an RDP connection. + * There are 3 different settings for each client and server: + * + * 1. The initial connection supplied by the user + * 2. The settings sent from client or server during capability exchange + * 3. The settings merged from the capability exchange and the initial configuration. + * + * The lifetime of the settings is as follows: + * 1. Initial configuration is saved and will be valid for the whole application lifecycle + * 2. The client or server settings from the other end are valid from capability exchange until + * the connection is ended (disconnect/redirect/...) + * 3. The merged settings are created from the initial configuration and server settings and + * have the same lifetime, until the connection ends + * + * + * So, when accessing the settings always ensure to know which one you are operating on! (this + * is especially important for the proxy where you have a RDP client and RDP server in the same + * application context) + * + * @{ + */ -typedef struct rdp_settings rdpSettings; + typedef struct rdp_settings rdpSettings; /** * rdpSettings creation flags @@ -171,6 +173,8 @@ typedef struct rdp_settings rdpSettings; * \param settings the settings to remove the device from * \param device the device to remove * + * \since version 3.4.0 + * * \return \b TRUE if the device was removed, \b FALSE if device was not found or is NULL */ FREERDP_API BOOL freerdp_device_collection_del(rdpSettings* settings, @@ -714,6 +718,8 @@ typedef struct rdp_settings rdpSettings; size_t size); /** \brief return the configuration directory for the library + * @return The current configuration path or \b NULL + * @since version 3.6.0 */ FREERDP_API char* freerdp_settings_get_config_path(void); @@ -721,4 +727,6 @@ typedef struct rdp_settings rdpSettings; } #endif +/** @} */ + #endif /* FREERDP_SETTINGS_H */ diff --git a/include/freerdp/settings_types.h b/include/freerdp/settings_types.h index 2f02e3277..be1ce6bde 100644 --- a/include/freerdp/settings_types.h +++ b/include/freerdp/settings_types.h @@ -40,33 +40,14 @@ extern "C" { #endif -/** \file - * \brief This is the FreeRDP settings module. - * - * Settings are used to store configuration data for an RDP connection. - * There are 3 different settings for each client and server: - * - * 1. The initial connection supplied by the user - * 2. The settings sent from client or server during capability exchange - * 3. The settings merged from the capability exchange and the initial configuration. - * - * The lifetime of the settings is as follows: - * 1. Initial configuration is saved and will be valid for the whole application lifecycle - * 2. The client or server settings from the other end are valid from capability exchange until the - * connection is ended (disconnect/redirect/...) - * 3. The merged settings are created from the initial configuration and server settings and have - * the same lifetime, until the connection ends - * - * - * So, when accessing the settings always ensure to know which one you are operating on! (this is - * especially important for the proxy where you have a RDP client and RDP server in the same - * application context) - */ + /** @addtogroup rdpSettings + * @{ + */ /* Surface Commands Flags */ -#define SURFCMDS_SET_SURFACE_BITS 0x00000002 -#define SURFCMDS_FRAME_MARKER 0x00000010 -#define SURFCMDS_STREAM_SURFACE_BITS 0x00000040 +#define SURFCMDS_SET_SURFACE_BITS 0x00000002 /** @since version 3.7.0 */ +#define SURFCMDS_FRAME_MARKER 0x00000010 /** @since version 3.7.0 */ +#define SURFCMDS_STREAM_SURFACE_BITS 0x00000040 /** @since version 3.7.0 */ /* RAIL Support Level */ #define RAIL_LEVEL_SUPPORTED 0x00000001 @@ -90,9 +71,11 @@ extern "C" #define PERF_ENABLE_DESKTOP_COMPOSITION 0x00000100 /* Connection Types */ -#define CONNECTION_TYPE_INVALID \ - 0x00 /* synthetic, removes RNS_UD_CS_VALID_CONNECTION_TYPE from ConnectionType in \ - EarlyCapabilityFlags */ +#define CONNECTION_TYPE_INVALID \ + 0x00 /** @brief synthetic, removes RNS_UD_CS_VALID_CONNECTION_TYPE from ConnectionType in \ + * EarlyCapabilityFlags \ + * @since version 3.6.0 \ + */ #define CONNECTION_TYPE_MODEM 0x01 #define CONNECTION_TYPE_BROADBAND_LOW 0x02 #define CONNECTION_TYPE_SATELLITE 0x03 @@ -248,7 +231,7 @@ extern "C" #define DEFAULT_COOKIE_MAX_LENGTH 0xFF /* General capability set */ -#define TS_CAPS_PROTOCOLVERSION 0x200 +#define TS_CAPS_PROTOCOLVERSION 0x200 /** @since version 3.6.0 */ /* Order Support */ #define NEG_DSTBLT_INDEX 0x00 @@ -522,4 +505,6 @@ extern "C" } #endif +/** @} */ + #endif /* FREERDP_SETTINGS_TYPES_H */ diff --git a/include/freerdp/settings_types_private.h b/include/freerdp/settings_types_private.h index ccc7a0282..f83b44465 100644 --- a/include/freerdp/settings_types_private.h +++ b/include/freerdp/settings_types_private.h @@ -32,6 +32,10 @@ #include +/** \addtogroup rdpSettings + * @{ + */ + #ifdef __cplusplus extern "C" { @@ -71,7 +75,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 char* AcceptedCert); /* 27 */ SETTINGS_DEPRECATED(ALIGN64 UINT32 AcceptedCertLength); /* 28 */ SETTINGS_DEPRECATED(ALIGN64 char* UserSpecifiedServerName); /* 29 */ - SETTINGS_DEPRECATED(ALIGN64 char* AadServerHostname); /* 30 */ + SETTINGS_DEPRECATED(ALIGN64 char* AadServerHostname); /** 30 + * @since version 3.1.0 + */ UINT64 padding0064[64 - 31]; /* 31 */ /* resource management related options */ SETTINGS_DEPRECATED(ALIGN64 UINT32 ThreadingFlags); /* 64 */ @@ -213,7 +219,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 ARC_CS_PRIVATE_PACKET* ClientAutoReconnectCookie); /* 834 */ SETTINGS_DEPRECATED(ALIGN64 ARC_SC_PRIVATE_PACKET* ServerAutoReconnectCookie); /* 835 */ SETTINGS_DEPRECATED(ALIGN64 BOOL PrintReconnectCookie); /* 836 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL AutoReconnectionPacketSupported); /* 837 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL AutoReconnectionPacketSupported); /** 837 + @since version 3.5.0 +*/ UINT64 padding0896[896 - 838]; /* 838 */ /* Client Info (Time Zone) */ @@ -432,7 +440,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 char* TransportDumpFile); /* 1861 */ SETTINGS_DEPRECATED(ALIGN64 BOOL TransportDumpReplay); /* 1862 */ SETTINGS_DEPRECATED(ALIGN64 BOOL DeactivateClientDecoding); /* 1863 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL TransportDumpReplayNodelay); /* 1864 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL TransportDumpReplayNodelay); /** 1864 + * @since version 3.6.0 + */ UINT64 padding1920[1920 - 1865]; /* 1865 */ UINT64 padding1984[1984 - 1920]; /* 1920 */ @@ -469,7 +479,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 char* GatewayAvdDiagnosticserviceurl); /* 2009 */ SETTINGS_DEPRECATED(ALIGN64 char* GatewayAvdHubdiscoverygeourl); /* 2010 */ SETTINGS_DEPRECATED(ALIGN64 char* GatewayAvdActivityhint); /* 2011 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL GatewayIgnoreRedirectionPolicy); /* 2012 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL GatewayIgnoreRedirectionPolicy); /** 2012 + * @since version 3.4.0 + */ UINT64 padding2015[2015 - 2013]; /* 2013 */ /* Proxy */ @@ -650,7 +662,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 BOOL SurfaceCommandsEnabled); /* 3520 */ SETTINGS_DEPRECATED(ALIGN64 BOOL FrameMarkerCommandEnabled); /* 3521 */ SETTINGS_DEPRECATED(ALIGN64 BOOL SurfaceFrameMarkerEnabled); /* 3522 */ - SETTINGS_DEPRECATED(ALIGN64 UINT32 SurfaceCommandsSupported); /* 3523 */ + SETTINGS_DEPRECATED(ALIGN64 UINT32 SurfaceCommandsSupported); /** 3523 + * @since version 3.7.0 + */ UINT64 padding3584[3584 - 3524]; /* 3524 */ UINT64 padding3648[3648 - 3584]; /* 3584 */ @@ -665,7 +679,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 UINT32 RemoteFxCodecMode); /* 3651 */ SETTINGS_DEPRECATED(ALIGN64 BOOL RemoteFxImageCodec); /* 3652 */ SETTINGS_DEPRECATED(ALIGN64 UINT32 RemoteFxCaptureFlags); /* 3653 */ - SETTINGS_DEPRECATED(ALIGN64 UINT32 RemoteFxRlgrMode); /* 3654 */ + SETTINGS_DEPRECATED(ALIGN64 UINT32 RemoteFxRlgrMode); /** 3654 + * @since version 3.7.0 + */ UINT64 padding3712[3712 - 3655]; /* 3655 */ /* NSCodec */ @@ -693,7 +709,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 BOOL GfxAVC444v2); /* 3847 */ SETTINGS_DEPRECATED(ALIGN64 UINT32 GfxCapsFilter); /* 3848 */ SETTINGS_DEPRECATED(ALIGN64 BOOL GfxPlanar); /* 3849 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL GfxSuspendFrameAck); /* 3850 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL GfxSuspendFrameAck); /** 3850 + * @since version 3.6.0 + */ UINT64 padding3904[3904 - 3851]; /* 3851 */ /** @@ -748,7 +766,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 BOOL RedirectSerialPorts); /* 4672 */ SETTINGS_DEPRECATED(ALIGN64 BOOL RedirectParallelPorts); /* 4673 */ SETTINGS_DEPRECATED(ALIGN64 BOOL PreferIPv6OverIPv4); /* 4674 */ - SETTINGS_DEPRECATED(ALIGN64 UINT32 ForceIPvX); /* 4675 */ + SETTINGS_DEPRECATED(ALIGN64 UINT32 ForceIPvX); /** 4675 + * @since version 3.6.0 + */ UINT64 padding4800[4800 - 4676]; /* 4676 */ /** @@ -767,7 +787,8 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 UINT32 StaticChannelCount); /* 4928 */ SETTINGS_DEPRECATED(ALIGN64 UINT32 StaticChannelArraySize); /* 4929 */ SETTINGS_DEPRECATED(ALIGN64 ADDIN_ARGV** StaticChannelArray); /* 4930 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL SynchronousStaticChannels); /* 4931 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL SynchronousStaticChannels); /** 4931 + * @since version 3.3.0 */ UINT64 padding5056[5056 - 4932]; /* 4932 */ /** @@ -778,7 +799,9 @@ struct rdp_settings SETTINGS_DEPRECATED(ALIGN64 UINT32 DynamicChannelArraySize); /* 5057 */ SETTINGS_DEPRECATED(ALIGN64 ADDIN_ARGV** DynamicChannelArray); /* 5058 */ SETTINGS_DEPRECATED(ALIGN64 BOOL SupportDynamicChannels); /* 5059 */ - SETTINGS_DEPRECATED(ALIGN64 BOOL SynchronousDynamicChannels); /* 5060 */ + SETTINGS_DEPRECATED(ALIGN64 BOOL SynchronousDynamicChannels); /** 5060 + * @since version 3.2.0 + */ UINT64 padding5184[5184 - 5061]; /* 5061 */ SETTINGS_DEPRECATED(ALIGN64 BOOL SupportEchoChannel); /* 5184 */ @@ -810,4 +833,6 @@ struct rdp_settings } #endif +/** @} */ + #endif /* FREERDP_SETTINGS_TYPES_PRIVATE_H */ diff --git a/include/freerdp/transport_io.h b/include/freerdp/transport_io.h index b0beb7c09..566ca04bc 100644 --- a/include/freerdp/transport_io.h +++ b/include/freerdp/transport_io.h @@ -32,13 +32,34 @@ extern "C" { #endif + + /** + * @brief Read data from a transport layer + * @param userContext + * @param data a buffer to read to + * @param bytes the size of the buffer + * @return the number of bytes read or <0 for failures + * @since version 3.9.0 + */ typedef int (*pTransportLayerRead)(void* userContext, void* data, int bytes); + + /** + * @brief write data to a transport layer + * @param userContext + * @param data a buffer to write + * @param bytes the size of the buffer + * @return the number of bytes written or <0 for failures + * @since version 3.9.0 + */ typedef int (*pTransportLayerWrite)(void* userContext, const void* data, int bytes); typedef BOOL (*pTransportLayerFkt)(void* userContext); typedef BOOL (*pTransportLayerWait)(void* userContext, BOOL waitWrite, DWORD timeout); typedef HANDLE (*pTransportLayerGetEvent)(void* userContext); - struct rdp_transport_layer + /** + * @since version 3.9.0 + */ + typedef struct { ALIGN64 void* userContext; ALIGN64 pTransportLayerRead Read; @@ -47,8 +68,7 @@ extern "C" ALIGN64 pTransportLayerWait Wait; ALIGN64 pTransportLayerGetEvent GetEvent; UINT64 reserved[64 - 6]; /* Reserve some space for ABI compatibility */ - }; - typedef struct rdp_transport_layer rdpTransportLayer; + } rdpTransportLayer; typedef int (*pTCPConnect)(rdpContext* context, rdpSettings* settings, const char* hostname, int port, DWORD timeout); @@ -58,10 +78,26 @@ extern "C" typedef SSIZE_T (*pTransportRead)(rdpTransport* transport, BYTE* data, size_t bytes); typedef BOOL (*pTransportGetPublicKey)(rdpTransport* transport, const BYTE** data, DWORD* length); + /** @brief + * + * @param transport The transport to manipulate + * @param blocking Boolean to set the transport \b TRUE blocking and \b FALSE non-blocking + * @return \b TRUE for success, \b FALSE for any error + * + * @since version 3.3.0 + */ typedef BOOL (*pTransportSetBlockingMode)(rdpTransport* transport, BOOL blocking); typedef rdpTransportLayer* (*pTransportConnectLayer)(rdpTransport* transport, const char* hostname, int port, DWORD timeout); + /** @brief Return the public key as PEM from transport layer. + * @param transport the transport to query + * @param data A pointer to hold the allocated result + * @param length A pointer to hold the length in bytes of the result + * + * @return \b TRUE for success, \b FALSE for failure + * @since version 3.2.0 + */ typedef BOOL (*pTransportAttachLayer)(rdpTransport* transport, rdpTransportLayer* layer); struct rdp_transport_io @@ -74,10 +110,10 @@ extern "C" pTransportRWFkt ReadPdu; /* Reads a whole PDU from the transport */ pTransportRWFkt WritePdu; /* Writes a whole PDU to the transport */ pTransportRead ReadBytes; /* Reads up to a requested amount of bytes */ - pTransportGetPublicKey GetPublicKey; - pTransportSetBlockingMode SetBlockingMode; - pTransportConnectLayer ConnectLayer; - pTransportAttachLayer AttachLayer; + pTransportGetPublicKey GetPublicKey; /** @since version 3.2.0 */ + pTransportSetBlockingMode SetBlockingMode; /** @since version 3.3.0 */ + pTransportConnectLayer ConnectLayer; /** @since 3.9.0 */ + pTransportAttachLayer AttachLayer; /** @since 3.9.0 */ UINT64 reserved[64 - 12]; /* Reserve some space for ABI compatibility */ }; typedef struct rdp_transport_io rdpTransportIo; @@ -101,9 +137,23 @@ extern "C" FREERDP_API rdpContext* transport_get_context(rdpTransport* transport); FREERDP_API rdpTransport* freerdp_get_transport(rdpContext* context); - FREERDP_API rdpTransportLayer* transport_layer_new(rdpTransport* transport, size_t contextSize); + /** + * @brief Free a transport layer instance + * @param layer A pointer to the layer to free or \b NULL + * @since version 3.9.0 + */ FREERDP_API void transport_layer_free(rdpTransportLayer* layer); + /** + * @brief Create new transport layer instance + * @param transport A pointer to the transport instance to use + * @param contextSize The size of the context to use + * @return A new transport layer instance or \b NULL in case of failure + * @since version 3.9.0 + */ + WINPR_ATTR_MALLOC(transport_layer_free, 1) + FREERDP_API rdpTransportLayer* transport_layer_new(rdpTransport* transport, size_t contextSize); + #ifdef __cplusplus } #endif diff --git a/include/freerdp/utils/gfx.h b/include/freerdp/utils/gfx.h index 1e487862b..9f25242fd 100644 --- a/include/freerdp/utils/gfx.h +++ b/include/freerdp/utils/gfx.h @@ -30,6 +30,12 @@ extern "C" { #endif + /** + * @brief Stringification utility for rdpgfx capability versions + * @param capsVersion A capability version integer + * @return The string representation of the capabilities + * @since version 3.9.0 + */ FREERDP_API const char* rdpgfx_caps_version_str(UINT32 capsVersion); FREERDP_API const char* rdpgfx_get_cmd_id_string(UINT16 cmdId); diff --git a/libfreerdp/utils/passphrase.c b/libfreerdp/utils/passphrase.c index 2328b8b18..9ca51bd17 100644 --- a/libfreerdp/utils/passphrase.c +++ b/libfreerdp/utils/passphrase.c @@ -46,8 +46,8 @@ int freerdp_interruptible_getc(rdpContext* context, FILE* f) return read_chr(f); } -char* freerdp_passphrase_read(rdpContext* context, const char* prompt, char* buf, size_t bufsiz, - int from_stdin) +const char* freerdp_passphrase_read(rdpContext* context, const char* prompt, char* buf, + size_t bufsiz, int from_stdin) { WCHAR UserNameW[CREDUI_MAX_USERNAME_LENGTH + 1] = { 'p', 'r', 'e', 'f', 'i', 'l', 'l', 'e', 'd', '\0' }; @@ -127,8 +127,8 @@ static void replace_char(char* buffer, size_t buffer_len, const char* toreplace) } } -static char* freerdp_passphrase_read_tty(rdpContext* context, const char* prompt, char* buf, - size_t bufsiz, int from_stdin) +static const char* freerdp_passphrase_read_tty(rdpContext* context, const char* prompt, char* buf, + size_t bufsiz, int from_stdin) { BOOL terminal_needs_reset = FALSE; char term_name[L_ctermid] = { 0 }; @@ -271,8 +271,8 @@ int freerdp_interruptible_getc(rdpContext* context, FILE* f) #else -char* freerdp_passphrase_read(rdpContext* context, const char* prompt, char* buf, size_t bufsiz, - int from_stdin) +const char* freerdp_passphrase_read(rdpContext* context, const char* prompt, char* buf, + size_t bufsiz, int from_stdin) { return NULL; } diff --git a/winpr/include/config/config.h.in b/winpr/include/config/config.h.in index e233e56d4..0e6959bdb 100644 --- a/winpr/include/config/config.h.in +++ b/winpr/include/config/config.h.in @@ -25,7 +25,7 @@ #cmakedefine WINPR_HAVE_UNWIND_H #cmakedefine WINPR_WITH_PNG -#cmakedefine WINPR_HAVE_STRERROR_R +#cmakedefine WINPR_HAVE_STRERROR_R /** @since version 3.3.0 */ #cmakedefine WITH_EVENTFD_READ_WRITE @@ -34,15 +34,15 @@ #cmakedefine WITH_INTERNAL_MD4 #cmakedefine WITH_INTERNAL_MD5 -#cmakedefine WITH_WINPR_JSON +#cmakedefine WITH_WINPR_JSON /** @since version 3.6.0 */ #cmakedefine WITH_DEBUG_NTLM #cmakedefine WITH_DEBUG_THREADS #cmakedefine WITH_DEBUG_EVENTS #cmakedefine WITH_DEBUG_MUTEX -#cmakedefine WINPR_UTILS_IMAGE_WEBP -#cmakedefine WINPR_UTILS_IMAGE_PNG -#cmakedefine WINPR_UTILS_IMAGE_JPEG +#cmakedefine WINPR_UTILS_IMAGE_WEBP /** @since version 3.3.0 */ +#cmakedefine WINPR_UTILS_IMAGE_PNG /** @since version 3.3.0 */ +#cmakedefine WINPR_UTILS_IMAGE_JPEG /** @since version 3.3.0 */ #endif /* WINPR_CONFIG_H */ diff --git a/winpr/include/winpr/collections.h b/winpr/include/winpr/collections.h index ec3de729c..ab2c1a7a8 100644 --- a/winpr/include/winpr/collections.h +++ b/winpr/include/winpr/collections.h @@ -63,8 +63,25 @@ extern "C" } wObject; /* utility function with compatible arguments for string data */ + + /** @brief helper function to clone a string + * @param pvstr the source string to clone + * @return A clone of the source or \b NULL + * @since version 3.3.0 + */ WINPR_API void* winpr_ObjectStringClone(const void* pvstr); + + /** @brief helper function to clone a WCHAR string + * @param pvstr the source string to clone + * @return A clone of the source or \b NULL + * @since version 3.3.0 + */ WINPR_API void* winpr_ObjectWStringClone(const void* pvstr); + + /** @brief helper function to free a (WCHAR) string + * @param pvstr the string to free + * @since version 3.3.0 + */ WINPR_API void winpr_ObjectStringFree(void* pvstr); /* System.Collections.Queue */ diff --git a/winpr/include/winpr/image.h b/winpr/include/winpr/image.h index cf33c5f5d..b267194af 100644 --- a/winpr/include/winpr/image.h +++ b/winpr/include/winpr/image.h @@ -60,10 +60,14 @@ typedef struct #pragma pack(pop) +/** @defgrop WINPR_IMAGE_FORMAT + * #{ + */ #define WINPR_IMAGE_BITMAP 0 #define WINPR_IMAGE_PNG 1 -#define WINPR_IMAGE_JPEG 2 -#define WINPR_IMAGE_WEBP 3 +#define WINPR_IMAGE_JPEG 2 /** @since version 3.3.0 */ +#define WINPR_IMAGE_WEBP 3 /** @since version 3.3.0 */ +/** #} */ #define WINPR_IMAGE_BMP_HEADER_LEN 54 @@ -78,6 +82,10 @@ typedef struct UINT32 bytesPerPixel; } wImage; +/** @defgroup WINPR_IMAGE_CMP_FLAGS + * @since version 3.3.0 + * @{ + */ typedef enum { WINPR_IMAGE_CMP_NO_FLAGS = 0, @@ -86,6 +94,8 @@ typedef enum WINPR_IMAGE_CMP_FUZZY = 4 } wImageFlags; +/** @} */ + #ifdef __cplusplus extern "C" { @@ -93,6 +103,20 @@ extern "C" WINPR_API int winpr_bitmap_write(const char* filename, const BYTE* data, size_t width, size_t height, size_t bpp); + + /** @brief write a bitmap to a file + * + * @param filename the name of the file to write to + * @param data the data of the bitmap without headers + * @param stride the byte size of a line in the image + * @param width the width in pixels of a line + * @param the height of the bitmap + * @param bpp the color depth of the bitmap + * + * @since version 3.3.0 + * + * @return \b >=0 for success, /b <0 for an error + */ WINPR_API int winpr_bitmap_write_ex(const char* filename, const BYTE* data, size_t stride, size_t width, size_t height, size_t bpp); WINPR_API BYTE* winpr_bitmap_construct_header(size_t width, size_t height, size_t bpp); @@ -101,6 +125,17 @@ extern "C" WINPR_API int winpr_image_write_ex(wImage* image, UINT32 format, const char* filename); WINPR_API int winpr_image_read(wImage* image, const char* filename); + /** @brief write a bitmap to a buffer and return it + * + * @param image the image to write + * @param format the format of type @WINPR_IMAGE_FORMAT + * @param size a pointer to hold the size in bytes of the allocated bitmap + * + * @since version 3.3.0 + * + * @return \b NULL in case of failure, a pointer to an allocated buffer otherwise. Use \b free + * as deallocator + */ WINPR_API void* winpr_image_write_buffer(wImage* image, UINT32 format, size_t* size); WINPR_API int winpr_image_read_buffer(wImage* image, const BYTE* buffer, size_t size); @@ -109,9 +144,46 @@ extern "C" WINPR_ATTR_MALLOC(winpr_image_free, 1) WINPR_API wImage* winpr_image_new(void); + /** @brief Check if a image format is supported + * + * @param format the format of type @WINPR_IMAGE_FORMAT + * + * @since version 3.3.0 + * + * @return \b TRUE if the format is supported, \b FALSE otherwise + */ WINPR_API BOOL winpr_image_format_is_supported(UINT32 format); + + /** @brief Return the file extension of a format + * + * @param format the format of type @WINPR_IMAGE_FORMAT + * + * @since version 3.3.0 + * + * @return a extension string if format has one or \b NULL + */ WINPR_API const char* winpr_image_format_extension(UINT32 format); + + /** @brief Return the mime type of a format + * + * @param format the format of type @WINPR_IMAGE_FORMAT + * + * @since version 3.3.0 + * + * @return a mime type string if format has one or \b NULL + */ WINPR_API const char* winpr_image_format_mime(UINT32 format); + + /** @brief Check if two images are content equal + * + * @param imageA the first image for the comparison + * @param imageB the second image for the comparison + * @param flags Comparions flags @WINPR_IMAGE_CMP_FLAGS + * + * @since version 3.3.0 + * + * @return \b TRUE if they are equal, \b FALSE otherwise + */ WINPR_API BOOL winpr_image_equal(const wImage* imageA, const wImage* imageB, UINT32 flags); #ifdef __cplusplus diff --git a/winpr/include/winpr/json.h b/winpr/include/winpr/json.h index 600b52a96..ce9acdf2a 100644 --- a/winpr/include/winpr/json.h +++ b/winpr/include/winpr/json.h @@ -25,6 +25,12 @@ #include #include +/** @defgroup WINPR_JSON + * @since version 3.6.0 + * @brief Wrapper around cJSON or JSONC libraries + * @{ + */ + #ifdef __cplusplus extern "C" { @@ -32,64 +38,355 @@ extern "C" typedef void WINPR_JSON; + /** + * @brief Get the library version string + * + * @param buffer a string buffer to hold the version string + * @param len the length of the buffer + * @return length of the version string in bytes or negative for error + * @since version 3.6.0 + */ WINPR_API int WINPR_JSON_version(char* buffer, size_t len); - WINPR_API WINPR_JSON* WINPR_JSON_Parse(const char* value); - WINPR_API WINPR_JSON* WINPR_JSON_ParseWithLength(const char* value, size_t buffer_length); - + /** + * @brief Delete a @WINPR_JSON object + * + * @param item The instance to delete + * @since version 3.6.0 + */ WINPR_API void WINPR_JSON_Delete(WINPR_JSON* item); + /** + * @brief Parse a '\0' terminated JSON string + * + * @param value A '\0' terminated JSON string + * @return A @WINPR_JSON object holding the parsed string or \b NULL if failed + * @since version 3.6.0 + */ + WINPR_ATTR_MALLOC(WINPR_JSON_Delete, 1) + WINPR_API WINPR_JSON* WINPR_JSON_Parse(const char* value); + + /** + * @brief Parse a JSON string + * + * @param value A JSON string + * @param buffer_length The length in bytes of the JSON string + * @return A @WINPR_JSON object holding the parsed string or \b NULL if failed + * @since version 3.6.0 + */ + WINPR_ATTR_MALLOC(WINPR_JSON_Delete, 1) + WINPR_API WINPR_JSON* WINPR_JSON_ParseWithLength(const char* value, size_t buffer_length); + + /** + * @brief Get the number of arrayitems from an array + * + * @param array the JSON instance to query + * @return number of array items + * @since version 3.6.0 + */ WINPR_API size_t WINPR_JSON_GetArraySize(const WINPR_JSON* array); + + /** + * @brief Return a pointer to an item in the array + * + * @param array the JSON instance to query + * @param index The index of the array item + * @return A pointer to the array item or \b NULL if failed + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_GetArrayItem(const WINPR_JSON* array, size_t index); + /** + * @brief Return a pointer to an JSON object item + * @param object the JSON object + * @param string the name of the object + * @return A pointer to the object identified by @string or \b NULL + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_GetObjectItem(const WINPR_JSON* object, const char* string); + + /** + * @brief Same as @WINPR_JSON_GetObjectItem but with case insensitive matching + * + * @param object the JSON instance to query + * @param string the name of the object + * @return A pointer to the object identified by @string or \b NULL + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_GetObjectItemCaseSensitive(const WINPR_JSON* object, const char* string); + + /** + * @brief Check if JSON has an object matching the name + * @param object the JSON instance + * @param string the name of the object + * @return \b TRUE if found, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_HasObjectItem(const WINPR_JSON* object, const char* string); + /** + * @brief Return an error string + * @return A string describing the last error that occured or \b NULL + * @since version 3.6.0 + */ WINPR_API const char* WINPR_JSON_GetErrorPtr(void); + /** + * @brief Return the String value of a JSON item + * @param item the JSON item to query + * @return The string value or \b NULL if failed + * @since version 3.6.0 + */ WINPR_API const char* WINPR_JSON_GetStringValue(WINPR_JSON* item); + + /** + * @brief Return the Number value of a JSON item + * @param item the JSON item to query + * @return The Number value or \b NaN if failed + * @since version 3.6.0 + */ WINPR_API double WINPR_JSON_GetNumberValue(const WINPR_JSON* item); + /** + * @brief Check if JSON item is valid + * @param item the JSON item to query + * @return \b TRUE if valid, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsInvalid(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is BOOL value False + * @param item the JSON item to query + * @return \b TRUE if False, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsFalse(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is BOOL value True + * @param item the JSON item to query + * @return \b TRUE if True, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsTrue(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is of type BOOL + * @param item the JSON item to query + * @return \b TRUE if the type is BOOL, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsBool(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is Null + * @param item the JSON item to query + * @return \b TRUE if it is Null, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsNull(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is of type Number + * @param item the JSON item to query + * @return \b TRUE if the type is Number, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsNumber(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is of type String + * @param item the JSON item to query + * @return \b TRUE if the type is String, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsString(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is of type Array + * @param item the JSON item to query + * @return \b TRUE if the type is Array, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsArray(const WINPR_JSON* item); + + /** + * @brief Check if JSON item is of type Object + * @param item the JSON item to query + * @return \b TRUE if the type is Object, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL WINPR_JSON_IsObject(const WINPR_JSON* item); + /** + * @brief WINPR_JSON_CreateNull + * @return a new JSON item of type and value Null + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateNull(void); + + /** + * @brief WINPR_JSON_CreateTrue + * @return a new JSON item of type Bool and value True + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateTrue(void); + + /** + * @brief WINPR_JSON_CreateFalse + * @return a new JSON item of type Bool and value False + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateFalse(void); + + /** + * @brief WINPR_JSON_CreateBool + * @param boolean the value the JSON item should have + * @return a new JSON item of type Bool + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateBool(BOOL boolean); + + /** + * @brief WINPR_JSON_CreateNumber + * @param num the number value of the new item + * @return a new JSON item of type Number + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateNumber(double num); + + /** + * @brief WINPR_JSON_CreateString + * @param string The string value of the new item + * @return a new JSON item of type String + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateString(const char* string); + + /** + * @brief WINPR_JSON_CreateArray + * @return a new JSON item of type array, empty + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateArray(void); + + /** + * @brief WINPR_JSON_CreateObject + * @return a new JSON item of type Object + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_CreateObject(void); + /** + * @brief WINPR_JSON_AddNullToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddNullToObject(WINPR_JSON* object, const char* name); + + /** + * @brief WINPR_JSON_AddTrueToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddTrueToObject(WINPR_JSON* object, const char* name); + + /** + * @brief WINPR_JSON_AddFalseToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddFalseToObject(WINPR_JSON* object, const char* name); + + /** + * @brief WINPR_JSON_AddBoolToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddBoolToObject(WINPR_JSON* object, const char* name, BOOL boolean); + + /** + * @brief WINPR_JSON_AddNumberToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddNumberToObject(WINPR_JSON* object, const char* name, double number); + + /** + * @brief WINPR_JSON_AddStringToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddStringToObject(WINPR_JSON* object, const char* name, const char* string); + + /** + * @brief WINPR_JSON_AddObjectToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddObjectToObject(WINPR_JSON* object, const char* name); + + /** + * @brief WINPR_JSON_AddArrayToObject + * @param object The JSON object the new item is added to + * @param name The name of the object + * @return the new JSON item added + * @since version 3.6.0 + */ WINPR_API WINPR_JSON* WINPR_JSON_AddArrayToObject(WINPR_JSON* object, const char* name); + /** + * @brief Add an item to an existing array + * @param array An array to add to, must not be \b NULL + * @param item An item to add, must not be \b NULL + * @return \b TRUE for success, \b FALSE for failure + * @since version 3.7.0 + */ WINPR_API BOOL WINPR_JSON_AddItemToArray(WINPR_JSON* array, WINPR_JSON* item); + /** + * @brief Serialize a JSON instance to string + * for minimal size without formatting see @WINPR_JSON_PrintUnformatted + * + * @param item The JSON instance to serialize + * @return A string representation of the JSON instance or \b NULL + * @since version 3.6.0 + */ WINPR_API char* WINPR_JSON_Print(WINPR_JSON* item); + + /** + * @brief Serialize a JSON instance to string without formatting + * for human readable formatted output see @WINPR_JSON_Print + * + * @param item The JSON instance to serialize + * @return A string representation of the JSON instance or \b NULL + * @since version 3.6.0 + */ WINPR_API char* WINPR_JSON_PrintUnformatted(WINPR_JSON* item); #ifdef __cplusplus } #endif +/** @} */ + #endif diff --git a/winpr/include/winpr/library.h b/winpr/include/winpr/library.h index 718d97b69..15bb84947 100644 --- a/winpr/include/winpr/library.h +++ b/winpr/include/winpr/library.h @@ -85,6 +85,14 @@ extern "C" } #endif +/** + * @brief A macro to get a function pointer from a library handle + * @param module The library handle + * @param name The name of the function + * @param type The type of the function pointer + * @since version 3.9.0 + * @return A new function pointer or \b NULL + */ #define GetProcAddressAs(module, name, type) WINPR_FUNC_PTR_CAST(GetProcAddress(module, name), type) #if !defined(_WIN32) && !defined(__CYGWIN__) diff --git a/winpr/include/winpr/ncrypt.h b/winpr/include/winpr/ncrypt.h index 8c19d403f..3415f0a37 100644 --- a/winpr/include/winpr/ncrypt.h +++ b/winpr/include/winpr/ncrypt.h @@ -217,6 +217,7 @@ extern "C" * * @param phProvider [in] provider handle * @return module path + * @since version 3.6.0 */ WINPR_API const char* winpr_NCryptGetModulePath(NCRYPT_PROV_HANDLE phProvider); diff --git a/winpr/include/winpr/platform.h b/winpr/include/winpr/platform.h index e591cc77b..fa3666f7c 100644 --- a/winpr/include/winpr/platform.h +++ b/winpr/include/winpr/platform.h @@ -25,9 +25,9 @@ #if defined(__clang__) #define WINPR_PRAGMA_DIAG_PUSH _Pragma("clang diagnostic push") #define WINPR_PRAGMA_DIAG_IGNORED_OVERLENGTH_STRINGS \ - _Pragma("clang diagnostic ignored \"-Woverlength-strings\"") + _Pragma("clang diagnostic ignored \"-Woverlength-strings\"") /** @since version 3.9.0 */ #define WINPR_PRAGMA_DIAG_IGNORED_QUALIFIERS \ - _Pragma("clang diagnostic ignored \"-Wdiscarded-qualifiers\"") + _Pragma("clang diagnostic ignored \"-Wdiscarded-qualifiers\"") /** @since version 3.9.0 */ #define WINPR_PRAGMA_DIAG_IGNORED_PEDANTIC _Pragma("clang diagnostic ignored \"-Wpedantic\"") #define WINPR_PRAGMA_DIAG_IGNORED_MISSING_PROTOTYPES \ _Pragma("clang diagnostic ignored \"-Wmissing-prototypes\"") @@ -46,17 +46,18 @@ #define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_SECURITY \ _Pragma("clang diagnostic ignored \"-Wformat-security\"") #define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_NONLITERAL \ - _Pragma("clang diagnostic ignored \"-Wformat-nonliteral\"") -#define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC /* not supported \ + _Pragma("clang diagnostic ignored \"-Wformat-nonliteral\"") /** @since version 3.9.0 */ +#define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC /** @since version 3.3.0 */ /* not supported \ _Pragma("clang diagnostic ignored \"-Wmismatched-dealloc\"") */ #define WINPR_PRAGMA_DIAG_POP _Pragma("clang diagnostic pop") -#define WINPR_PRAGMA_UNROLL_LOOP _Pragma("clang loop vectorize_width(8) interleave_count(8)") +#define WINPR_PRAGMA_UNROLL_LOOP \ + _Pragma("clang loop vectorize_width(8) interleave_count(8)") /** @since version 3.6.0 */ #elif defined(__GNUC__) #define WINPR_PRAGMA_DIAG_PUSH _Pragma("GCC diagnostic push") #define WINPR_PRAGMA_DIAG_IGNORED_OVERLENGTH_STRINGS \ - _Pragma("GCC diagnostic ignored \"-Woverlength-strings\"") + _Pragma("GCC diagnostic ignored \"-Woverlength-strings\"") /** @since version 3.9.0 */ #define WINPR_PRAGMA_DIAG_IGNORED_QUALIFIERS \ - _Pragma("GCC diagnostic ignored \"-Wdiscarded-qualifiers\"") + _Pragma("GCC diagnostic ignored \"-Wdiscarded-qualifiers\"") /** @since version 3.9.0 */ #define WINPR_PRAGMA_DIAG_IGNORED_PEDANTIC _Pragma("GCC diagnostic ignored \"-Wpedantic\"") #define WINPR_PRAGMA_DIAG_IGNORED_MISSING_PROTOTYPES \ _Pragma("GCC diagnostic ignored \"-Wmissing-prototypes\"") @@ -76,20 +77,21 @@ #define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_SECURITY \ _Pragma("GCC diagnostic ignored \"-Wformat-security\"") #define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_NONLITERAL \ - _Pragma("GCC diagnostic ignored \"-Wformat-nonliteral\"") + _Pragma("GCC diagnostic ignored \"-Wformat-nonliteral\"") /** @since version 3.9.0 */ #if __GNUC__ >= 11 #define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC \ - _Pragma("GCC diagnostic ignored \"-Wmismatched-dealloc\"") + _Pragma("GCC diagnostic ignored \"-Wmismatched-dealloc\"") /** @since version 3.3.0 */ #else #define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC #endif #define WINPR_PRAGMA_DIAG_POP _Pragma("GCC diagnostic pop") -#define WINPR_PRAGMA_UNROLL_LOOP _Pragma("GCC unroll 8") _Pragma("GCC ivdep") +#define WINPR_PRAGMA_UNROLL_LOOP \ + _Pragma("GCC unroll 8") _Pragma("GCC ivdep") /** @since version 3.6.0 */ #else #define WINPR_PRAGMA_DIAG_PUSH #define WINPR_PRAGMA_DIAG_IGNORED_PEDANTIC -#define WINPR_PRAGMA_DIAG_IGNORED_QUALIFIERS -#define WINPR_PRAGMA_DIAG_IGNORED_OVERLENGTH_STRINGS +#define WINPR_PRAGMA_DIAG_IGNORED_QUALIFIERS /** @since version 3.9.0 */ +#define WINPR_PRAGMA_DIAG_IGNORED_OVERLENGTH_STRINGS /** @since version 3.9.0 */ #define WINPR_PRAGMA_DIAG_IGNORED_MISSING_PROTOTYPES #define WINPR_PRAGMA_DIAG_IGNORED_STRICT_PROTOTYPES #define WINPR_PRAGMA_DIAG_IGNORED_RESERVED_ID_MACRO @@ -98,15 +100,15 @@ #define WINPR_PRAGMA_DIAG_IGNORED_ATOMIC_SEQ_CST #define WINPR_PRAGMA_DIAG_IGNORED_UNUSED_CONST_VAR #define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_SECURITY -#define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_NONLITERAL -#define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC +#define WINPR_PRAGMA_DIAG_IGNORED_FORMAT_NONLITERAL /** @since version 3.9.0 */ +#define WINPR_PRAGMA_DIAG_IGNORED_MISMATCHED_DEALLOC /** @since version 3.3.0 */ #define WINPR_PRAGMA_DIAG_POP -#define WINPR_PRAGMA_UNROLL_LOOP +#define WINPR_PRAGMA_UNROLL_LOOP /** @since version 3.6.0 */ #endif #if defined(MSVC) #undef WINPR_PRAGMA_UNROLL_LOOP -#define WINPR_PRAGMA_UNROLL_LOOP _Pragma("loop ( ivdep )") +#define WINPR_PRAGMA_UNROLL_LOOP _Pragma("loop ( ivdep )") /** @since version 3.6.0 */ #endif WINPR_PRAGMA_DIAG_PUSH diff --git a/winpr/include/winpr/secapi.h b/winpr/include/winpr/secapi.h index fe2419d7c..78443dd60 100644 --- a/winpr/include/winpr/secapi.h +++ b/winpr/include/winpr/secapi.h @@ -29,7 +29,7 @@ typedef enum _KERB_LOGON_SUBMIT_TYPE { - KerbInvalidValue = 0, + KerbInvalidValue = 0, /** @since version 3.9.0 */ KerbInteractiveLogon = 2, KerbSmartCardLogon = 6, KerbWorkstationUnlockLogon = 7, diff --git a/winpr/include/winpr/stream.h b/winpr/include/winpr/stream.h index 33411892b..257fca2bf 100644 --- a/winpr/include/winpr/stream.h +++ b/winpr/include/winpr/stream.h @@ -348,141 +348,309 @@ extern "C" return v; } + /** + * @brief Stream_Get_UINT8 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT8 Stream_Get_UINT8(wStream* _s) { return stream_read_u8(_s, TRUE); } + /** + * @brief Stream_Get_INT8 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT8 Stream_Get_INT8(wStream* _s) { return stream_read_i8(_s, TRUE); } + /** + * @brief Stream_Get_UINT16 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT16 Stream_Get_UINT16(wStream* _s) { return stream_read_u16_le(_s, TRUE); } + /** + * @brief Stream_Get_INT16 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT16 Stream_Get_INT16(wStream* _s) { return stream_read_i16_le(_s, TRUE); } + /** + * @brief Stream_Get_UINT16 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT16 Stream_Get_UINT16_BE(wStream* _s) { return stream_read_u16_be(_s, TRUE); } + /** + * @brief Stream_Get_INT16 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT16 Stream_Get_INT16_BE(wStream* _s) { return stream_read_i16_be(_s, TRUE); } + /** + * @brief Stream_Get_UINT32 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT32 Stream_Get_UINT32(wStream* _s) { return stream_read_u32_le(_s, TRUE); } + /** + * @brief Stream_Get_INT32 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT32 Stream_Get_INT32(wStream* _s) { return stream_read_i32_le(_s, TRUE); } + /** + * @brief Stream_Get_UINT32 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT32 Stream_Get_UINT32_BE(wStream* _s) { return stream_read_u32_be(_s, TRUE); } + /** + * @brief Stream_Get_INT32 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT32 Stream_Get_INT32_BE(wStream* _s) { return stream_read_i32_be(_s, TRUE); } + /** + * @brief Stream_Get_UINT64 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT64 Stream_Get_UINT64(wStream* _s) { return stream_read_u64_le(_s, TRUE); } + /** + * @brief Stream_Get_INT64 + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT64 Stream_Get_INT64(wStream* _s) { return stream_read_i64_le(_s, TRUE); } + /** + * @brief Stream_Get_UINT64 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT64 Stream_Get_UINT64_BE(wStream* _s) { return stream_read_u64_be(_s, TRUE); } + /** + * @brief Stream_Get_INT64 big endian + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT64 Stream_Get_INT64_BE(wStream* _s) { return stream_read_i64_be(_s, TRUE); } + /** + * @brief Read a UINT8 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT8 Stream_Peek_Get_UINT8(wStream* _s) { return stream_read_u8(_s, FALSE); } + /** + * @brief Read a INT8 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT8 Stream_Peek_Get_INT8(wStream* _s) { return stream_read_i8(_s, FALSE); } + /** + * @brief Read a UINT16 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT16 Stream_Peek_Get_UINT16(wStream* _s) { return stream_read_u16_le(_s, FALSE); } + /** + * @brief Read a INT16 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT16 Stream_Peek_Get_INT16(wStream* _s) { return stream_read_i16_le(_s, FALSE); } + /** + * @brief Read a UINT16 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT16 Stream_Peek_Get_UINT16_BE(wStream* _s) { return stream_read_u16_be(_s, FALSE); } + /** + * @brief Read a INT16 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT16 Stream_Peek_Get_INT16_BE(wStream* _s) { return stream_read_i16_be(_s, FALSE); } + /** + * @brief Read a UINT32 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT32 Stream_Peek_Get_UINT32(wStream* _s) { return stream_read_u32_le(_s, FALSE); } + /** + * @brief Read a INT32 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT32 Stream_Peek_Get_INT32(wStream* _s) { return stream_read_i32_le(_s, FALSE); } + /** + * @brief Read a UINT32 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT32 Stream_Peek_Get_UINT32_BE(wStream* _s) { return stream_read_u32_be(_s, FALSE); } + /** + * @brief Read a INT32 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT32 Stream_Peek_Get_INT32_BE(wStream* _s) { return stream_read_i32_be(_s, FALSE); } + /** + * @brief Read a UINT64 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT64 Stream_Peek_Get_UINT64(wStream* _s) { return stream_read_u64_le(_s, FALSE); } + /** + * @brief Read a INT64 from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT64 Stream_Peek_Get_INT64(wStream* _s) { return stream_read_i64_le(_s, FALSE); } + /** + * @brief Read a UINT64 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE UINT64 Stream_Peek_Get_UINT64_BE(wStream* _s) { return stream_read_u64_be(_s, FALSE); } + /** + * @brief Read a INT64 big endian from the stream, do not increment stream position + * @param _s The stream to read from + * @return an integer + * @since version 3.9.0 + */ static INLINE INT64 Stream_Peek_Get_INT64_BE(wStream* _s) { return stream_read_i64_be(_s, FALSE); diff --git a/winpr/include/winpr/sysinfo.h b/winpr/include/winpr/sysinfo.h index 45893fb25..d2a478f87 100644 --- a/winpr/include/winpr/sysinfo.h +++ b/winpr/include/winpr/sysinfo.h @@ -227,19 +227,19 @@ extern "C" #define PF_ARM_64BIT_LOADSTORE_ATOMIC 25 #define PF_ARM_EXTERNAL_CACHE_AVAILABLE 26 #define PF_ARM_FMAC_INSTRUCTIONS_AVAILABLE 27 -#define PF_SSSE3_INSTRUCTIONS_AVAILABLE 36 -#define PF_SSE4_1_INSTRUCTIONS_AVAILABLE 37 -#define PF_SSE4_2_INSTRUCTIONS_AVAILABLE 38 -#define PF_AVX_INSTRUCTIONS_AVAILABLE 39 -#define PF_AVX2_INSTRUCTIONS_AVAILABLE 40 -#define PF_AVX512F_INSTRUCTIONS_AVAILABLE 41 -#define PF_ARM_V8_INSTRUCTIONS_AVAILABLE 29 -#define PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE 30 -#define PF_ARM_V8_CRC32_INSTRUCTIONS_AVAILABLE 31 -#define PF_ARM_V81_ATOMIC_INSTRUCTIONS_AVAILABLE 34 -#define PF_ARM_V82_DP_INSTRUCTIONS_AVAILABLE 43 -#define PF_ARM_V83_JSCVT_INSTRUCTIONS_AVAILABLE 44 -#define PF_ARM_V83_LRCPC_INSTRUCTIONS_AVAILABLE 45 +#define PF_SSSE3_INSTRUCTIONS_AVAILABLE 36 /** @since version 3.3.0 */ +#define PF_SSE4_1_INSTRUCTIONS_AVAILABLE 37 /** @since version 3.3.0 */ +#define PF_SSE4_2_INSTRUCTIONS_AVAILABLE 38 /** @since version 3.3.0 */ +#define PF_AVX_INSTRUCTIONS_AVAILABLE 39 /** @since version 3.3.0 */ +#define PF_AVX2_INSTRUCTIONS_AVAILABLE 40 /** @since version 3.3.0 */ +#define PF_AVX512F_INSTRUCTIONS_AVAILABLE 41 /** @since version 3.3.0 */ +#define PF_ARM_V8_INSTRUCTIONS_AVAILABLE 29 /** @since version 3.3.0 */ +#define PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE 30 /** @since version 3.3.0 */ +#define PF_ARM_V8_CRC32_INSTRUCTIONS_AVAILABLE 31 /** @since version 3.3.0 */ +#define PF_ARM_V81_ATOMIC_INSTRUCTIONS_AVAILABLE 34 /** @since version 3.3.0 */ +#define PF_ARM_V82_DP_INSTRUCTIONS_AVAILABLE 43 /** @since version 3.3.0 */ +#define PF_ARM_V83_JSCVT_INSTRUCTIONS_AVAILABLE 44 /** @since version 3.3.0 */ +#define PF_ARM_V83_LRCPC_INSTRUCTIONS_AVAILABLE 45 /** @since version 3.3.0 */ #define PF_ARM_V4 0x80000001 #define PF_ARM_V5 0x80000002 @@ -335,15 +335,24 @@ extern "C" #endif -#define WINPR_TIME_NS_TO_S(ns) ((ns) / 1000000000ull) -#define WINPR_TIME_NS_TO_MS(ns) ((ns) / 1000000ull) -#define WINPR_TIME_NS_TO_US(ns) ((ns) / 1000ull) +#define WINPR_TIME_NS_TO_S(ns) ((ns) / 1000000000ull) /** @since version 3.4.0 */ +#define WINPR_TIME_NS_TO_MS(ns) ((ns) / 1000000ull) /** @since version 3.4.0 */ +#define WINPR_TIME_NS_TO_US(ns) ((ns) / 1000ull) /** @since version 3.4.0 */ -#define WINPR_TIME_NS_REM_NS(ns) ((ns) % 1000000000ull) -#define WINPR_TIME_NS_REM_US(ns) (WINPR_TIME_NS_REM_NS(ns) / 1000ull) -#define WINPR_TIME_NS_REM_MS(ns) (WINPR_TIME_NS_REM_US(ns) / 1000ull) +#define WINPR_TIME_NS_REM_NS(ns) ((ns) % 1000000000ull) /** @since version 3.4.0 */ +#define WINPR_TIME_NS_REM_US(ns) (WINPR_TIME_NS_REM_NS(ns) / 1000ull) /** @since version 3.4.0 */ +#define WINPR_TIME_NS_REM_MS(ns) (WINPR_TIME_NS_REM_US(ns) / 1000ull) /** @since version 3.4.0 */ + /** @brief get current tick count in nano second resolution + * @since version 3.4.0 + * @return The tick count in nanosecond resolution since a undefined reference data + */ WINPR_API UINT64 winpr_GetTickCount64NS(void); + + /** @brief the the current time in nano second resolution + * @since version 3.4.0 + * @return The nano seconds since 1.1.1970 + */ WINPR_API UINT64 winpr_GetUnixTimeNS(void); WINPR_API DWORD GetTickCountPrecise(void); diff --git a/winpr/include/winpr/thread.h b/winpr/include/winpr/thread.h index 97c7eec09..6e61d2855 100644 --- a/winpr/include/winpr/thread.h +++ b/winpr/include/winpr/thread.h @@ -194,16 +194,29 @@ extern "C" #endif /* Thread */ -#define THREAD_MODE_BACKGROUND_BEGIN 0x00010000 -#define THREAD_MODE_BACKGROUND_END 0x00020000 -#define THREAD_PRIORITY_ABOVE_NORMAL 1 -#define THREAD_PRIORITY_BELOW_NORMAL -1 -#define THREAD_PRIORITY_HIGHEST 2 -#define THREAD_PRIORITY_IDLE -15 -#define THREAD_PRIORITY_LOWEST -2 -#define THREAD_PRIORITY_NORMAL 0 -#define THREAD_PRIORITY_TIME_CRITICAL 15 +#define THREAD_MODE_BACKGROUND_BEGIN 0x00010000 /** @since version 3.6.0 */ +#define THREAD_MODE_BACKGROUND_END 0x00020000 /** @since version 3.6.0 */ + /** @defgroup THREAD_PRIORITY + * @since version 3.6.0 + * @{ + */ +#define THREAD_PRIORITY_ABOVE_NORMAL 1 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_BELOW_NORMAL -1 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_HIGHEST 2 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_IDLE -15 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_LOWEST -2 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_NORMAL 0 /** @since version 3.6.0 */ +#define THREAD_PRIORITY_TIME_CRITICAL 15 /** @since version 3.6.0 */ + /** @} */ + + /** @brief Change the thread priority + * + * @param hThread the thhread handle to manipulate + * @param nPriority The priority to set, see @THREAD_PRIORITY + * @return \b TRUE for success, \b FALSE otherwise + * @since version 3.6.0 + */ WINPR_API BOOL SetThreadPriority(HANDLE hThread, int nPriority); #define CREATE_SUSPENDED 0x00000004 diff --git a/winpr/include/winpr/timezone.h b/winpr/include/winpr/timezone.h index 7afbf64f3..77df18b02 100644 --- a/winpr/include/winpr/timezone.h +++ b/winpr/include/winpr/timezone.h @@ -57,9 +57,14 @@ extern "C" } DYNAMIC_TIME_ZONE_INFORMATION, *PDYNAMIC_TIME_ZONE_INFORMATION, *LPDYNAMIC_TIME_ZONE_INFORMATION; +/** @defgroup TIME_ZONE_ID + * @since version 3.6.0 + * @{ + */ #define TIME_ZONE_ID_UNKNOWN 0 #define TIME_ZONE_ID_STANDARD 1 #define TIME_ZONE_ID_DAYLIGHT 2 + /** @} */ WINPR_API DWORD GetTimeZoneInformation(LPTIME_ZONE_INFORMATION lpTimeZoneInformation); WINPR_API BOOL SetTimeZoneInformation(const TIME_ZONE_INFORMATION* lpTimeZoneInformation); diff --git a/winpr/include/winpr/winpr.h b/winpr/include/winpr/winpr.h index 9303c9079..2761dd9e6 100644 --- a/winpr/include/winpr/winpr.h +++ b/winpr/include/winpr/winpr.h @@ -48,12 +48,13 @@ #endif #if defined(__clang__) || defined(__GNUC__) && (__GNUC__ <= 10) -#define WINPR_ATTR_MALLOC(deallocator, ptrindex) __attribute__((malloc, warn_unused_result)) +#define WINPR_ATTR_MALLOC(deallocator, ptrindex) \ + __attribute__((malloc, warn_unused_result)) /** @since version 3.3.0 */ #elif defined(__GNUC__) #define WINPR_ATTR_MALLOC(deallocator, ptrindex) \ - __attribute__((malloc(deallocator, ptrindex), warn_unused_result)) + __attribute__((malloc(deallocator, ptrindex), warn_unused_result)) /** @since version 3.3.0 */ #else -#define WINPR_ATTR_MALLOC(deallocator, ptrindex) +#define WINPR_ATTR_MALLOC(deallocator, ptrindex) /** @since version 3.3.0 */ #endif #if defined(__GNUC__) || defined(__clang__) @@ -120,12 +121,12 @@ #endif #if defined(__GNUC__) || defined(__clang__) -#define WINPR_ALIGN64 __attribute__((aligned(8))) +#define WINPR_ALIGN64 __attribute__((aligned(8))) /** @since version 3.4.0 */ #else #ifdef _WIN32 -#define WINPR_ALIGN64 __declspec(align(8)) +#define WINPR_ALIGN64 __declspec(align(8)) /** @since version 3.4.0 */ #else -#define WINPR_ALIGN64 +#define WINPR_ALIGN64 /** @since version 3.4.0 */ #endif #endif @@ -137,6 +138,13 @@ WINPR_API const char* winpr_get_build_config(void); #define WINPR_UNUSED(x) (void)(x) #if defined(__GNUC__) || defined(__clang__) +/** + * @brief A macro to do dirty casts. Do not use without a good justification! + * @param ptr The pointer to cast + * @param dstType The data type to cast to + * @return The casted pointer + * @since version 3.9.0 + */ #define WINPR_CAST_CONST_PTR_AWAY(ptr, dstType) \ ({ \ union \ @@ -148,6 +156,13 @@ WINPR_API const char* winpr_get_build_config(void); cnv.dst; \ }) +/** + * @brief A macro to do function pointer casts. Do not use without a good justification! + * @param ptr The pointer to cast + * @param dstType The data type to cast to + * @return The casted pointer + * @since version 3.9.0 + */ #define WINPR_FUNC_PTR_CAST(ptr, dstType) \ ({ \ union \ diff --git a/winpr/libwinpr/utils/image.c b/winpr/libwinpr/utils/image.c index 376062dd0..badf432bc 100644 --- a/winpr/libwinpr/utils/image.c +++ b/winpr/libwinpr/utils/image.c @@ -336,6 +336,7 @@ int winpr_bitmap_write_ex(const char* filename, const BYTE* data, size_t stride, if (fwrite(bmpdata, bmpsize, 1, fp) != 1) goto fail; + ret = 0; fail: if (fp) (void)fclose(fp);