diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt index 62caf275d..eea70f636 100644 --- a/include/CMakeLists.txt +++ b/include/CMakeLists.txt @@ -176,6 +176,11 @@ set_property(TARGET freerdp APPEND PROPERTY SOURCES ${PUBLIC_COMMON_HEADERS} ) +add_library(freerdp-headers INTERFACE) +target_sources(freerdp-headers INTERFACE + ${PUBLIC_COMMON_HEADERS} +) + install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/freerdp DESTINATION ${FREERDP_INCLUDE_DIR} FILES_MATCHING PATTERN "*.h") 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/assistance.h b/include/freerdp/assistance.h index f6e9aa9f6..e38e58b77 100644 --- a/include/freerdp/assistance.h +++ b/include/freerdp/assistance.h @@ -31,11 +31,19 @@ extern "C" typedef struct rdp_assistance_file rdpAssistanceFile; + WINPR_ATTR_MALLOC(free, 1) FREERDP_API BYTE* freerdp_assistance_hex_string_to_bin(const void* str, size_t* size); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_assistance_bin_to_hex_string(const void* data, size_t size); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_assistance_generate_pass_stub(DWORD flags); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_assistance_construct_expert_blob(const char* name, const char* pass); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API BYTE* freerdp_assistance_encrypt_pass_stub(const char* password, const char* passStub, size_t* pEncryptedSize); diff --git a/include/freerdp/channels/location.h b/include/freerdp/channels/location.h index f724fbbdc..315475937 100644 --- a/include/freerdp/channels/location.h +++ b/include/freerdp/channels/location.h @@ -24,11 +24,17 @@ #include #include +/** @defgroup channel_location Location Channel + * @brief Location channel providing redirection of client side Network/GPS location to the RDP + * server + * @{ + */ + /** 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 +123,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..e2ebb7995 100644 --- a/include/freerdp/channels/rdpemsc.h +++ b/include/freerdp/channels/rdpemsc.h @@ -20,7 +20,11 @@ #ifndef FREERDP_CHANNEL_RDPEMSC_H #define FREERDP_CHANNEL_RDPEMSC_H -/** \file [MS-RDPEMSC] Mouse Cursor Virtual Channel Extension +/** @defgroup channel_rdpemsc [MS-RDPEMSC] + * @{ + */ + +/** \file @code [MS-RDPEMSC] @endcode Mouse Cursor Virtual Channel Extension * \link * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-rdpemsc/2591b507-cd5a-4537-be29-b45540543dc8 * \since version 3.0.0 @@ -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/audio.h b/include/freerdp/codec/audio.h index f5e5040b2..fd4b1f9bb 100644 --- a/include/freerdp/codec/audio.h +++ b/include/freerdp/codec/audio.h @@ -205,7 +205,7 @@ extern "C" FREERDP_API UINT32 audio_format_compute_time_length(const AUDIO_FORMAT* format, size_t size); - FREERDP_API char* audio_format_get_tag_string(UINT16 wFormatTag); + FREERDP_API const char* audio_format_get_tag_string(UINT16 wFormatTag); FREERDP_API void audio_format_print(wLog* log, DWORD level, const AUDIO_FORMAT* format); FREERDP_API void audio_formats_print(wLog* log, DWORD level, const AUDIO_FORMAT* formats, diff --git a/include/freerdp/codec/color.h b/include/freerdp/codec/color.h index fd9532cad..fbd9f8a87 100644 --- a/include/freerdp/codec/color.h +++ b/include/freerdp/codec/color.h @@ -22,6 +22,7 @@ #ifndef FREERDP_CODEC_COLOR_H #define FREERDP_CODEC_COLOR_H +#include #include #ifdef __cplusplus @@ -38,13 +39,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 +67,10 @@ enum FREERDP_IMAGE_FLAGS * X for alpha channel denotes unused (but existing) alpha channel data. */ +/** @defgroup PIXEL_FORMAT Pixel formats + * @brief PIXEL color ordering formats known + * @{ + */ /* 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 +106,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. @@ -280,6 +288,7 @@ typedef struct gdi_palette gdiPalette; * @return A buffer allocated with winpr_aligned_malloc(width * height, 16) * if successful, NULL otherwise. */ + WINPR_ATTR_MALLOC(winpr_aligned_free, 1) FREERDP_API BYTE* freerdp_glyph_convert(UINT32 width, UINT32 height, const BYTE* WINPR_RESTRICT data); @@ -379,21 +388,25 @@ 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 + /** + * @brief Same as @ref 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 @ref 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..d632d3957 100644 --- a/include/freerdp/crypto/certificate.h +++ b/include/freerdp/crypto/certificate.h @@ -54,35 +54,73 @@ extern "C" FREERDP_API BOOL freerdp_certificate_is_rsa(const rdpCertificate* certificate); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_hash(const rdpCertificate* certificate, const char* hash, size_t* plength); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_fingerprint_by_hash(const rdpCertificate* certificate, const char* hash); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_fingerprint_by_hash_ex(const rdpCertificate* certificate, const char* hash, BOOL separator); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_fingerprint(const rdpCertificate* certificate); + + WINPR_ATTR_MALLOC(free, 1) 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 + */ + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_pem_ex(const rdpCertificate* certificate, size_t* pLength, BOOL withCertChain); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API BYTE* freerdp_certificate_get_der(const rdpCertificate* certificate, size_t* pLength); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_subject(const rdpCertificate* certificate); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_issuer(const rdpCertificate* certificate); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_upn(const rdpCertificate* certificate); + + WINPR_ATTR_MALLOC(free, 1) 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 + */ + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_validity(const rdpCertificate* certificate, BOOL startDate); FREERDP_API WINPR_MD_TYPE freerdp_certificate_get_signature_alg(const rdpCertificate* cert); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_common_name(const rdpCertificate* cert, size_t* plength); + + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char** freerdp_certificate_get_dns_names(const rdpCertificate* cert, size_t* pcount, size_t** pplengths); FREERDP_API void freerdp_certificate_free_dns_names(size_t count, size_t* lengths, @@ -98,6 +136,7 @@ extern "C" FREERDP_API BOOL freerdp_certificate_is_rdp_security_compatible(const rdpCertificate* cert); + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_certificate_get_param(const rdpCertificate* cert, enum FREERDP_CERT_PARAM what, size_t* psize); 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..43b0b1883 100644 --- a/include/freerdp/locale/locale.h +++ b/include/freerdp/locale/locale.h @@ -30,6 +30,9 @@ #include #include +/** @defgroup keyboard-identifiers Keyboard Layout 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 @ref 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 @ref keyboard-identifiers for a provided locale + * @param locale The locale to query + * @return The @ref 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..ed73a702f 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 @ref 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 @ref 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 @ref 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..73f770706 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 Proxy Configuration + * @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 */ }; /** @@ -121,6 +126,13 @@ extern "C" */ FREERDP_API BOOL pf_server_config_dump(const char* file); + /** + * @brief pf_server_config_free Releases all resources associated with proxyConfig + * + * @param config A pointer to the proxyConfig to clean up. Might be NULL. + */ + FREERDP_API void pf_server_config_free(proxyConfig* config); + /** * @brief server_config_load_ini Create a proxyConfig from a already loaded * INI file. @@ -129,6 +141,7 @@ extern "C" * * @return A proxyConfig or NULL in case of failure. */ + WINPR_ATTR_MALLOC(pf_server_config_free, 1) FREERDP_API proxyConfig* server_config_load_ini(wIniFile* ini); /** * @brief pf_server_config_load_file Create a proxyConfig from a INI file found at path. @@ -137,6 +150,7 @@ extern "C" * * @return A proxyConfig or NULL in case of failure. */ + WINPR_ATTR_MALLOC(pf_server_config_free, 1) FREERDP_API proxyConfig* pf_server_config_load_file(const char* path); /** @@ -147,6 +161,7 @@ extern "C" * * @return A proxyConfig or NULL in case of failure. */ + WINPR_ATTR_MALLOC(pf_server_config_free, 1) FREERDP_API proxyConfig* pf_server_config_load_buffer(const char* buffer); /** @@ -156,13 +171,6 @@ extern "C" */ FREERDP_API void pf_server_config_print(const proxyConfig* config); - /** - * @brief pf_server_config_free Releases all resources associated with proxyConfig - * - * @param config A pointer to the proxyConfig to clean up. Might be NULL. - */ - FREERDP_API void pf_server_config_free(proxyConfig* config); - /** * @brief pf_config_required_plugins_count * @@ -232,4 +240,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..9088135ad 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 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 @@ -78,6 +80,12 @@ typedef struct rdp_settings rdpSettings; #define FREERDP_SETTINGS_SERVER_MODE 0x00000001 #define FREERDP_SETTINGS_REMOTE_MODE 0x00000002 + /** \brief Free a settings struct with all data in it + * + * \param settings A pointer to the settings to free, May be NULL + */ + FREERDP_API void freerdp_settings_free(rdpSettings* settings); + /** \brief creates a new setting struct * * \param flags Flags for creation, use \b FREERDP_SETTINGS_SERVER_MODE for server settings, 0 @@ -85,6 +93,7 @@ typedef struct rdp_settings rdpSettings; * * \return A newly allocated settings struct or NULL */ + WINPR_ATTR_MALLOC(freerdp_settings_free, 1) FREERDP_API rdpSettings* freerdp_settings_new(DWORD flags); /** \brief Creates a deep copy of settings @@ -93,6 +102,7 @@ typedef struct rdp_settings rdpSettings; * * \return A newly allocated copy of \b settings or NULL */ + WINPR_ATTR_MALLOC(freerdp_settings_free, 1) FREERDP_API rdpSettings* freerdp_settings_clone(const rdpSettings* settings); /** \brief Deep copies settings from \b src to \b dst @@ -120,12 +130,6 @@ typedef struct rdp_settings rdpSettings; FREERDP_API BOOL freerdp_settings_copy_item(rdpSettings* dst, const rdpSettings* src, SSIZE_T id); - /** \brief Free a settings struct with all data in it - * - * \param settings A pointer to the settings to free, May be NULL - */ - FREERDP_API void freerdp_settings_free(rdpSettings* settings); - /** \brief Dumps the contents of a settings struct to a WLog logger * * \param log The logger to write to, must not be NULL @@ -146,10 +150,14 @@ typedef struct rdp_settings rdpSettings; FREERDP_API BOOL freerdp_settings_print_diff(wLog* log, DWORD level, const rdpSettings* src, const rdpSettings* other); - FREERDP_API ADDIN_ARGV* freerdp_addin_argv_new(size_t argc, const char* argv[]); - FREERDP_API ADDIN_ARGV* freerdp_addin_argv_clone(const ADDIN_ARGV* args); FREERDP_API void freerdp_addin_argv_free(ADDIN_ARGV* args); + WINPR_ATTR_MALLOC(freerdp_addin_argv_free, 1) + FREERDP_API ADDIN_ARGV* freerdp_addin_argv_new(size_t argc, const char* argv[]); + + WINPR_ATTR_MALLOC(freerdp_addin_argv_free, 1) + FREERDP_API ADDIN_ARGV* freerdp_addin_argv_clone(const ADDIN_ARGV* args); + FREERDP_API BOOL freerdp_addin_argv_add_argument(ADDIN_ARGV* args, const char* argument); FREERDP_API BOOL freerdp_addin_argv_add_argument_ex(ADDIN_ARGV* args, const char* argument, size_t len); @@ -171,6 +179,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, @@ -480,7 +490,8 @@ typedef struct rdp_settings rdpSettings; const char* param); /** \brief appends a string to a settings value. The \b param is copied. - * If the initial value of the setting was not empty, is created + * If the initial value of the setting was not empty, @code + * @endcode is created * * \param settings A pointer to the settings to query, must not be NULL. * \param id The key to query @@ -682,8 +693,8 @@ typedef struct rdp_settings rdpSettings; * * \return A pointer to \b buffer for success, NULL otherwise */ - FREERDP_API char* freerdp_rail_support_flags_to_string(UINT32 flags, char* buffer, - size_t length); + FREERDP_API const char* freerdp_rail_support_flags_to_string(UINT32 flags, char* buffer, + size_t length); /** \brief Returns a stringified representation of the RDP protocol version. * @@ -714,11 +725,16 @@ 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 */ + WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_settings_get_config_path(void); #ifdef __cplusplus } #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..1e9de38dc 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 user defined context passed by @ref freerdp_set_io_callback_context + * @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 user defined context passed by @ref freerdp_set_io_callback_context + * @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,28 @@ extern "C" typedef SSIZE_T (*pTransportRead)(rdpTransport* transport, BYTE* data, size_t bytes); typedef BOOL (*pTransportGetPublicKey)(rdpTransport* transport, const BYTE** data, DWORD* length); + /** + * @brief Mofify transport behaviour between bocking and non blocking operation + * + * @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 layer the transport layer to attach + * + * @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 +112,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 +139,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/aad.h b/include/freerdp/utils/aad.h index 1c69a3fc9..06ae2c16e 100644 --- a/include/freerdp/utils/aad.h +++ b/include/freerdp/utils/aad.h @@ -21,7 +21,7 @@ #ifndef FREERDP_UTILS_AAD_H #define FREERDP_UTILS_AAD_H -/** \file AAD related helper utilities +/** \defgroup AAD AAD related helper utilities * \since version 3.0.0 */ #include @@ -40,6 +40,7 @@ * * @return The token string or \b NULL */ +WINPR_ATTR_MALLOC(free, 1) FREERDP_API char* freerdp_utils_aad_get_access_token(wLog* log, const char* data, size_t length); #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/include/freerdp/utils/http.h b/include/freerdp/utils/http.h index 9719402df..b2e643ebf 100644 --- a/include/freerdp/utils/http.h +++ b/include/freerdp/utils/http.h @@ -70,6 +70,6 @@ FREERDP_API BOOL freerdp_http_request(const char* url, const char* body, long* s BYTE** response, size_t* response_length); FREERDP_API const char* freerdp_http_status_string(long status); -FREERDP_API char* freerdp_http_status_string_format(long status, char* buffer, size_t size); +FREERDP_API const char* freerdp_http_status_string_format(long status, char* buffer, size_t size); #endif /* FREERDP_UTILS_HTTP_H */ diff --git a/include/freerdp/utils/passphrase.h b/include/freerdp/utils/passphrase.h index f6a0f9605..0bcce1953 100644 --- a/include/freerdp/utils/passphrase.h +++ b/include/freerdp/utils/passphrase.h @@ -34,8 +34,8 @@ extern "C" FREERDP_API int freerdp_interruptible_getc(rdpContext* context, FILE* file); FREERDP_API SSIZE_T freerdp_interruptible_get_line(rdpContext* context, char** lineptr, size_t* size, FILE* stream); - FREERDP_API char* freerdp_passphrase_read(rdpContext* context, const char* prompt, char* buf, - size_t bufsiz, int from_stdin); + FREERDP_API const char* freerdp_passphrase_read(rdpContext* context, const char* prompt, + char* buf, size_t bufsiz, int from_stdin); #ifdef __cplusplus } diff --git a/include/freerdp/utils/string.h b/include/freerdp/utils/string.h index c0083684f..1268360a0 100644 --- a/include/freerdp/utils/string.h +++ b/include/freerdp/utils/string.h @@ -30,8 +30,10 @@ extern "C" { #endif - FREERDP_API char* rdp_redirection_flags_to_string(UINT32 flags, char* buffer, size_t size); - FREERDP_API char* rdp_cluster_info_flags_to_string(UINT32 flags, char* buffer, size_t size); + FREERDP_API const char* rdp_redirection_flags_to_string(UINT32 flags, char* buffer, + size_t size); + FREERDP_API const char* rdp_cluster_info_flags_to_string(UINT32 flags, char* buffer, + size_t size); #ifdef __cplusplus } diff --git a/libfreerdp/codec/audio.c b/libfreerdp/codec/audio.c index 3791fd81a..b59837803 100644 --- a/libfreerdp/codec/audio.c +++ b/libfreerdp/codec/audio.c @@ -75,7 +75,7 @@ UINT32 audio_format_compute_time_length(const AUDIO_FORMAT* format, size_t size) return mstime; } -char* audio_format_get_tag_string(UINT16 wFormatTag) +const char* audio_format_get_tag_string(UINT16 wFormatTag) { switch (wFormatTag) { diff --git a/libfreerdp/common/settings.c b/libfreerdp/common/settings.c index ef79a1c73..327ad2efb 100644 --- a/libfreerdp/common/settings.c +++ b/libfreerdp/common/settings.c @@ -1948,7 +1948,7 @@ BOOL freerdp_device_equal(const RDPDR_DEVICE* what, const RDPDR_DEVICE* expect) return TRUE; } -char* freerdp_rail_support_flags_to_string(UINT32 flags, char* buffer, size_t length) +const char* freerdp_rail_support_flags_to_string(UINT32 flags, char* buffer, size_t length) { const UINT32 mask = RAIL_LEVEL_SUPPORTED | RAIL_LEVEL_DOCKED_LANGBAR_SUPPORTED | diff --git a/libfreerdp/core/gateway/arm.c b/libfreerdp/core/gateway/arm.c index 09bd7e134..7b023d518 100644 --- a/libfreerdp/core/gateway/arm.c +++ b/libfreerdp/core/gateway/arm.c @@ -323,12 +323,14 @@ arm_create_cleanup: } /** - * treats the redirectedAuthBlob + * @brief treats the redirectedAuthBlob * * sample pbInput: + * @code * 41004500530000004b44424d01000000200000006ee71b295810b3fd13799da3825d0efa3a628e8f4a6eda609ffa975408556546 * 'A\x00E\x00S\x00\x00\x00KDBM\x01\x00\x00\x00 * \x00\x00\x00n\xe7\x1b)X\x10\xb3\xfd\x13y\x9d\xa3\x82]\x0e\xfa:b\x8e\x8fJn\xda`\x9f\xfa\x97T\x08UeF' + * @endcode * * @param pbInput the raw auth blob (base64 and utf16 decoded) * @param cbInput size of pbInput diff --git a/libfreerdp/crypto/certificate.h b/libfreerdp/crypto/certificate.h index ead71f8ee..57c0dcb85 100644 --- a/libfreerdp/crypto/certificate.h +++ b/libfreerdp/crypto/certificate.h @@ -49,6 +49,7 @@ FREERDP_LOCAL BOOL freerdp_certificate_read_server_cert(rdpCertificate* certific FREERDP_LOCAL SSIZE_T freerdp_certificate_write_server_cert(const rdpCertificate* certificate, UINT32 dwVersion, wStream* s); +WINPR_ATTR_MALLOC(freerdp_certificate_free, 1) FREERDP_LOCAL rdpCertificate* freerdp_certificate_clone(const rdpCertificate* certificate); FREERDP_LOCAL const rdpCertInfo* freerdp_certificate_get_info(const rdpCertificate* certificate); diff --git a/libfreerdp/gdi/drawing.c b/libfreerdp/gdi/drawing.c index d4e241c13..750c878a6 100644 --- a/libfreerdp/gdi/drawing.c +++ b/libfreerdp/gdi/drawing.c @@ -99,7 +99,7 @@ UINT32 gdi_SetBkColor(HGDI_DC hdc, UINT32 crColor) } /** - * @brief Get the current background mode.\n + * @brief Get the current background mode. * msdn{dd144853} * * @param hdc device context @@ -113,7 +113,7 @@ UINT32 gdi_GetBkMode(HGDI_DC hdc) } /** - * @brief Set the current background mode.\n + * @brief Set the current background mode. * msdn{dd162965} * * @param hdc device context diff --git a/libfreerdp/utils/http.c b/libfreerdp/utils/http.c index 0f50823b8..aa14677a9 100644 --- a/libfreerdp/utils/http.c +++ b/libfreerdp/utils/http.c @@ -384,7 +384,7 @@ const char* freerdp_http_status_string(long status) } } -char* freerdp_http_status_string_format(long status, char* buffer, size_t size) +const char* freerdp_http_status_string_format(long status, char* buffer, size_t size) { const char* code = freerdp_http_status_string(status); (void)_snprintf(buffer, size, "%s [%ld]", code, status); diff --git a/libfreerdp/utils/passphrase.c b/libfreerdp/utils/passphrase.c index 2328b8b18..0388fba59 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 }; @@ -213,8 +213,8 @@ error: } } -static char* freerdp_passphrase_read_askpass(const char* prompt, char* buf, size_t bufsiz, - char const* askpass_env) +static const char* freerdp_passphrase_read_askpass(const char* prompt, char* buf, size_t bufsiz, + char const* askpass_env) { char command[4096] = { 0 }; @@ -234,8 +234,8 @@ static char* freerdp_passphrase_read_askpass(const char* prompt, char* buf, size return buf; } -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) { const char* askpass_env = getenv("FREERDP_ASKPASS"); @@ -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/libfreerdp/utils/string.c b/libfreerdp/utils/string.c index 4e520ea1d..2b5826f0b 100644 --- a/libfreerdp/utils/string.c +++ b/libfreerdp/utils/string.c @@ -22,7 +22,7 @@ #include #include -char* rdp_redirection_flags_to_string(UINT32 flags, char* buffer, size_t size) +const char* rdp_redirection_flags_to_string(UINT32 flags, char* buffer, size_t size) { struct map_t { @@ -60,7 +60,7 @@ char* rdp_redirection_flags_to_string(UINT32 flags, char* buffer, size_t size) return buffer; } -char* rdp_cluster_info_flags_to_string(UINT32 flags, char* buffer, size_t size) +const char* rdp_cluster_info_flags_to_string(UINT32 flags, char* buffer, size_t size) { const UINT32 version = (flags & ServerSessionRedirectionVersionMask) >> 2; if (flags & REDIRECTION_SUPPORTED) diff --git a/winpr/include/CMakeLists.txt b/winpr/include/CMakeLists.txt index 5dc488581..c9b7459e4 100644 --- a/winpr/include/CMakeLists.txt +++ b/winpr/include/CMakeLists.txt @@ -47,6 +47,11 @@ if (WITH_WINPR_TOOLS) ) endif() +add_library(winpr-headers INTERFACE) +target_sources(winpr-headers INTERFACE + ${WINPR_PUBLIC_COMMON_HEADERS} +) + install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/ DESTINATION ${WINPR_INCLUDE_DIR} FILES_MATCHING PATTERN "*.h") 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..b502b3f6e 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 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 height 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 @ref 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 @ref 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 @ref 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 @ref 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 @ref 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..830c86310 100644 --- a/winpr/include/winpr/json.h +++ b/winpr/include/winpr/json.h @@ -25,6 +25,12 @@ #include #include +/** @defgroup WINPR_JSON WinPR JSON wrapper + * @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 @ref 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 @ref 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 @ref 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 @ref 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 @ref 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 @ref 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 @ref 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 @ref 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..2c46e37cf 100644 --- a/winpr/include/winpr/thread.h +++ b/winpr/include/winpr/thread.h @@ -194,16 +194,31 @@ 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 THREAD_PRIORITY + * @brief Known THREAD_PRIORITY values + * @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 @ref 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..4f9d41418 100644 --- a/winpr/include/winpr/timezone.h +++ b/winpr/include/winpr/timezone.h @@ -57,9 +57,15 @@ extern "C" } DYNAMIC_TIME_ZONE_INFORMATION, *PDYNAMIC_TIME_ZONE_INFORMATION, *LPDYNAMIC_TIME_ZONE_INFORMATION; +/** @defgroup TIME_ZONE_ID TIME_ZONE_ID + * @brief Known values of 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);