From 85ad07ece55cbfa40ab7538e89c7adf079443f53 Mon Sep 17 00:00:00 2001 From: Simon Rozman Date: Wed, 2 Nov 2016 00:16:33 +0100 Subject: [PATCH] Doxygen documentation updated & some minor issues stumbled upon fixed --- Doxyfile | 2 +- README.md | 12 +- include/WinStd/Base64.h | 41 +- include/WinStd/COM.h | 108 ++-- include/WinStd/Common.h | 660 ++++++++++++---------- include/WinStd/Cred.h | 49 +- include/WinStd/Crypt.h | 1150 +++++++++++++++++++-------------------- include/WinStd/EAP.h | 151 ++--- include/WinStd/ETW.h | 93 ++-- include/WinStd/Hex.h | 31 +- include/WinStd/MSI.h | 40 +- include/WinStd/Sec.h | 78 ++- include/WinStd/Shell.h | 15 +- include/WinStd/WLAN.h | 41 +- include/WinStd/Win.h | 197 +++---- src/Base64.cpp | 4 + src/EAP.cpp | 4 + src/Win.cpp | 4 +- 18 files changed, 1373 insertions(+), 1307 deletions(-) diff --git a/Doxyfile b/Doxyfile index c4ae370a..c14c60de 100644 --- a/Doxyfile +++ b/Doxyfile @@ -694,7 +694,7 @@ CITE_BIB_FILES = # messages are off. # The default value is: NO. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES diff --git a/README.md b/README.md index a767200f..c1e7d47d 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,15 @@ Provides additional templates and function helpers for Windows API using Standard C++ ##Building -- The _.h_ files can be used individually. However, we do encourage you to include the entire library project and reference it in dependant projects of your solution, as WinStd might develop some non-inline code over time. -- The _WinStd.vcxproj_ requires Microsoft Visual Studio 2010 SP1 and _..\\..\\include_ folder with _common.props_, _Debug.props_, _Release.props_, _Win32.props_, and _x64.props_ files to customize building process for individual applications. +- The `.h` files can be used individually. However, we do encourage you to include the entire library project and reference it in dependant projects of your solution, as WinStd might develop some non-inline code over time. +- The `WinStd.vcxproj` requires Microsoft Visual Studio 2010 SP1 and `..\..\include` folder with `common.props`, `Debug.props`, `Release.props`, `Win32.props`, and `x64.props` files to customize building process for individual applications. ##Usage 1. Clone the repository into your solution folder. -2. Add the _WinStd.vcxproj_ to your solution. -3. Add WinStd's _include_ folder to _Additional Include Directories_ in your project's C/C++ settings. +2. Add the `WinStd.vcxproj` to your solution. +3. Add WinStd's `include` folder to _Additional Include Directories_ in your project's C/C++ settings. 4. Add a new reference to WinStd project from your project's common properties. -5. Include _.h_ files from WinStd as needed: +5. Include `.h` files from WinStd as needed: ```C #include #include @@ -25,7 +25,7 @@ void main() ``` ##Debugging -For user friendlier display of variables of WinStd types in Visual Studio 2010 debugger, find the file _autoexp.dat_ in your _C:\Program Files (x86)\Microsoft Visual Studio 2010_ and open it with Notepad. +For user friendlier display of variables of WinStd types in Visual Studio 2010 debugger, find the file `autoexp.dat` in your `C:\Program Files (x86)\Microsoft Visual Studio 2010` and open it with Notepad. Locate the `[AutoExpand]` section and add the following lines: ``` winstd::variant=$BUILTIN(VARIANT) diff --git a/include/WinStd/Base64.h b/include/WinStd/Base64.h index 7392fa6e..1f06900a 100644 --- a/include/WinStd/Base64.h +++ b/include/WinStd/Base64.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdBase64 Base64 conversion +/// Provides Base64 conversion for WinStd classes +/// + #include "Common.h" #include @@ -25,23 +30,8 @@ namespace winstd { - /// - /// \defgroup WinStdBase64 Base64 conversion - /// Provides Base64 conversion for WinStd classes - /// - /// @{ - - /// - /// Base64 encoding session - /// class WINSTD_API base64_enc; - - /// - /// Base64 decoding session - /// class WINSTD_API base64_dec; - - /// @} } #pragma once @@ -49,6 +39,12 @@ namespace winstd namespace winstd { + /// \addtogroup WinStdBase64 + /// @{ + + /// + /// Base64 encoding session + /// class WINSTD_API base64_enc { public: @@ -167,10 +163,16 @@ namespace winstd protected: unsigned char buf[3]; ///< Internal buffer size_t num; ///< Number of bytes used in `buf` - static const char lookup[64]; ///< Look-up table + + /// \cond internal + static const char lookup[64]; + /// \endcond }; + /// + /// Base64 decoding session + /// class WINSTD_API base64_dec { public: @@ -268,6 +270,11 @@ namespace winstd protected: unsigned char buf[4]; ///< Internal buffer size_t num; ///< Number of bytes used in `buf` - static const unsigned char lookup[256]; ///< Look-up table + + /// \cond internal + static const unsigned char lookup[256]; + /// \endcond }; + + /// @} } diff --git a/include/WinStd/COM.h b/include/WinStd/COM.h index 5ddca211..775650da 100644 --- a/include/WinStd/COM.h +++ b/include/WinStd/COM.h @@ -18,51 +18,22 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdCOM COM object management +/// Provides helper templates for Windows COM object manipulation +/// + #include "Common.h" #include namespace winstd { - /// - /// \defgroup WinStdCOM COM object management - /// Provides helper templates for Windows COM object manipulation - /// - /// @{ - - /// - /// COM object wrapper template - /// template class com_obj; - - /// - /// BSTR string wrapper - /// class WINSTD_API bstr; - - /// - /// VARIANT struct wrapper - /// class WINSTD_API variant; - - /// @} - class WINSTD_API com_initializer; - - /// - /// \defgroup WinStdExceptions Exceptions - /// Additional exceptions - /// - /// @{ - - /// - /// COM runtime error - /// - /// \note Must be defined as derived class from num_runtime_error<> to allow correct type info for dynamic typecasting and prevent folding with other derivates of num_runtime_error<>. - /// class WINSTD_API com_runtime_error; - - /// @} } #pragma once @@ -70,6 +41,12 @@ namespace winstd namespace winstd { + /// \addtogroup WinStdCOM + /// @{ + + /// + /// COM object wrapper template + /// template class com_obj : public dplhandle { @@ -144,7 +121,9 @@ namespace winstd protected: /// - /// Releases the object. + /// Releases the object by decrementing reference counter + /// + /// \sa [IUnknown::Release method](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682317.aspx) /// virtual void free_internal() { @@ -153,7 +132,9 @@ namespace winstd /// - /// Duplicates the object. + /// Duplicates the object by incrementing the reference counter + /// + /// \sa [IUnknown::AddRef method](https://msdn.microsoft.com/en-us/library/windows/desktop/ms691379.aspx) /// /// \param[in] h Object handle of existing object /// @@ -167,6 +148,9 @@ namespace winstd }; + /// + /// BSTR string wrapper + /// class WINSTD_API bstr : public dplhandle { DPLHANDLE_IMPL(bstr) @@ -235,6 +219,9 @@ namespace winstd }; + /// + /// VARIANT struct wrapper + /// class WINSTD_API variant : public VARIANT { public: @@ -924,6 +911,32 @@ namespace winstd return compare(static_cast(*this), varSrc, LOCALE_USER_DEFAULT, 0)== static_cast(VARCMP_GT); } + /// + /// Is variant less than or equal to? + /// + /// \param[in] varSrc Variant to compare against + /// \return + /// - Non zero when variant is less than or equal to \p varSrc; + /// - Zero otherwise. + /// + inline bool operator<=(_In_ const VARIANT& varSrc) const + { + return !operator>(varSrc); + } + + /// + /// Is variant greater than or equal to? + /// + /// \param[in] varSrc Variant to compare against + /// \return + /// - Non zero when variant is greater than or equal to \p varSrc; + /// - Zero otherwise. + /// + inline bool operator>=(_In_ const VARIANT& varSrc) const + { + return !operator<(varSrc); + } + /// /// Converts a variant from one type to another. /// @@ -935,6 +948,7 @@ namespace winstd } private: + /// \cond internal inline HRESULT compare(_In_ const VARIANT &varLeft, _In_ const VARIANT &varRight, _In_ LCID lcid, _In_ ULONG dwFlags) const { switch(vt) { @@ -945,9 +959,13 @@ namespace winstd default: return VarCmp(const_cast(&varLeft), const_cast(&varRight), lcid, dwFlags); } } + /// \endcond }; + /// + /// Context scope automatic COM (un)initialization + /// class WINSTD_API com_initializer { public: @@ -995,15 +1013,27 @@ namespace winstd HRESULT m_result; ///< Result of CoInitialize call }; + /// @} + /// + /// \defgroup WinStdExceptions Exceptions + /// Additional exceptions + /// + /// @{ + + /// + /// COM runtime error + /// + /// \note Must be defined as derived class from num_runtime_error<> to allow correct type info for dynamic typecasting and prevent folding with other derivates of num_runtime_error<>. + /// class WINSTD_API com_runtime_error : public num_runtime_error { public: /// /// Constructs an exception /// - /// \param[in] error COM error code - /// \param[in] msg Error message + /// \param[in] num COM error code + /// \param[in] msg Error message /// inline com_runtime_error(_In_ error_type num, _In_ const std::string& msg) : num_runtime_error(num, msg.c_str()) { @@ -1030,4 +1060,6 @@ namespace winstd { } }; + + /// @} } diff --git a/include/WinStd/Common.h b/include/WinStd/Common.h index 7ca09989..5b548c5e 100644 --- a/include/WinStd/Common.h +++ b/include/WinStd/Common.h @@ -18,6 +18,41 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdGeneral General +/// General API +/// +/// \defgroup WinStdSysHandles System Handles +/// Simplifies work with object handles of various type +/// +/// \defgroup WinStdExceptions Exceptions +/// Additional exceptions +/// +/// \defgroup WinStdStrFormat String Formatting +/// Formatted string generation +/// +/// \par Example +/// \code +/// // Please note the PCSTR typecasting invokes an operator to return +/// // pointer to formatted buffer rather than class reference itself. +/// cout << (PCSTR)(winstd::string_printf("%i is less than %i.\n", 1, 5)); +/// \endcode +/// +/// \defgroup WinStdMemSanitize Auto-sanitize Memory Management +/// Sanitizes memory before dismissed +/// + +#include + +#include + +#include +#include +#include + +/// \addtogroup WinStdGeneral +/// @{ + /// /// Public function calling convention /// @@ -31,19 +66,45 @@ #endif #endif +/// +/// Class/struct with no virtual table declaration +/// +/// Use for storing flat data. +/// +/// This macro bypasses Doxygen limitation to parse class/struct declarations with parentheses. +/// +#define WINSTD_NOVTABLE __declspec(novtable) + +/// +/// "L" stringizing macro +/// #ifndef __L #define __L(x) L ## x #endif + +/// +/// Makes string Unicode +/// #ifndef _L #define _L(x) __L(x) #endif -// Macros for building default constructors and operators to prevent their auto-generation by compiler. +/// +/// Declares a class as non-copyable +/// #define WINSTD_NONCOPYABLE(C) \ private: \ inline C (_In_ const C &h); \ inline C& operator=(_In_ const C &h); +/// @} + +/// \addtogroup WinStdSysHandles +/// @{ + +/// +/// Implements default constructors and operators to prevent their auto-generation by compiler. +/// #define HANDLE_IMPL(C) \ public: \ inline C ( ) { } \ @@ -53,6 +114,9 @@ public: \ inline C& operator=(_Inout_ C &&h) { handle::operator=(std::move(h)); return *this; } \ WINSTD_NONCOPYABLE(C) +/// +/// Implements default constructors and operators to prevent their auto-generation by compiler. +/// #define DPLHANDLE_IMPL(C) \ public: \ inline C ( ) { } \ @@ -64,15 +128,153 @@ public: \ inline C& operator=(_Inout_ C &&h) { dplhandle::operator=(std::move(h)); return *this; } \ private: -#include +/// @} -#include +namespace winstd +{ + /// \addtogroup WinStdStrFormat + /// @{ -#include -#include -#include + /// + /// Multi-byte / Wide-character string (according to _UNICODE) + /// +#ifdef _UNICODE + typedef std::wstring tstring; +#else + typedef std::string tstring; +#endif + /// @} + + template struct LocalFree_delete; + template struct LocalFree_delete<_Ty[]>; + template class handle; + template class dplhandle; + template class vector_queue; + template class num_runtime_error; + class WINSTD_API win_runtime_error; + + /// \addtogroup WinStdStrFormat + /// @{ + + template, class _Ax = std::allocator<_Elem> > class basic_string_printf; + + /// + /// Single-byte character implementation of a class to support string formatting using `printf()` style templates + /// + typedef basic_string_printf, std::allocator > string_printf; + + /// + /// Wide character implementation of a class to support string formatting using `printf()` style templates + /// + typedef basic_string_printf, std::allocator > wstring_printf; + + /// + /// Multi-byte / Wide-character formatted string (according to _UNICODE) + /// +#ifdef _UNICODE + typedef wstring_printf tstring_printf; +#else + typedef string_printf tstring_printf; +#endif + + template, class _Ax = std::allocator<_Elem> > class basic_string_msg; + + /// + /// Single-byte character implementation of a class to support string formatting using `FormatMessage()` style templates + /// + typedef basic_string_msg, std::allocator > string_msg; + + /// + /// Wide character implementation of a class to support string formatting using `FormatMessage()` style templates + /// + typedef basic_string_msg, std::allocator > wstring_msg; + + /// + /// Multi-byte / Wide-character formatted string (according to _UNICODE) + /// +#ifdef _UNICODE + typedef wstring_msg tstring_msg; +#else + typedef string_msg tstring_msg; +#endif + + template, class _Ax = std::allocator<_Elem> > class basic_string_guid; + + class WINSTD_API string_guid; + class WINSTD_API wstring_guid; + + /// + /// Multi-byte / Wide-character string GUID (according to _UNICODE) + /// +#ifdef _UNICODE + typedef wstring_guid tstring_guid; +#else + typedef string_guid tstring_guid; +#endif + + /// @} + + /// \addtogroup WinStdMemSanitize + /// @{ + + template class sanitizing_allocator; + + /// + /// A sanitizing variant of std::string + /// + /// \note + /// `sanitizing_string` introduces a performance penalty. However, it provides an additional level of security. + /// Use for security sensitive data memory storage only. + /// + typedef std::basic_string, sanitizing_allocator > sanitizing_string; + + /// + /// A sanitizing variant of std::wstring + /// + /// \note + /// `sanitizing_wstring` introduces a performance penalty. However, it provides an additional level of security. + /// Use for security sensitive data memory storage only. + /// + typedef std::basic_string, sanitizing_allocator > sanitizing_wstring; + + /// + /// Multi-byte / Wide-character sanitizing string (according to _UNICODE) + /// +#ifdef _UNICODE + typedef sanitizing_wstring sanitizing_tstring; +#else + typedef sanitizing_string sanitizing_tstring; +#endif + + /// @} +} + +/// \addtogroup WinStdStrFormat +/// @{ + +/// +/// Formats string using `printf()`. +/// +/// \param[out] str Buffer to receive string +/// \param[in ] capacity Size of `str` in characters +/// \param[in ] format String template using `printf()` style +/// \param[in ] arg Arguments to `format` +/// +/// \returns Number of characters in result. +/// inline int vsnprintf(_Out_z_cap_(capacity) char *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const char *format, _In_ va_list arg); + +/// +/// Formats string using `printf()`. +/// +/// \param[out] str Buffer to receive string +/// \param[in ] capacity Size of `str` in characters +/// \param[in ] format String template using `printf()` style +/// \param[in ] arg Arguments to `format` +/// +/// \returns Number of characters in result. +/// inline int vsnprintf(_Out_z_cap_(capacity) wchar_t *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const wchar_t *format, _In_ va_list arg); /// @@ -110,198 +312,7 @@ template inline DWORD FormatMessage(_In_ DWORD dwFlags /// template inline DWORD FormatMessage(_In_ DWORD dwFlags, _In_opt_ LPCVOID lpSource, _In_ DWORD dwMessageId, _In_ DWORD dwLanguageId, _Out_ std::basic_string &str, _In_opt_ va_list *Arguments); -namespace winstd -{ - /// - /// Multi-byte / Wide-character string (according to _UNICODE) - /// -#ifdef _UNICODE - typedef std::wstring tstring; -#else - typedef std::string tstring; -#endif - - /// - /// Deleter for unique_ptr using LocalFree - /// - template struct LocalFree_delete; - - /// - /// Deleter for unique_ptr to array of unknown size using LocalFree - /// - template struct LocalFree_delete<_Ty[]>; - - /// - /// \defgroup WinStdSysHandles System Handles - /// Simplifies work with object handles of various type - /// - /// @{ - - /// - /// Base abstract template class to support generic object handle keeping - /// - /// It provides basic operators and methods common to all descendands of this class establishing a base to ease the replacement of native object handle type with classes in object-oriented approach. - /// - template class handle; - - /// - /// Base abstract template class to support object handle keeping for objects that support handle duplication - /// - template class dplhandle; - - /// - /// Helper class to allow limited size FIFO queues implemented as vector of elements - /// - template class vector_queue; - - /// - /// \defgroup WinStdExceptions Exceptions - /// Additional exceptions - /// - /// @{ - - /// - /// Numerical runtime error - /// - template class num_runtime_error; - - /// - /// Windows runtime error - /// - class WINSTD_API win_runtime_error; - - /// @} - - /// - /// \defgroup WinStdStrFormat String Formatting - /// Formatted string generation - /// - /// \par Example - /// \code - /// // Please note the PCSTR typecasting invokes an operator to return - /// // pointer to formatted buffer rather than class reference itself. - /// cout << (PCSTR)(winstd::string_printf("%i is less than %i.\n", 1, 5)); - /// \endcode - /// - /// @{ - - /// - /// Base template class to support string formatting using `printf()` style templates - /// - template, class _Ax = std::allocator<_Elem> > class basic_string_printf; - - /// - /// Single-byte character implementation of a class to support string formatting using `printf()` style templates - /// - typedef basic_string_printf, std::allocator > string_printf; - - /// - /// Wide character implementation of a class to support string formatting using `printf()` style templates - /// - typedef basic_string_printf, std::allocator > wstring_printf; - - /// - /// Multi-byte / Wide-character formatted string (according to _UNICODE) - /// -#ifdef _UNICODE - typedef wstring_printf tstring_printf; -#else - typedef string_printf tstring_printf; -#endif - - /// - /// Base template class to support string formatting using `FormatMessage()` style templates - /// - template, class _Ax = std::allocator<_Elem> > class basic_string_msg; - - /// - /// Single-byte character implementation of a class to support string formatting using `FormatMessage()` style templates - /// - typedef basic_string_msg, std::allocator > string_msg; - - /// - /// Wide character implementation of a class to support string formatting using `FormatMessage()` style templates - /// - typedef basic_string_msg, std::allocator > wstring_msg; - - /// - /// Multi-byte / Wide-character formatted string (according to _UNICODE) - /// -#ifdef _UNICODE - typedef wstring_msg tstring_msg; -#else - typedef string_msg tstring_msg; -#endif - - /// - /// Base template class to support converting GUID to string - /// - template, class _Ax = std::allocator<_Elem> > class basic_string_guid; - - /// - /// Single-byte character implementation of a class to support converting GUID to string - /// - class WINSTD_API string_guid; - - /// - /// Wide character implementation of a class to support converting GUID to string - /// - class WINSTD_API wstring_guid; - - /// - /// Multi-byte / Wide-character string GUID (according to _UNICODE) - /// -#ifdef _UNICODE - typedef wstring_guid tstring_guid; -#else - typedef string_guid tstring_guid; -#endif - - /// @} - - /// \defgroup WinStdMemSanitize Auto-sanitize Memory Management - /// Sanitizes memory before dismissed - /// - /// @{ - - /// - /// An allocator template that sanitizes each memory block before it is destroyed or reallocated - /// - /// \note - /// `sanitizing_allocator` introduces a performance penalty. However, it provides an additional level of security. - /// Use for security sensitive data memory storage only. - /// - template class sanitizing_allocator; - - /// - /// A sanitizing variant of std::string - /// - /// \note - /// `sanitizing_string` introduces a performance penalty. However, it provides an additional level of security. - /// Use for security sensitive data memory storage only. - /// - typedef std::basic_string, sanitizing_allocator > sanitizing_string; - - /// - /// A sanitizing variant of std::wstring - /// - /// \note - /// `sanitizing_wstring` introduces a performance penalty. However, it provides an additional level of security. - /// Use for security sensitive data memory storage only. - /// - typedef std::basic_string, sanitizing_allocator > sanitizing_wstring; - - /// - /// Multi-byte / Wide-character sanitizing string (according to _UNICODE) - /// -#ifdef _UNICODE - typedef sanitizing_wstring sanitizing_tstring; -#else - typedef sanitizing_string sanitizing_tstring; -#endif - - /// @} -} +/// @} #pragma once @@ -311,6 +322,9 @@ namespace winstd #include +/// \addtogroup WinStdGeneral +/// @{ + #ifndef WINSTD_STACK_BUFFER_BYTES /// /// Size of the stack buffer in bytes used for initial system function call @@ -328,89 +342,19 @@ namespace winstd #define WINSTD_STACK_BUFFER_BYTES 1024 #endif - -// Do not use _vsnprintf_s/_vsnwprintf_s(), since it terminates string by force even when we explicitly want to write unterminated string. -// Threfore turn off compiler warning instead. ;) -#pragma warning(push) -#pragma warning(disable: 4995) -#pragma warning(disable: 4996) - -inline int vsnprintf(_Out_z_cap_(capacity) char *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const char *format, _In_ va_list arg) -{ - return _vsnprintf(str, capacity, format, arg); -} - - -inline int vsnprintf(_Out_z_cap_(capacity) wchar_t *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const wchar_t *format, _In_ va_list arg) -{ - return _vsnwprintf(str, capacity, format, arg); -} - - -template -inline int vsprintf(_Out_ std::basic_string<_Elem, _Traits, _Ax> &str, _In_z_ _Printf_format_string_ const _Elem *format, _In_ va_list arg) -{ - _Elem buf[WINSTD_STACK_BUFFER_BYTES/sizeof(_Elem)]; - - // Try with stack buffer first. - int count = vsnprintf(buf, _countof(buf) - 1, format, arg); - if (count >= 0) { - // Copy from stack. - str.assign(buf, count); - } else { - for (size_t capacity = 2*WINSTD_STACK_BUFFER_BYTES/sizeof(_Elem);; capacity *= 2) { - // Allocate on heap and retry. - std::unique_ptr<_Elem[]> buf(new _Elem[capacity]); - count = vsnprintf(buf.get(), capacity - 1, format, arg); - if (count >= 0) { - str.assign(buf.get(), count); - break; - } - } - } - - return count; -} - -#pragma warning(pop) - - -template -inline int sprintf(_Out_ std::basic_string<_Elem, _Traits, _Ax> &str, _In_z_ _Printf_format_string_ const _Elem *format, ...) -{ - va_list arg; - va_start(arg, format); - int res = vsprintf(str, format, arg); - va_end(arg); - return res; -} - - -template -inline DWORD FormatMessage(_In_ DWORD dwFlags, _In_opt_ LPCVOID lpSource, _In_ DWORD dwMessageId, _In_ DWORD dwLanguageId, _Out_ std::basic_string &str, _In_opt_ va_list *Arguments) -{ - std::unique_ptr > lpBuffer; - DWORD dwResult = FormatMessageA(dwFlags | FORMAT_MESSAGE_ALLOCATE_BUFFER, lpSource, dwMessageId, dwLanguageId, reinterpret_cast(&lpBuffer._Myptr), 0, Arguments); - if (dwResult) - str.assign(lpBuffer.get(), dwResult); - return dwResult; -} - - -template -inline DWORD FormatMessage(_In_ DWORD dwFlags, _In_opt_ LPCVOID lpSource, _In_ DWORD dwMessageId, _In_ DWORD dwLanguageId, _Out_ std::basic_string &str, _In_opt_ va_list *Arguments) -{ - std::unique_ptr > lpBuffer; - DWORD dwResult = FormatMessageW(dwFlags | FORMAT_MESSAGE_ALLOCATE_BUFFER, lpSource, dwMessageId, dwLanguageId, reinterpret_cast(&lpBuffer._Myptr), 0, Arguments); - if (dwResult) - str.assign(lpBuffer.get(), dwResult); - return dwResult; -} +/// @} namespace winstd { - template struct LocalFree_delete + /// \addtogroup WinStdGeneral + /// @{ + + /// + /// Deleter for unique_ptr using LocalFree + /// + template + struct LocalFree_delete { typedef LocalFree_delete<_Ty> _Myt; ///< This type @@ -427,6 +371,8 @@ namespace winstd /// /// Delete a pointer /// + /// \sa [LocalFree function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa366730.aspx) + /// void operator()(_Ty *_Ptr) const { LocalFree(_Ptr); @@ -434,7 +380,11 @@ namespace winstd }; - template struct LocalFree_delete<_Ty[]> + /// + /// Deleter for unique_ptr to array of unknown size using LocalFree + /// + template + struct LocalFree_delete<_Ty[]> { typedef LocalFree_delete<_Ty> _Myt; ///< This type @@ -454,6 +404,8 @@ namespace winstd /// /// Delete a pointer of another type /// + /// \sa [LocalFree function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa366730.aspx) + /// template void operator()(_Other *) const { @@ -461,7 +413,17 @@ namespace winstd } }; + /// @} + + /// \addtogroup WinStdSysHandles + /// @{ + + /// + /// Base abstract template class to support generic object handle keeping + /// + /// It provides basic operators and methods common to all descendands of this class establishing a base to ease the replacement of native object handle type with classes in object-oriented approach. + /// template class handle { @@ -715,6 +677,9 @@ namespace winstd }; + /// + /// Base abstract template class to support object handle keeping for objects that support handle duplication + /// template class dplhandle : public handle { @@ -842,7 +807,12 @@ namespace winstd /// @} + /// \addtogroup WinStdGeneral + /// @{ + /// + /// Helper class to allow limited size FIFO queues implemented as vector of elements + /// template class vector_queue { @@ -1244,19 +1214,26 @@ namespace winstd size_type m_size_max; ///< Maximum size }; + /// @} + /// \addtogroup WinStdExceptions + /// @{ + + /// + /// Numerical runtime error + /// template class num_runtime_error : public std::runtime_error { public: - typedef _Tn error_type; + typedef _Tn error_type; ///< Error number type public: /// /// Constructs an exception /// - /// \param[in] error Numeric error code - /// \param[in] msg Error message + /// \param[in] num Numeric error code + /// \param[in] msg Error message /// inline num_runtime_error(_In_ error_type num, _In_ const std::string& msg) : m_num(num), @@ -1319,14 +1296,17 @@ namespace winstd }; + /// + /// Windows runtime error + /// class WINSTD_API win_runtime_error : public num_runtime_error { public: /// /// Constructs an exception /// - /// \param[in] error Windows error code - /// \param[in] msg Error message + /// \param[in] num Windows error code + /// \param[in] msg Error message /// inline win_runtime_error(_In_ error_type num, _In_ const std::string& msg) : num_runtime_error(num, msg.c_str()) { @@ -1374,7 +1354,14 @@ namespace winstd } }; + /// @} + /// \addtogroup WinStdStrFormat + /// @{ + + /// + /// Base template class to support string formatting using `printf()` style templates + /// template class basic_string_printf : public std::basic_string<_Elem, _Traits, _Ax> { @@ -1439,6 +1426,9 @@ namespace winstd }; + /// + /// Base template class to support string formatting using `FormatMessage()` style templates + /// template class basic_string_msg : public std::basic_string<_Elem, _Traits, _Ax> { @@ -1547,6 +1537,9 @@ namespace winstd }; + /// + /// Base template class to support converting GUID to string + /// template class basic_string_guid : public std::basic_string<_Elem, _Traits, _Ax> { @@ -1557,7 +1550,8 @@ namespace winstd /// /// Initializes a new string and formats its contents to string representation of given GUID. /// - /// \param[in] guid GUID to convert + /// \param[in] guid GUID to convert + /// \param[in] format A `printf()` syntax template to convert GUID to string (i.e. `"{%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X}"`) /// inline basic_string_guid(_In_ const GUID &guid, _In_opt_z_ _Printf_format_string_ const _Elem *format) { @@ -1573,6 +1567,9 @@ namespace winstd }; + /// + /// Single-byte character implementation of a class to support converting GUID to string + /// class WINSTD_API string_guid : public basic_string_guid, std::allocator > { public: @@ -1593,6 +1590,9 @@ namespace winstd }; + /// + /// Wide character implementation of a class to support converting GUID to string + /// class WINSTD_API wstring_guid : public basic_string_guid, std::allocator > { public: @@ -1612,11 +1612,22 @@ namespace winstd /// @} }; + /// @} + + /// \addtogroup WinStdMemSanitize + /// @{ // winstd::sanitizing_allocator::destroy() member generates _Ptr parameter not used warning for primitive datatypes _Ty. #pragma warning(push) #pragma warning(disable: 4100) + /// + /// An allocator template that sanitizes each memory block before it is destroyed or reallocated + /// + /// \note + /// `sanitizing_allocator` introduces a performance penalty. However, it provides an additional level of security. + /// Use for security sensitive data memory storage only. + /// template class sanitizing_allocator : public std::allocator<_Ty> { @@ -1670,4 +1681,85 @@ namespace winstd }; #pragma warning(pop) + + /// @} +} + + +// Do not use _vsnprintf_s/_vsnwprintf_s(), since it terminates string by force even when we explicitly want to write unterminated string. +// Threfore turn off compiler warning instead. ;) +#pragma warning(push) +#pragma warning(disable: 4995) +#pragma warning(disable: 4996) + +inline int vsnprintf(_Out_z_cap_(capacity) char *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const char *format, _In_ va_list arg) +{ + return _vsnprintf(str, capacity, format, arg); +} + + +inline int vsnprintf(_Out_z_cap_(capacity) wchar_t *str, _In_ size_t capacity, _In_z_ _Printf_format_string_ const wchar_t *format, _In_ va_list arg) +{ + return _vsnwprintf(str, capacity, format, arg); +} + + +template +inline int vsprintf(_Out_ std::basic_string<_Elem, _Traits, _Ax> &str, _In_z_ _Printf_format_string_ const _Elem *format, _In_ va_list arg) +{ + _Elem buf[WINSTD_STACK_BUFFER_BYTES/sizeof(_Elem)]; + + // Try with stack buffer first. + int count = vsnprintf(buf, _countof(buf) - 1, format, arg); + if (count >= 0) { + // Copy from stack. + str.assign(buf, count); + } else { + for (size_t capacity = 2*WINSTD_STACK_BUFFER_BYTES/sizeof(_Elem);; capacity *= 2) { + // Allocate on heap and retry. + std::unique_ptr<_Elem[]> buf(new _Elem[capacity]); + count = vsnprintf(buf.get(), capacity - 1, format, arg); + if (count >= 0) { + str.assign(buf.get(), count); + break; + } + } + } + + return count; +} + +#pragma warning(pop) + + +template +inline int sprintf(_Out_ std::basic_string<_Elem, _Traits, _Ax> &str, _In_z_ _Printf_format_string_ const _Elem *format, ...) +{ + va_list arg; + va_start(arg, format); + int res = vsprintf(str, format, arg); + va_end(arg); + return res; +} + + +template +inline DWORD FormatMessage(_In_ DWORD dwFlags, _In_opt_ LPCVOID lpSource, _In_ DWORD dwMessageId, _In_ DWORD dwLanguageId, _Out_ std::basic_string &str, _In_opt_ va_list *Arguments) +{ + std::unique_ptr > lpBuffer; + DWORD dwResult = FormatMessageA(dwFlags | FORMAT_MESSAGE_ALLOCATE_BUFFER, lpSource, dwMessageId, dwLanguageId, reinterpret_cast(&lpBuffer._Myptr), 0, Arguments); + if (dwResult) + str.assign(lpBuffer.get(), dwResult); + return dwResult; +} + + +template +inline DWORD FormatMessage(_In_ DWORD dwFlags, _In_opt_ LPCVOID lpSource, _In_ DWORD dwMessageId, _In_ DWORD dwLanguageId, _Out_ std::basic_string &str, _In_opt_ va_list *Arguments) +{ + std::unique_ptr > lpBuffer; + DWORD dwResult = FormatMessageW(dwFlags | FORMAT_MESSAGE_ALLOCATE_BUFFER, lpSource, dwMessageId, dwLanguageId, reinterpret_cast(&lpBuffer._Myptr), 0, Arguments); + if (dwResult) + str.assign(lpBuffer.get(), dwResult); + return dwResult; } diff --git a/include/WinStd/Cred.h b/include/WinStd/Cred.h index 18326d7d..8f1cdeff 100644 --- a/include/WinStd/Cred.h +++ b/include/WinStd/Cred.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdCryptoAPI Cryptography API +/// Integrates WinStd classes with Microsoft Cryptography API +/// + #include "Common.h" #include @@ -26,23 +31,8 @@ namespace winstd { - /// - /// \defgroup WinStdCryptoAPI Cryptography API - /// Integrates WinStd classes with Microsoft Cryptography API - /// - /// @{ - - /// - /// Deleter for unique_ptr using CredFree - /// template struct CredFree_delete; - - /// - /// Deleter for unique_ptr to array of unknown size using CredFree - /// template struct CredFree_delete<_Ty[]>; - - /// @} } @@ -56,11 +46,7 @@ namespace winstd /// inline BOOL CredEnumerate(_In_ LPCTSTR Filter, _In_ DWORD Flags, _Out_ DWORD *Count, _Out_ std::unique_ptr > &cCredentials); -/// -/// Encrypts the specified credentials so that only the current security context can decrypt them. -/// -/// \sa [CredProtect function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374803.aspx) -/// +/// @copydoc CredProtectW() template inline BOOL CredProtectA(_In_ BOOL fAsSelf, _In_ LPCSTR pszCredentials, _In_ DWORD cchCredentials, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sProtectedCredentials, _Out_ CRED_PROTECTION_TYPE *ProtectionType); /// @@ -70,11 +56,7 @@ template inline BOOL CredProtectA(_In_ BO /// template inline BOOL CredProtectW(_In_ BOOL fAsSelf, _In_ LPCWSTR pszCredentials, _In_ DWORD cchCredentials, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sProtectedCredentials, _Out_ CRED_PROTECTION_TYPE *ProtectionType); -/// -/// Decrypts credentials that were previously encrypted by using the CredProtect function. -/// -/// \sa [CredUnprotect function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa375186.aspx) -/// +/// @copydoc CredUnprotectW() template inline BOOL CredUnprotectA(_In_ BOOL fAsSelf, _In_ LPCSTR pszProtectedCredentials, _In_ DWORD cchCredentials, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sCredentials); /// @@ -91,6 +73,12 @@ template inline BOOL CredUnprotectW(_In_ namespace winstd { + /// \addtogroup WinStdCryptoAPI + /// @{ + + /// + /// Deleter for unique_ptr using CredFree + /// template struct CredFree_delete { typedef CredFree_delete<_Ty> _Myt; ///< This type @@ -108,6 +96,8 @@ namespace winstd /// /// Delete a pointer /// + /// \sa [CredFree function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374796.aspx) + /// void operator()(_Ty *_Ptr) const { CredFree(_Ptr); @@ -115,6 +105,9 @@ namespace winstd }; + /// + /// Deleter for unique_ptr to array of unknown size using CredFree + /// template struct CredFree_delete<_Ty[]> { typedef CredFree_delete<_Ty> _Myt; ///< This type @@ -127,6 +120,8 @@ namespace winstd /// /// Delete a pointer /// + /// \sa [CredFree function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374796.aspx) + /// void operator()(_Ty *_Ptr) const { CredFree(_Ptr); @@ -135,12 +130,16 @@ namespace winstd /// /// Delete a pointer of another type /// + /// \sa [CredFree function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374796.aspx) + /// template void operator()(_Other *) const { CredFree(_Ptr); } }; + + /// @} } diff --git a/include/WinStd/Crypt.h b/include/WinStd/Crypt.h index 588917d9..3152b25f 100644 --- a/include/WinStd/Crypt.h +++ b/include/WinStd/Crypt.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdCryptoAPI Cryptography API +/// Integrates WinStd classes with Microsoft Cryptography API +/// + #include "Common.h" #include @@ -25,17 +30,21 @@ #include #include -/// -/// \defgroup WinStdCryptoAPI Cryptography API -/// Integrates WinStd classes with Microsoft Cryptography API -/// +namespace winstd +{ + class WINSTD_API cert_context; + class WINSTD_API cert_chain_context; + class WINSTD_API cert_store; + class WINSTD_API crypt_prov; + class WINSTD_API crypt_hash; + class WINSTD_API crypt_key; + class WINSTD_API data_blob; +} + +/// \addtogroup WinStdCryptoAPI /// @{ -/// -/// Obtains the subject or issuer name from a certificate [CERT_CONTEXT](https://msdn.microsoft.com/en-us/library/windows/desktop/aa377189.aspx) structure and stores it in a std::string string. -/// -/// \sa [CertGetNameString function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376086.aspx) -/// +/// @copydoc CertGetNameStringW() template inline DWORD CertGetNameStringA(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sNameString); /// @@ -96,6 +105,11 @@ template inline BOOL CryptDecrypt(_In_ HCRYPTKEY hKey, _In /// @} +#pragma once + +#include + + namespace winstd { /// \addtogroup WinStdCryptoAPI @@ -104,45 +118,582 @@ namespace winstd /// /// PCCERT_CONTEXT wrapper class /// - class WINSTD_API cert_context; + class WINSTD_API cert_context : public dplhandle + { + DPLHANDLE_IMPL(cert_context) + + public: + /// + /// Destroys the certificate context. + /// + /// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx) + /// + virtual ~cert_context(); + + /// + /// Creates the certificate context. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CertCreateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376033.aspx) + /// + inline bool create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded) + { + handle_type h = CertCreateCertificateContext(dwCertEncodingType, pbCertEncoded, cbCertEncoded); + if (h) { + attach(h); + return true; + } else + return false; + } + + /// + /// Is certificate equal to? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is equal to \p other; + /// - Zero otherwise. + /// + inline bool operator==(_In_ const handle_type &other) const + { + return + m_h == other || + m_h->cbCertEncoded == other->cbCertEncoded && memcmp(m_h->pbCertEncoded, other->pbCertEncoded, m_h->cbCertEncoded) == 0; + } + + /// + /// Is certificate not equal to? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is not equal to \p other; + /// - Zero otherwise. + /// + inline bool operator!=(_In_ const handle_type &other) const + { + return !operator==(other); + } + + /// + /// Is certificate less than? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is less than \p other; + /// - Zero otherwise. + /// + inline bool operator<(_In_ const handle_type &other) const + { + int r = memcmp(m_h->pbCertEncoded, other->pbCertEncoded, std::min(m_h->cbCertEncoded, other->cbCertEncoded)); + return r < 0 || r == 0 && m_h->cbCertEncoded < other->cbCertEncoded; + } + + /// + /// Is certificate greater than? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is greater than \p other; + /// - Zero otherwise. + /// + inline bool operator>(_In_ const handle_type &other) const + { + int r = memcmp(m_h->pbCertEncoded, other->pbCertEncoded, std::min(m_h->cbCertEncoded, other->cbCertEncoded)); + return r > 0 || r == 0 && m_h->cbCertEncoded > other->cbCertEncoded; + } + + /// + /// Is certificate less than or equal? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is less than \p other; + /// - Zero otherwise. + /// + inline bool operator<=(_In_ const handle_type &other) const + { + return !operator>(other); + } + + /// + /// Is certificate greater than or equal? + /// + /// \param[in] other Certificate to compare against + /// \return + /// - Non zero when certificate is greater than \p other; + /// - Zero otherwise. + /// + inline bool operator>=(_In_ const handle_type &other) const + { + return !operator<(other); + } + + protected: + /// + /// Destroys the certificate context. + /// + /// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx) + /// + virtual void free_internal(); + + /// + /// Duplicates the certificate context. + /// + /// \param[in] h Object handle of existing certificate context + /// + /// \return Duplicated certificate context handle + /// + /// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx) + /// + virtual handle_type duplicate_internal(_In_ handle_type h) const; + }; + /// /// PCCERT_CHAIN_CONTEXT wrapper class /// - class WINSTD_API cert_chain_context; + class WINSTD_API cert_chain_context : public dplhandle + { + DPLHANDLE_IMPL(cert_chain_context) + + public: + /// + /// Destroys the certificate chain context. + /// + /// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx) + /// + virtual ~cert_chain_context(); + + /// + /// Creates the certificate chain context. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CertGetCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376078.aspx) + /// + inline bool create(_In_opt_ HCERTCHAINENGINE hChainEngine, _In_ PCCERT_CONTEXT pCertContext, _In_opt_ LPFILETIME pTime, _In_opt_ HCERTSTORE hAdditionalStore, _In_ PCERT_CHAIN_PARA pChainPara, _In_ DWORD dwFlags, __reserved LPVOID pvReserved = NULL) + { + handle_type h; + if (CertGetCertificateChain(hChainEngine, pCertContext, pTime, hAdditionalStore, pChainPara, dwFlags, pvReserved, &h)) { + attach(h); + return true; + } else + return false; + } + + protected: + /// + /// Destroys the certificate chain context. + /// + /// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx) + /// + virtual void free_internal(); + + /// + /// Duplicates the certificate chain context. + /// + /// \param[in] h Object handle of existing certificate chain context + /// + /// \return Duplicated certificate chain context handle + /// + /// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx) + /// + virtual handle_type duplicate_internal(_In_ handle_type h) const; + }; + /// /// HCERTSTORE wrapper class /// - class WINSTD_API cert_store; + class WINSTD_API cert_store : public handle + { + HANDLE_IMPL(cert_store) + + public: + /// + /// Closes the certificate store. + /// + /// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx) + /// + virtual ~cert_store(); + + /// + /// Opens the certificate store. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CertOpenStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376559.aspx) + /// + inline bool create(_In_ LPCSTR lpszStoreProvider, _In_ DWORD dwEncodingType, _In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ DWORD dwFlags, _In_opt_ const void *pvPara) + { + handle_type h = CertOpenStore(lpszStoreProvider, dwEncodingType, hCryptProv, dwFlags, pvPara); + if (h) { + attach(h); + return true; + } else + return false; + } + + /// + /// Opens the most common system certificate store. To open certificate stores with more complex requirements, such as file-based or memory-based stores, use `create()`. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CertOpenSystemStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376560.aspx) + /// + inline bool create(_In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ LPCTSTR szSubsystemProtocol) + { + handle_type h = CertOpenSystemStore(hCryptProv, szSubsystemProtocol); + if (h) { + attach(h); + return true; + } else + return false; + } + + protected: + /// + /// Closes the certificate store. + /// + /// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx) + /// + virtual void free_internal(); + }; + /// /// HCRYPTPROV wrapper class /// - class WINSTD_API crypt_prov; + class WINSTD_API crypt_prov : public handle + { + HANDLE_IMPL(crypt_prov) + + public: + /// + /// Releases the cryptographic context. + /// + /// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx) + /// + virtual ~crypt_prov(); + + /// + /// Acquires the cryptographic context. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CryptAcquireContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379886.aspx) + /// + inline bool create(_In_opt_ LPCTSTR szContainer, _In_opt_ LPCTSTR szProvider, _In_ DWORD dwProvType, _In_ DWORD dwFlags = 0) + { + handle_type h; + if (CryptAcquireContext(&h, szContainer, szProvider, dwProvType, dwFlags)) { + attach(h); + return true; + } else + return false; + } + + protected: + /// + /// Releases the cryptographic context. + /// + /// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx) + /// + virtual void free_internal(); + }; + /// /// HCRYPTHASH wrapper class /// - class WINSTD_API crypt_hash; + class WINSTD_API crypt_hash : public dplhandle + { + DPLHANDLE_IMPL(crypt_hash) + + public: + /// + /// Destroys the hash context. + /// + /// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx) + /// + virtual ~crypt_hash(); + + /// + /// Creates the hash context. + /// + /// \return + /// - true when creation succeeds; + /// - false when creation fails. For extended error information, call `GetLastError()`. + /// + /// \sa [CryptCreateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379908.aspx) + /// + inline bool create(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_opt_ HCRYPTKEY hKey = NULL, _In_opt_ DWORD dwFlags = 0) + { + handle_type h; + if (CryptCreateHash(hProv, Algid, hKey, dwFlags, &h)) { + attach(h); + return true; + } else + return false; + } + + protected: + /// + /// Destroys the hash context. + /// + /// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx) + /// + virtual void free_internal(); + + /// + /// Duplicates the hash context. + /// + /// \param[in] h Object handle of existing hash context + /// + /// \return Duplicated hash context handle + /// + /// \sa [CryptDuplicateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379919.aspx) + /// + virtual handle_type duplicate_internal(_In_ handle_type h) const; + }; + /// /// HCRYPTKEY wrapper class /// - class WINSTD_API crypt_key; + class WINSTD_API crypt_key : public dplhandle + { + DPLHANDLE_IMPL(crypt_key) + + public: + /// + /// Destroys the key. + /// + /// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx) + /// + virtual ~crypt_key(); + + /// + /// Generates the key. + /// + /// \sa [CryptGenKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379941.aspx) + /// + inline bool generate(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ DWORD dwFlags) + { + handle_type h; + if (CryptGenKey(hProv, Algid, dwFlags, &h)) { + attach(h); + return true; + } else + return false; + } + + /// + /// Imports the key. + /// + /// \sa [CryptImportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380207.aspx) + /// + inline bool import(_In_ HCRYPTPROV hProv, __in_bcount(dwDataLen) const BYTE *pbData, _In_ DWORD dwDataLen, _In_ HCRYPTKEY hPubKey, _In_ DWORD dwFlags) + { + handle_type h; + if (CryptImportKey(hProv, pbData, dwDataLen, hPubKey, dwFlags, &h)) { + attach(h); + return true; + } else + return false; + } + + /// + /// Imports the public key. + /// + /// \sa [CryptImportPublicKeyInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380209.aspx) + /// + inline bool import_public(_In_ HCRYPTPROV hCryptProv, _In_ DWORD dwCertEncodingType, _In_ PCERT_PUBLIC_KEY_INFO pInfo) + { + handle_type h; + if (CryptImportPublicKeyInfo(hCryptProv, dwCertEncodingType, pInfo, &h)) { + attach(h); + return true; + } else + return false; + } + + /// + /// Generates cryptographic session keys derived from a base data value. + /// + /// \sa [CryptDeriveKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379916.aspx) + /// + inline bool derive(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ HCRYPTHASH hBaseData, _In_ DWORD dwFlags) + { + handle_type h; + if (CryptDeriveKey(hProv, Algid, hBaseData, dwFlags, &h)) { + attach(h); + return true; + } else + return false; + } + + /// + /// Creates Exponent-of-one key + /// + /// \sa [How to export and import plain text session keys by using CryptoAPI](https://support.microsoft.com/en-us/kb/228786) + /// + /// \param[in] hProv Handle of cryptographics provider to use + /// \param[in] dwKeySpec Key specification (`AT_KEYEXCHANGE` or `AT_SIGNATURE`) + /// + bool create_exp1(_In_ HCRYPTPROV hProv, _In_ DWORD dwKeySpec); + + protected: + /// + /// Destroys the key. + /// + /// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx) + /// + virtual void free_internal(); + + /// + /// Duplicates the key. + /// + /// \param[in] h Object handle of existing key + /// + /// \return Duplicated key handle + /// + /// \sa [CryptDuplicateKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379920.aspx) + /// + virtual handle_type duplicate_internal(_In_ handle_type h) const; + }; + /// /// DATA_BLOB wrapper class /// - class WINSTD_API data_blob; + class WINSTD_API data_blob : public DATA_BLOB + { + public: + /// + /// Initializes an empty BLOB. + /// + inline data_blob() + { + cbData = 0; + pbData = NULL; + } + + /// + /// Initializes a BLOB from existing data. + /// + inline data_blob(_In_count_(size) BYTE *data, _In_ DWORD size) + { + cbData = size; + pbData = data; + } + + /// + /// Duplicate an existing BLOB. + /// + inline data_blob(_In_ const DATA_BLOB &other) + { + cbData = other.cbData; + if (cbData) { + pbData = (BYTE*)LocalAlloc(LMEM_FIXED, other.cbData); + assert(pbData); + memcpy(pbData, other.pbData, other.cbData); + } else + pbData = NULL; + } + + /// + /// Move an existing BLOB. + /// + inline data_blob(_Inout_ DATA_BLOB &&other) + { + cbData = other.cbData; + pbData = other.pbData; + other.cbData = 0; + other.pbData = NULL; + } + + /// + /// Destroys the BLOB. + /// + virtual ~data_blob(); + + /// + /// Copy an existing BLOB. + /// + inline data_blob& operator=(_In_ const DATA_BLOB &other) + { + if (this != &other) { + cbData = other.cbData; + if (pbData) + LocalFree(pbData); + if (cbData) { + pbData = (BYTE*)LocalAlloc(LMEM_FIXED, other.cbData); + assert(pbData); + memcpy(pbData, other.pbData, other.cbData); + } else + pbData = NULL; + } + + return *this; + } + + /// + /// Move an existing BLOB. + /// + inline data_blob& operator=(_Inout_ DATA_BLOB &&other) + { + if (this != &other) { + cbData = other.cbData; + if (pbData) + LocalFree(pbData); + pbData = other.pbData; + other.cbData = 0; + other.pbData = NULL; + } + + return *this; + } + + /// + /// Get BLOB size. + /// + inline DWORD size() const + { + return cbData; + } + + /// + /// Get BLOB buffer. + /// + inline const BYTE* data() const + { + return pbData; + } + + /// + /// Get BLOB buffer. + /// + inline BYTE* data() + { + return pbData; + } + }; /// @} } -#pragma once - -#include - template inline DWORD CertGetNameStringA(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sNameString) @@ -329,562 +880,3 @@ inline BOOL CryptDecrypt(_In_ HCRYPTKEY hKey, _In_opt_ HCRYPTHASH hHash, _In_ BO return FALSE; } - - -namespace winstd -{ - class WINSTD_API cert_context : public dplhandle - { - DPLHANDLE_IMPL(cert_context) - - public: - /// - /// Destroys the certificate context. - /// - /// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx) - /// - virtual ~cert_context(); - - /// - /// Creates the certificate context. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CertCreateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376033.aspx) - /// - inline bool create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded) - { - handle_type h = CertCreateCertificateContext(dwCertEncodingType, pbCertEncoded, cbCertEncoded); - if (h) { - attach(h); - return true; - } else - return false; - } - - /// - /// Is certificate equal to? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is equal to \p other; - /// - Zero otherwise. - /// - inline bool operator==(_In_ const handle_type &other) const - { - return - m_h == other || - m_h->cbCertEncoded == other->cbCertEncoded && memcmp(m_h->pbCertEncoded, other->pbCertEncoded, m_h->cbCertEncoded) == 0; - } - - /// - /// Is certificate not equal to? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is not equal to \p other; - /// - Zero otherwise. - /// - inline bool operator!=(_In_ const handle_type &other) const - { - return !operator==(other); - } - - /// - /// Is certificate less than? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is less than \p other; - /// - Zero otherwise. - /// - inline bool operator<(_In_ const handle_type &other) const - { - int r = memcmp(m_h->pbCertEncoded, other->pbCertEncoded, std::min(m_h->cbCertEncoded, other->cbCertEncoded)); - return r < 0 || r == 0 && m_h->cbCertEncoded < other->cbCertEncoded; - } - - /// - /// Is certificate greater than? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is greater than \p other; - /// - Zero otherwise. - /// - inline bool operator>(_In_ const handle_type &other) const - { - int r = memcmp(m_h->pbCertEncoded, other->pbCertEncoded, std::min(m_h->cbCertEncoded, other->cbCertEncoded)); - return r > 0 || r == 0 && m_h->cbCertEncoded > other->cbCertEncoded; - } - - /// - /// Is certificate less than or equal? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is less than \p other; - /// - Zero otherwise. - /// - inline bool operator<=(_In_ const handle_type &other) const - { - return !operator>(other); - } - - /// - /// Is certificate greater than or equal? - /// - /// \param[in] other Certificate to compare against - /// \return - /// - Non zero when certificate is greater than \p other; - /// - Zero otherwise. - /// - inline bool operator>=(_In_ const handle_type &other) const - { - return !operator<(other); - } - - protected: - /// - /// Destroys the certificate context. - /// - /// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx) - /// - virtual void free_internal(); - - /// - /// Duplicates the certificate context. - /// - /// \param[in] h Object handle of existing certificate context - /// - /// \return Duplicated certificate context handle - /// - /// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx) - /// - virtual handle_type duplicate_internal(_In_ handle_type h) const; - }; - - - class WINSTD_API cert_chain_context : public dplhandle - { - DPLHANDLE_IMPL(cert_chain_context) - - public: - /// - /// Destroys the certificate chain context. - /// - /// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx) - /// - virtual ~cert_chain_context(); - - /// - /// Creates the certificate chain context. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CertGetCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376078.aspx) - /// - inline bool create(_In_opt_ HCERTCHAINENGINE hChainEngine, _In_ PCCERT_CONTEXT pCertContext, _In_opt_ LPFILETIME pTime, _In_opt_ HCERTSTORE hAdditionalStore, _In_ PCERT_CHAIN_PARA pChainPara, _In_ DWORD dwFlags, __reserved LPVOID pvReserved = NULL) - { - handle_type h; - if (CertGetCertificateChain(hChainEngine, pCertContext, pTime, hAdditionalStore, pChainPara, dwFlags, pvReserved, &h)) { - attach(h); - return true; - } else - return false; - } - - protected: - /// - /// Destroys the certificate chain context. - /// - /// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx) - /// - virtual void free_internal(); - - /// - /// Duplicates the certificate chain context. - /// - /// \param[in] h Object handle of existing certificate chain context - /// - /// \return Duplicated certificate chain context handle - /// - /// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx) - /// - virtual handle_type duplicate_internal(_In_ handle_type h) const; - }; - - - class WINSTD_API cert_store : public handle - { - HANDLE_IMPL(cert_store) - - public: - /// - /// Closes the certificate store. - /// - /// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx) - /// - virtual ~cert_store(); - - /// - /// Opens the certificate store. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CertOpenStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376559.aspx) - /// - inline bool create(_In_ LPCSTR lpszStoreProvider, _In_ DWORD dwEncodingType, _In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ DWORD dwFlags, _In_opt_ const void *pvPara) - { - handle_type h = CertOpenStore(lpszStoreProvider, dwEncodingType, hCryptProv, dwFlags, pvPara); - if (h) { - attach(h); - return true; - } else - return false; - } - - /// - /// Opens the most common system certificate store. To open certificate stores with more complex requirements, such as file-based or memory-based stores, use `create()`. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CertOpenSystemStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376560.aspx) - /// - inline bool create(_In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ LPCTSTR szSubsystemProtocol) - { - handle_type h = CertOpenSystemStore(hCryptProv, szSubsystemProtocol); - if (h) { - attach(h); - return true; - } else - return false; - } - - protected: - /// - /// Closes the certificate store. - /// - /// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx) - /// - virtual void free_internal(); - }; - - - class WINSTD_API crypt_prov : public handle - { - HANDLE_IMPL(crypt_prov) - - public: - /// - /// Releases the cryptographic context. - /// - /// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx) - /// - virtual ~crypt_prov(); - - /// - /// Acquires the cryptographic context. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CryptAcquireContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379886.aspx) - /// - inline bool create(_In_opt_ LPCTSTR szContainer, _In_opt_ LPCTSTR szProvider, _In_ DWORD dwProvType, _In_ DWORD dwFlags = 0) - { - handle_type h; - if (CryptAcquireContext(&h, szContainer, szProvider, dwProvType, dwFlags)) { - attach(h); - return true; - } else - return false; - } - - protected: - /// - /// Releases the cryptographic context. - /// - /// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx) - /// - virtual void free_internal(); - }; - - - class WINSTD_API crypt_hash : public dplhandle - { - DPLHANDLE_IMPL(crypt_hash) - - public: - /// - /// Destroys the hash context. - /// - /// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx) - /// - virtual ~crypt_hash(); - - /// - /// Creates the hash context. - /// - /// \return - /// - true when creation succeeds; - /// - false when creation fails. For extended error information, call `GetLastError()`. - /// - /// \sa [CryptCreateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379908.aspx) - /// - inline bool create(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_opt_ HCRYPTKEY hKey = NULL, _In_opt_ DWORD dwFlags = 0) - { - handle_type h; - if (CryptCreateHash(hProv, Algid, hKey, dwFlags, &h)) { - attach(h); - return true; - } else - return false; - } - - protected: - /// - /// Destroys the hash context. - /// - /// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx) - /// - virtual void free_internal(); - - /// - /// Duplicates the hash context. - /// - /// \param[in] h Object handle of existing hash context - /// - /// \return Duplicated hash context handle - /// - /// \sa [CryptDuplicateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379919.aspx) - /// - virtual handle_type duplicate_internal(_In_ handle_type h) const; - }; - - - class WINSTD_API crypt_key : public dplhandle - { - DPLHANDLE_IMPL(crypt_key) - - public: - /// - /// Destroys the key. - /// - /// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx) - /// - virtual ~crypt_key(); - - /// - /// Generates the key. - /// - /// \sa [CryptGenKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379941.aspx) - /// - inline bool generate(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ DWORD dwFlags) - { - handle_type h; - if (CryptGenKey(hProv, Algid, dwFlags, &h)) { - attach(h); - return true; - } else - return false; - } - - /// - /// Imports the key. - /// - /// \sa [CryptImportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380207.aspx) - /// - inline bool import(_In_ HCRYPTPROV hProv, __in_bcount(dwDataLen) const BYTE *pbData, _In_ DWORD dwDataLen, _In_ HCRYPTKEY hPubKey, _In_ DWORD dwFlags) - { - handle_type h; - if (CryptImportKey(hProv, pbData, dwDataLen, hPubKey, dwFlags, &h)) { - attach(h); - return true; - } else - return false; - } - - /// - /// Imports the public key. - /// - /// \sa [CryptImportPublicKeyInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380209.aspx) - /// - inline bool import_public(_In_ HCRYPTPROV hCryptProv, _In_ DWORD dwCertEncodingType, _In_ PCERT_PUBLIC_KEY_INFO pInfo) - { - handle_type h; - if (CryptImportPublicKeyInfo(hCryptProv, dwCertEncodingType, pInfo, &h)) { - attach(h); - return true; - } else - return false; - } - - /// - /// Generates cryptographic session keys derived from a base data value. - /// - /// \sa [CryptDeriveKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379916.aspx) - /// - inline bool derive(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ HCRYPTHASH hBaseData, _In_ DWORD dwFlags) - { - handle_type h; - if (CryptDeriveKey(hProv, Algid, hBaseData, dwFlags, &h)) { - attach(h); - return true; - } else - return false; - } - - /// - /// Creates Exponent-of-one key - /// - /// \sa [How to export and import plain text session keys by using CryptoAPI](https://support.microsoft.com/en-us/kb/228786) - /// - /// \param[in] hProv Handle of cryptographics provider to use - /// \param[in] dwKeySpec Key specification (`AT_KEYEXCHANGE` or `AT_SIGNATURE`) - /// - bool create_exp1(_In_ HCRYPTPROV hProv, _In_ DWORD dwKeySpec); - - protected: - /// - /// Destroys the key. - /// - /// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx) - /// - virtual void free_internal(); - - /// - /// Duplicates the key. - /// - /// \param[in] h Object handle of existing key - /// - /// \return Duplicated key handle - /// - /// \sa [CryptDuplicateKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379920.aspx) - /// - virtual handle_type duplicate_internal(_In_ handle_type h) const; - }; - - - class WINSTD_API data_blob : public DATA_BLOB - { - public: - /// - /// Initializes an empty BLOB. - /// - inline data_blob() - { - cbData = 0; - pbData = NULL; - } - - /// - /// Initializes a BLOB from existing data. - /// - inline data_blob(_In_count_(size) BYTE *data, _In_ DWORD size) - { - cbData = size; - pbData = data; - } - - /// - /// Duplicate an existing BLOB. - /// - inline data_blob(_In_ const DATA_BLOB &other) - { - cbData = other.cbData; - if (cbData) { - pbData = (BYTE*)LocalAlloc(LMEM_FIXED, other.cbData); - assert(pbData); - memcpy(pbData, other.pbData, other.cbData); - } else - pbData = NULL; - } - - /// - /// Move an existing BLOB. - /// - inline data_blob(_Inout_ DATA_BLOB &&other) - { - cbData = other.cbData; - pbData = other.pbData; - other.cbData = 0; - other.pbData = NULL; - } - - /// - /// Destroys the BLOB. - /// - virtual ~data_blob(); - - /// - /// Copy an existing BLOB. - /// - inline data_blob& operator=(_In_ const DATA_BLOB &other) - { - if (this != &other) { - cbData = other.cbData; - if (pbData) - LocalFree(pbData); - if (cbData) { - pbData = (BYTE*)LocalAlloc(LMEM_FIXED, other.cbData); - assert(pbData); - memcpy(pbData, other.pbData, other.cbData); - } else - pbData = NULL; - } - - return *this; - } - - /// - /// Move an existing BLOB. - /// - inline data_blob& operator=(_Inout_ DATA_BLOB &&other) - { - if (this != &other) { - cbData = other.cbData; - if (pbData) - LocalFree(pbData); - pbData = other.pbData; - other.cbData = 0; - other.pbData = NULL; - } - - return *this; - } - - /// - /// Get BLOB size. - /// - inline DWORD size() const - { - return cbData; - } - - /// - /// Get BLOB buffer. - /// - inline const BYTE* data() const - { - return pbData; - } - - /// - /// Get BLOB buffer. - /// - inline BYTE* data() - { - return pbData; - } - }; -} diff --git a/include/WinStd/EAP.h b/include/WinStd/EAP.h index 5caf42a9..a71fa2de 100644 --- a/include/WinStd/EAP.h +++ b/include/WinStd/EAP.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdEAPAPI Extensible Authentication Protocol API +/// Integrates WinStd classes with Microsoft EAP API +/// + #include "Common.h" #include @@ -28,93 +33,39 @@ namespace winstd { - /// - /// \defgroup WinStdEAPAPI Extensible Authentication Protocol API - /// Integrates WinStd classes with Microsoft EAP API - /// - /// @{ - - /// - /// EAP method numbers - /// - /// \sa [Extensible Authentication Protocol (EAP) Registry (Chapter: Method Types)](https://www.iana.org/assignments/eap-numbers/eap-numbers.xhtml#eap-numbers-4) - /// enum eap_type_t; - - /// - /// Deleter for unique_ptr using EapHostPeerFreeMemory - /// struct WINSTD_API EapHostPeerFreeMemory_delete; + struct WINSTD_API EapHostPeerFreeRuntimeMemory_delete; + struct WINSTD_API EapHostPeerFreeErrorMemory_delete; + struct WINSTD_API EapHostPeerFreeEapError_delete; + class WINSTD_API WINSTD_NOVTABLE eap_attr; + class WINSTD_API WINSTD_NOVTABLE eap_method_prop; + class WINSTD_API eap_packet; + class WINSTD_API WINSTD_NOVTABLE eap_method_info_array; + class WINSTD_API eap_runtime_error; + + /// \addtogroup WinStdEAPAPI + /// @{ /// /// EapHost BLOB wrapper class /// typedef std::unique_ptr WINSTD_API eap_blob; - /// - /// Deleter for unique_ptr using EapHostPeerFreeRuntimeMemory - /// - struct WINSTD_API EapHostPeerFreeRuntimeMemory_delete; - /// /// EapHost BLOB wrapper class /// typedef std::unique_ptr WINSTD_API eap_blob_runtime; - /// - /// Deleter for unique_ptr to EAP_ERROR using EapHostPeerFreeErrorMemory - /// - struct WINSTD_API EapHostPeerFreeErrorMemory_delete; - /// /// EAP_ERROR wrapper class /// typedef std::unique_ptr WINSTD_API eap_error; - /// - /// Deleter for unique_ptr to EAP_ERROR using EapHostPeerFreeEapError - /// - struct WINSTD_API EapHostPeerFreeEapError_delete; - /// /// EAP_ERROR wrapper class /// - typedef std::unique_ptr WINSTD_API eap_error_runtime; - - /// - /// EAP_ATTRIBUTE wrapper class - /// - class WINSTD_API eap_attr; - - /// - /// EAP_METHOD_PROPERTY wrapper class - /// - class WINSTD_API eap_method_prop; - - /// - /// EapPacket wrapper class - /// - class WINSTD_API eap_packet; - - /// - /// EAP_METHOD_INFO_ARRAY wrapper class - /// - class WINSTD_API eap_method_info_array; - - /// @} - - /// - /// \defgroup WinStdExceptions Exceptions - /// Additional exceptions - /// - /// @{ - - /// - /// EapHost runtime error - /// - /// \sa [EAP_ERROR structure](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363699.aspx) - /// - class WINSTD_API eap_runtime_error; + typedef std::unique_ptr WINSTD_API eap_error_runtime; /// @} } @@ -158,6 +109,14 @@ inline bool operator!=(_In_ const EAP_METHOD_TYPE &a, _In_ const EAP_METHOD_TYPE namespace winstd { + /// \addtogroup WinStdEAPAPI + /// @{ + + /// + /// EAP method numbers + /// + /// \sa [Extensible Authentication Protocol (EAP) Registry (Chapter: Method Types)](https://www.iana.org/assignments/eap-numbers/eap-numbers.xhtml#eap-numbers-4) + /// #pragma warning(suppress: 4480) enum eap_type_t : unsigned char { eap_type_undefined = 0, ///< Undefined EAP type @@ -182,6 +141,9 @@ namespace winstd }; + /// + /// Deleter for unique_ptr using EapHostPeerFreeMemory + /// struct WINSTD_API EapHostPeerFreeMemory_delete { /// @@ -192,6 +154,8 @@ namespace winstd /// /// Delete a pointer /// + /// \sa [EapHostPeerFreeMemory function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363558.aspx) + /// template void operator()(_T *_Ptr) const { @@ -200,6 +164,9 @@ namespace winstd }; + /// + /// Deleter for unique_ptr using EapHostPeerFreeRuntimeMemory + /// struct WINSTD_API EapHostPeerFreeRuntimeMemory_delete { /// @@ -218,6 +185,9 @@ namespace winstd }; + /// + /// Deleter for unique_ptr to EAP_ERROR using EapHostPeerFreeErrorMemory + /// struct WINSTD_API EapHostPeerFreeErrorMemory_delete { /// @@ -228,6 +198,8 @@ namespace winstd /// /// Delete a pointer /// + /// \sa [EapHostPeerFreeErrorMemory function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363557.aspx) + /// void operator()(EAP_ERROR *_Ptr) const { EapHostPeerFreeErrorMemory(_Ptr); @@ -235,24 +207,32 @@ namespace winstd }; - struct WINSTD_API EapHostPeerFreeEapError_delete + /// + /// Deleter for unique_ptr to EAP_ERROR using EapHostPeerFreeEapError + /// + struct WINSTD_API EapHostPeerFreeEapError_delete { /// /// Default constructor /// - EapHostPeerFreeEapError_delete() {} + EapHostPeerFreeEapError_delete() {} /// /// Delete a pointer /// + /// \sa [EapHostPeerFreeEapError function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363556.aspx) + /// void operator()(EAP_ERROR *_Ptr) const { - EapHostPeerFreeEapError(_Ptr); + EapHostPeerFreeEapError(_Ptr); } }; - class WINSTD_API __declspec(novtable) eap_attr : public EAP_ATTRIBUTE + /// + /// EAP_ATTRIBUTE wrapper class + /// + class WINSTD_API WINSTD_NOVTABLE eap_attr : public EAP_ATTRIBUTE { public: /// @@ -353,11 +333,14 @@ namespace winstd void create_ms_mppe_key(_In_ BYTE bVendorType, _In_count_(nKeySize) LPCBYTE pbKey, _In_ BYTE nKeySize); public: - static const EAP_ATTRIBUTE blank; + static const EAP_ATTRIBUTE blank; ///< Blank EAP attribute }; - class WINSTD_API __declspec(novtable) eap_method_prop : public EAP_METHOD_PROPERTY + /// + /// EAP_METHOD_PROPERTY wrapper class + /// + class WINSTD_API WINSTD_NOVTABLE eap_method_prop : public EAP_METHOD_PROPERTY { public: /// @@ -406,6 +389,9 @@ namespace winstd }; + /// + /// EapPacket wrapper class + /// class WINSTD_API eap_packet : public dplhandle { DPLHANDLE_IMPL(eap_packet) @@ -471,7 +457,10 @@ namespace winstd }; - class WINSTD_API __declspec(novtable) eap_method_info_array : public EAP_METHOD_INFO_ARRAY + /// + /// EAP_METHOD_INFO_ARRAY wrapper class + /// + class WINSTD_API WINSTD_NOVTABLE eap_method_info_array : public EAP_METHOD_INFO_ARRAY { WINSTD_NONCOPYABLE(eap_method_info_array) @@ -522,11 +511,25 @@ namespace winstd } protected: + /// \cond internal void free_internal(); static void free_internal(_In_ EAP_METHOD_INFO *pMethodInfo); + /// \endcond }; + /// @} + /// + /// \defgroup WinStdExceptions Exceptions + /// Additional exceptions + /// + /// @{ + + /// + /// EapHost runtime error + /// + /// \sa [EAP_ERROR structure](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363699.aspx) + /// class WINSTD_API eap_runtime_error : public win_runtime_error { public: @@ -643,6 +646,8 @@ namespace winstd GUID m_help_link_id; ///< A unique ID that maps to a localizable string that specifies an URL for a page that contains additional information about an error or repair message }; + + /// @} } diff --git a/include/WinStd/ETW.h b/include/WinStd/ETW.h index 78880a8d..c5f68a09 100644 --- a/include/WinStd/ETW.h +++ b/include/WinStd/ETW.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdETWAPI Event Tracing for Windows API +/// Integrates WinStd classes with Event Tracing for Windows API +/// + #include "Common.h" #include @@ -32,57 +37,14 @@ namespace winstd { - /// - /// \defgroup WinStdETWAPI Event Tracing for Windows API - /// Integrates WinStd classes with Event Tracing for Windows API - /// - /// @{ - - /// - /// EVENT_DATA_DESCRIPTOR wrapper - /// - class WINSTD_API __declspec(novtable) event_data; - - /// - /// EVENT_RECORD wrapper - /// - class WINSTD_API __declspec(novtable) event_rec; - - /// - /// ETW event provider - /// + class WINSTD_API WINSTD_NOVTABLE event_data; + class WINSTD_API WINSTD_NOVTABLE event_rec; class WINSTD_API event_provider; - - /// - /// ETW session - /// class WINSTD_API event_session; - - /// - /// ETW trace - /// class WINSTD_API event_trace; - - /// - /// Helper class to enable event provider in constructor and disables it in destructor - /// class WINSTD_API event_trace_enabler; - - /// - /// Helper class to write an event on entry/exit of scope. - /// - /// It writes one string event at creation and another at destruction. - /// - class event_fn_auto; - - /// - /// Helper template to write an event on entry/exit of scope with one parameter (typically result). - /// - /// It writes one string event at creation and another at destruction, with allowing one sprintf type parameter for string event at destruction. - /// + class WINSTD_API event_fn_auto; template class event_fn_auto_ret; - - /// @} } /// \addtogroup WinStdCryptoAPI @@ -116,7 +78,13 @@ template inline ULONG TdhGetProperty(_In_ PEVENT_RECORD pE namespace winstd { - class WINSTD_API __declspec(novtable) event_data : public EVENT_DATA_DESCRIPTOR + /// \addtogroup WinStdETWAPI + /// @{ + + /// + /// EVENT_DATA_DESCRIPTOR wrapper + /// + class WINSTD_API WINSTD_NOVTABLE event_data : public EVENT_DATA_DESCRIPTOR { public: /// @@ -228,7 +196,10 @@ namespace winstd }; - class WINSTD_API __declspec(novtable) event_rec : public EVENT_RECORD + /// + /// EVENT_RECORD wrapper + /// + class WINSTD_API WINSTD_NOVTABLE event_rec : public EVENT_RECORD { public: /// @@ -367,6 +338,9 @@ namespace winstd }; + /// + /// ETW event provider + /// class WINSTD_API event_provider : public handle { HANDLE_IMPL(event_provider) @@ -549,6 +523,9 @@ namespace winstd }; + /// + /// ETW session + /// class WINSTD_API event_session : public handle { WINSTD_NONCOPYABLE(event_session) @@ -733,6 +710,9 @@ namespace winstd }; + /// + /// ETW trace + /// class WINSTD_API event_trace : public handle { HANDLE_IMPL(event_trace) @@ -775,6 +755,9 @@ namespace winstd }; + /// + /// Helper class to enable event provider in constructor and disables it in destructor + /// class WINSTD_API event_trace_enabler { public: @@ -880,7 +863,12 @@ namespace winstd }; - class event_fn_auto + /// + /// Helper class to write an event on entry/exit of scope. + /// + /// It writes one string event at creation and another at destruction. + /// + class WINSTD_API event_fn_auto { public: /// @@ -966,6 +954,11 @@ namespace winstd }; + /// + /// Helper template to write an event on entry/exit of scope with one parameter (typically result). + /// + /// It writes one string event at creation and another at destruction, with allowing one sprintf type parameter for string event at destruction. + /// template class event_fn_auto_ret { @@ -1059,6 +1052,8 @@ namespace winstd EVENT_DATA_DESCRIPTOR m_desc[2]; ///< Function name and return value T &m_result; ///< Function result }; + + /// @} } diff --git a/include/WinStd/Hex.h b/include/WinStd/Hex.h index 56c8829f..8c43e7d6 100644 --- a/include/WinStd/Hex.h +++ b/include/WinStd/Hex.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdHexadecimal Hexadecimal conversion +/// Provides Hexadecimal conversion for WinStd classes +/// + #include "Common.h" #include @@ -25,23 +30,8 @@ namespace winstd { - /// - /// \defgroup WinStdHexadecimal Hexadecimal conversion - /// Provides Hexadecimal conversion for WinStd classes - /// - /// @{ - - /// - /// Hexadecimal encoding session - /// class WINSTD_API hex_enc; - - /// - /// Hexadecimal decoding session - /// class WINSTD_API hex_dec; - - /// @} } #pragma once @@ -49,6 +39,12 @@ namespace winstd namespace winstd { + /// \addtogroup WinStdHexadecimal + /// @{ + + /// + /// Hexadecimal encoding session + /// class WINSTD_API hex_enc { public: @@ -102,6 +98,9 @@ namespace winstd }; + /// + /// Hexadecimal decoding session + /// class WINSTD_API hex_dec { public: @@ -186,4 +185,6 @@ namespace winstd unsigned char buf; ///< Internal buffer size_t num; ///< Number of nibbles used in `buf` }; + + /// @} } diff --git a/include/WinStd/MSI.h b/include/WinStd/MSI.h index a826e231..963a1c78 100644 --- a/include/WinStd/MSI.h +++ b/include/WinStd/MSI.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdMSIAPI Microsoft Installer API +/// Integrates WinStd classes with Microsoft Installer API +/// + #include "Common.h" #include @@ -25,17 +30,10 @@ #include #include -/// -/// \defgroup WinStdMSIAPI Microsoft Installer API -/// Integrates WinStd classes with Microsoft Installer API -/// +/// \addtogroup WinStdMSIAPI /// @{ -/// -/// Gets the value for an installer property and stores it in a std::string string. -/// -/// \sa [MsiGetProperty function](https://msdn.microsoft.com/en-us/library/aa370134.aspx) -/// +/// @copydoc MsiGetPropertyW() template inline UINT MsiGetPropertyA(_In_ MSIHANDLE hInstall, _In_ LPCSTR szName, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -45,11 +43,7 @@ template inline UINT MsiGetPropertyA(_In_ /// template inline UINT MsiGetPropertyW(_In_ MSIHANDLE hInstall, _In_ LPCWSTR szName, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Returns the string value of a record field and stores it in a std::string string. -/// -/// \sa [MsiRecordGetString function](https://msdn.microsoft.com/en-us/library/aa370368.aspx) -/// +/// @copydoc MsiRecordGetStringW() template inline UINT MsiRecordGetStringA(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -59,11 +53,7 @@ template inline UINT MsiRecordGetStringA( /// template inline UINT MsiRecordGetStringW(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Formats record field data and properties using a format string and stores it in a std::string string. -/// -/// \sa [MsiFormatRecord function](https://msdn.microsoft.com/en-us/library/aa370109.aspx) -/// +/// @copydoc MsiFormatRecordW() template inline UINT MsiFormatRecordA(MSIHANDLE hInstall, MSIHANDLE hRecord, std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -80,11 +70,7 @@ template inline UINT MsiFormatRecordW(MSI /// template inline UINT MsiRecordReadStream(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ std::vector<_Ty, _Ax> &binData); -/// -/// Returns the full target path for a folder in the Directory table and stores it in a std::string string. -/// -/// \sa [MsiGetTargetPath function](https://msdn.microsoft.com/en-us/library/aa370303.aspx) -/// +/// @copydoc MsiGetTargetPathW() template inline UINT MsiGetTargetPathA(_In_ MSIHANDLE hInstall, _In_ LPCSTR szFolder, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -94,11 +80,7 @@ template inline UINT MsiGetTargetPathA(_I /// template inline UINT MsiGetTargetPathW(_In_ MSIHANDLE hInstall, _In_ LPCWSTR szFolder, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Returns the full path to an installed component. If the key path for the component is a registry key then the registry key is returned. -/// -/// \sa [MsiGetComponentPath function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa370112.aspx) -/// +/// @copydoc MsiGetComponentPathW() template inline INSTALLSTATE MsiGetComponentPathA(_In_ LPCSTR szProduct, _In_ LPCSTR szComponent, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// diff --git a/include/WinStd/Sec.h b/include/WinStd/Sec.h index 39e11a53..5bb6e78c 100644 --- a/include/WinStd/Sec.h +++ b/include/WinStd/Sec.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdSecurityAPI Security API +/// Integrates WinStd classes with Microsoft Security API +/// + #include "Common.h" #include @@ -26,53 +31,16 @@ namespace winstd { - /// - /// \defgroup WinStdSecurityAPI Security API - /// Integrates WinStd classes with Microsoft Security API - /// - /// @{ - - /// - /// PCredHandle wrapper class - /// class WINSTD_API sec_credentials; - - /// - /// PCtxtHandle wrapper class - /// class WINSTD_API sec_context; - - /// - /// SecBufferDesc wrapper class - /// class WINSTD_API sec_buffer_desc; - - /// @} - - /// - /// \defgroup WinStdExceptions Exceptions - /// Additional exceptions - /// - /// @{ - - /// - /// Security runtime error - /// - /// \note Must be defined as derived class from num_runtime_error<> to allow correct type info for dynamic typecasting and prevent folding with other derivates of num_runtime_error<>. - /// class WINSTD_API sec_runtime_error; - - /// @} } /// \addtogroup WinStdSecurityAPI /// @{ -/// -/// Retrieves the name of the user or other security principal associated with the calling thread and stores it in a std::string string. -/// -/// \sa [GetUserNameEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724435.aspx) -/// +/// @copydoc GetUserNameExW() template BOOLEAN GetUserNameExA(_In_ EXTENDED_NAME_FORMAT NameFormat, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sName); /// @@ -89,6 +57,12 @@ template BOOLEAN GetUserNameExW(_In_ EXTE namespace winstd { + /// \addtogroup WinStdSecurityAPI + /// @{ + + /// + /// PCredHandle wrapper class + /// class WINSTD_API sec_credentials : public handle { WINSTD_NONCOPYABLE(sec_credentials) @@ -105,8 +79,8 @@ namespace winstd /// /// Initializes a new class with an already available object handle. /// - /// \param[in] h Initial class handle value - /// \param[in] prop Credentials expiration + /// \param[in] h Initial class handle value + /// \param[in] expires Credentials expiration /// inline sec_credentials(_In_opt_ handle_type h, _In_ const TimeStamp expires) : m_expires(expires), @@ -188,6 +162,9 @@ namespace winstd }; + /// + /// PCtxtHandle wrapper class + /// class WINSTD_API sec_context : public handle { public: @@ -299,6 +276,9 @@ namespace winstd }; + /// + /// SecBufferDesc wrapper class + /// class WINSTD_API sec_buffer_desc : public SecBufferDesc { public: @@ -320,15 +300,27 @@ namespace winstd virtual ~sec_buffer_desc(); }; + /// @} + /// + /// \defgroup WinStdExceptions Exceptions + /// Additional exceptions + /// + /// @{ + + /// + /// Security runtime error + /// + /// \note Must be defined as derived class from num_runtime_error<> to allow correct type info for dynamic typecasting and prevent folding with other derivates of num_runtime_error<>. + /// class WINSTD_API sec_runtime_error : public num_runtime_error { public: /// /// Constructs an exception /// - /// \param[in] error Security provider error code - /// \param[in] msg Error message + /// \param[in] num Security provider error code + /// \param[in] msg Error message /// inline sec_runtime_error(_In_ error_type num, _In_ const std::string& msg) : num_runtime_error(num, msg.c_str()) { @@ -355,6 +347,8 @@ namespace winstd { } }; + + /// @} } diff --git a/include/WinStd/Shell.h b/include/WinStd/Shell.h index 1d09c559..3afbdb3a 100644 --- a/include/WinStd/Shell.h +++ b/include/WinStd/Shell.h @@ -18,23 +18,20 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdShellWAPI Shell API +/// Integrates WinStd classes with Microsoft Shell API +/// #include "Common.h" #include #include -/// -/// \defgroup WinStdShellWAPI Shell API -/// Integrates WinStd classes with Microsoft Shell API -/// +/// \addtogroup WinStdShellWAPI /// @{ -/// -/// Simplifies a path by removing navigation elements such as "." and ".." to produce a direct, well-formed path, and stores it in a std::string string. -/// -/// \sa [PathCanonicalize function](https://msdn.microsoft.com/en-us/library/windows/desktop/bb773569.aspx) -/// +/// @copydoc PathCanonicalizeW() template inline BOOL PathCanonicalizeA(__out std::basic_string<_Elem, _Traits, _Ax> &sValue, __in LPCSTR pszPath); /// diff --git a/include/WinStd/WLAN.h b/include/WinStd/WLAN.h index e7a62061..a5f75f1f 100644 --- a/include/WinStd/WLAN.h +++ b/include/WinStd/WLAN.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdWLANAPI WLAN API +/// Integrates WinStd classes with Microsoft WLAN API +/// + #include "Common.h" #include @@ -28,36 +33,22 @@ // without a WLAN interface. extern DWORD (WINAPI *pfnWlanReasonCodeToString)(__in DWORD dwReasonCode, __in DWORD dwBufferSize, __in_ecount(dwBufferSize) PWCHAR pStringBuffer, __reserved PVOID pReserved); -/// -/// \defgroup WinStdWLANAPI WLAN API -/// Integrates WinStd classes with Microsoft WLAN API -/// -/// @{ - namespace winstd { - /// - /// Deleter for unique_ptr using WlanFreeMemory - /// template struct WlanFreeMemory_delete; - - /// - /// Deleter for unique_ptr to array of unknown size using WlanFreeMemory - /// template struct WlanFreeMemory_delete<_Ty[]>; - - /// - /// WLAN handle wrapper - /// class WINSTD_API wlan_handle; } +/// \addtogroup WinStdWLANAPI +/// @{ + /// /// Retrieves a string that describes a specified reason code and stores it in a std::wstring string. /// /// \sa [WlanReasonCodeToString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms706768.aspx) /// /// \note -/// Since Wlanapi.dll is not always present, the \c pfnWlanReasonCodeToString pointer to \c WlanReasonCodeToString +/// Since Wlanapi.dll is not always present, the `pfnWlanReasonCodeToString` pointer to `WlanReasonCodeToString()` /// function must be loaded dynamically. /// template inline DWORD WlanReasonCodeToString(_In_ DWORD dwReasonCode, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue, __reserved PVOID pReserved); @@ -69,6 +60,12 @@ template inline DWORD WlanReasonCodeToStr namespace winstd { + /// \addtogroup WinStdWLANAPI + /// @{ + + /// + /// Deleter for unique_ptr using WlanFreeMemory + /// template struct WlanFreeMemory_delete { typedef WlanFreeMemory_delete<_Ty> _Myt; ///< This type @@ -93,6 +90,9 @@ namespace winstd }; + /// + /// Deleter for unique_ptr to array of unknown size using WlanFreeMemory + /// template struct WlanFreeMemory_delete<_Ty[]> { typedef WlanFreeMemory_delete<_Ty> _Myt; ///< This type @@ -121,6 +121,9 @@ namespace winstd }; + /// + /// WLAN handle wrapper + /// class WINSTD_API wlan_handle : public handle { HANDLE_IMPL(wlan_handle) @@ -163,6 +166,8 @@ namespace winstd /// virtual void free_internal(); }; + + /// @} } diff --git a/include/WinStd/Win.h b/include/WinStd/Win.h index 0ee295aa..503c8359 100644 --- a/include/WinStd/Win.h +++ b/include/WinStd/Win.h @@ -18,6 +18,11 @@ along with Setup. If not, see . */ +/// +/// \defgroup WinStdWinAPI Windows API +/// Integrates WinStd classes with Microsoft Windows API +/// + #include "Common.h" #include @@ -27,69 +32,22 @@ namespace winstd { - /// - /// \defgroup WinStdWinAPI Windows API - /// Integrates WinStd classes with Microsoft Windows API - /// - /// @{ - - /// - /// Windows HANDLE wrapper class - /// class WINSTD_API win_handle; - - /// - /// Module handle wrapper - /// class WINSTD_API library; - - /// - /// Process handle wrapper - /// class WINSTD_API process; - - /// - /// Heap handle wrapper - /// class WINSTD_API heap; - - /// - /// HeapAlloc allocator - /// template class heap_allocator; - - /// - /// Activates given activation context in constructor and deactivates it in destructor - /// class WINSTD_API actctx_activator; - - /// - /// Lets the calling thread impersonate the security context of a logged-on user - /// class WINSTD_API user_impersonator; - - /// - /// Memory in virtual address space of a process handle wrapper - /// class WINSTD_API vmemory; - - /// - /// Registry wrapper class - /// class WINSTD_API reg_key; - - /// @} } /// \addtogroup WinStdWinAPI /// @{ -/// -/// Retrieves the fully qualified path for the file that contains the specified module and stores it in a std::string string. -/// -/// \sa [GetModuleFileName function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms683197.aspx) -/// +/// @copydoc GetModuleFileNameW() template inline DWORD GetModuleFileNameA(_In_opt_ HMODULE hModule, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -99,11 +57,7 @@ template inline DWORD GetModuleFileNameA( /// template inline DWORD GetModuleFileNameW(_In_opt_ HMODULE hModule, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Copies the text of the specified window's title bar (if it has one) into a std::string string. -/// -/// \sa [GetWindowText function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms633520.aspx) -/// +/// @copydoc GetWindowTextW() template inline int GetWindowTextA(_In_ HWND hWnd, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); /// @@ -113,11 +67,7 @@ template inline int GetWindowTextA(_In_ H /// template inline int GetWindowTextW(_In_ HWND hWnd, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Retrieves version information for the specified file and stores it in a std::vector buffer. -/// -/// \sa [GetFileVersionInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms647003.aspx) -/// +/// @copydoc GetFileVersionInfoW() template inline BOOL GetFileVersionInfoA(_In_ LPCSTR lptstrFilename, __reserved DWORD dwHandle, _Out_ std::vector<_Ty, _Ax> &aValue); /// @@ -127,12 +77,8 @@ template inline BOOL GetFileVersionInfoA(_In_ LPCSTR lptst /// template inline BOOL GetFileVersionInfoW(_In_ LPCWSTR lptstrFilename, __reserved DWORD dwHandle, _Out_ std::vector<_Ty, _Ax> &aValue); -/// -/// Expands environment-variable strings, replaces them with the values defined for the current user, and stores it in a std::string string. -/// -/// \sa [ExpandEnvironmentStrings function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724265.aspx) -/// -template inline DWORD ExpandEnvironmentStringsW(_In_ LPCSTR lpSrc, std::basic_string<_Elem, _Traits, _Ax> &sValue); +/// @copydoc ExpandEnvironmentStringsW() +template inline DWORD ExpandEnvironmentStringsA(_In_ LPCSTR lpSrc, std::basic_string<_Elem, _Traits, _Ax> &sValue); /// /// Expands environment-variable strings, replaces them with the values defined for the current user, and stores it in a std::wstring string. @@ -141,12 +87,7 @@ template inline DWORD ExpandEnvironmentSt /// template inline DWORD ExpandEnvironmentStringsW(_In_ LPCWSTR lpSrc, std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Formats GUID and stores it in a std::string string. -/// -/// \param[in ] lpGuid Pointer to GUID -/// \param[out] str String to store the result to -/// +/// @copydoc GuidToStringW() template inline VOID GuidToStringA(_In_ LPCGUID lpGuid, _Out_ std::basic_string<_Elem, _Traits, _Ax> &str); /// @@ -156,28 +97,29 @@ template inline VOID GuidToStringA(_In_ L /// \param[out] str String to store the result to /// template inline VOID GuidToStringW(_In_ LPCGUID lpGuid, _Out_ std::basic_string<_Elem, _Traits, _Ax> &str); +/// @copydoc GuidToStringW() #ifdef _UNICODE #define GuidToString GuidToStringW #else #define GuidToString GuidToStringA #endif -/// -/// Parses string with GUID and stores it to GUID -/// -/// \param[in ] lpszGuid String with GUID -/// \param[out] lpGuid GUID to store the result to -/// -BOOL WINSTD_API StringToGuidA(_In_z_ LPCSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_ LPCSTR *lpszGuidEnd = NULL); +/// @copydoc StringToGuidW() +BOOL WINSTD_API StringToGuidA(_In_z_ LPCSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_opt_ LPCSTR *lpszGuidEnd = NULL); /// /// Parses string with GUID and stores it to GUID /// -/// \param[in ] lpszGuid String with GUID -/// \param[out] lpGuid GUID to store the result to +/// \param[in ] lpszGuid String with GUID +/// \param[out] lpGuid GUID to store the result to +/// \param[out] lpszGuidEnd If non-NULL the pointer to the end of parsed GUID within `lpszGuid` is returned /// -BOOL WINSTD_API StringToGuidW(_In_z_ LPCWSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_ LPCWSTR *lpszGuidEnd = NULL); - +/// \returns +/// - `TRUE` if GUID successfuly parsed; +/// - `FALSE` otherwise. +/// +BOOL WINSTD_API StringToGuidW(_In_z_ LPCWSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_opt_ LPCWSTR *lpszGuidEnd = NULL); +/// @copydoc StringToGuidW() #ifdef _UNICODE #define StringToGuid StringToGuidW #else @@ -224,11 +166,7 @@ template inline LSTATUS RegQueryStringVal /// template inline LSTATUS RegQueryStringValue(_In_ HKEY hReg, _In_z_ LPCWSTR pszName, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sValue); -/// -/// Retrieves the type and data for the specified value name associated with an open registry key and stores the data in a std::vector buffer. -/// -/// \sa [RegQueryValueEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724911.aspx) -/// +/// @copydoc RegQueryValueExW() template inline LSTATUS RegQueryValueExA(_In_ HKEY hKey, _In_opt_ LPCSTR lpValueName, __reserved LPDWORD lpReserved, _Out_opt_ LPDWORD lpType, _Out_ std::vector<_Ty, _Ax> &aData); /// @@ -240,11 +178,7 @@ template inline LSTATUS RegQueryValueExW(_In_ HKEY hKey, _ #if _WIN32_WINNT >= _WIN32_WINNT_VISTA -/// -/// Loads the specified string from the specified key and subkey, and stores it in a std::string string. -/// -/// \sa [RegLoadMUIString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724890.aspx) -/// +/// @copydoc RegLoadMUIStringW() template inline LSTATUS RegLoadMUIStringA(_In_ HKEY hKey, _In_opt_ LPCSTR pszValue, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sOut, _In_ DWORD Flags, _In_opt_ LPCSTR pszDirectory); /// @@ -270,19 +204,15 @@ template inline int WideCharToMultiByte(_ /// template inline int MultiByteToWideChar(_In_ UINT CodePage, _In_ DWORD dwFlags, _In_z_count_(cbMultiByte) LPCSTR lpMultiByteStr, _In_ int cbMultiByte, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sWideCharStr); -/// -/// Loads a string resource from the executable file associated with a specified module. -/// -/// \sa [LoadString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms647486.aspx) -/// -template inline int WINAPI LoadString(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer); +/// @copydoc LoadStringW +template inline int WINAPI LoadStringA(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer); /// /// Loads a string resource from the executable file associated with a specified module. /// /// \sa [LoadString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms647486.aspx) /// -template inline int WINAPI LoadString(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer); +template inline int WINAPI LoadStringW(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer); /// /// Formats and sends a string to the debugger for display. @@ -312,11 +242,7 @@ inline VOID OutputDebugStr(_In_ LPCSTR lpOutputString, ...); /// inline VOID OutputDebugStr(_In_ LPCWSTR lpOutputString, ...); -/// -/// Formats a date as a date string for a locale specified by the locale identifier. The function formats either a specified date or the local system date. -/// -/// \sa [GetDateFormat function](https://msdn.microsoft.com/en-us/library/windows/desktop/dd318086.aspx) -/// +/// @copydoc GetDateFormatW() template inline int GetDateFormatA(_In_ LCID Locale, _In_ DWORD dwFlags, _In_opt_ const SYSTEMTIME *lpDate, _In_opt_ LPCSTR lpFormat, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sDate); /// @@ -326,11 +252,7 @@ template inline int GetDateFormatA(_In_ L /// template inline int GetDateFormatW(_In_ LCID Locale, _In_ DWORD dwFlags, _In_opt_ const SYSTEMTIME *lpDate, _In_opt_ LPCWSTR lpFormat, _Out_ std::basic_string<_Elem, _Traits, _Ax> &sDate); -/// -/// Retrieves the name of the account for this SID and the name of the first domain on which this SID is found. -/// -/// \sa [LookupAccountSid function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379166.aspx) -/// +/// @copydoc LookupAccountSidW() template inline BOOL LookupAccountSidA(_In_opt_ LPCSTR lpSystemName, _In_ PSID lpSid, _Out_opt_ std::basic_string<_Elem, _Traits, _Ax> *sName, _Out_opt_ std::basic_string<_Elem, _Traits, _Ax> *sReferencedDomainName, _Out_ PSID_NAME_USE peUse); /// @@ -347,6 +269,12 @@ template inline BOOL LookupAccountSidW(_I namespace winstd { + /// \addtogroup WinStdWinAPI + /// @{ + + /// + /// Windows HANDLE wrapper class + /// class WINSTD_API win_handle : public handle { HANDLE_IMPL(win_handle) @@ -369,6 +297,9 @@ namespace winstd }; + /// + /// Module handle wrapper + /// class WINSTD_API library : public handle { HANDLE_IMPL(library) @@ -410,6 +341,9 @@ namespace winstd }; + /// + /// Process handle wrapper + /// class WINSTD_API process : public win_handle { public: @@ -434,6 +368,9 @@ namespace winstd }; + /// + /// Heap handle wrapper + /// class WINSTD_API heap : public handle { HANDLE_IMPL(heap) @@ -484,24 +421,30 @@ namespace winstd }; + /// + /// HeapAlloc allocator + /// template class heap_allocator { public: - typedef typename _Ty value_type; + typedef typename _Ty value_type; ///< A type that is managed by the allocator - typedef _Ty *pointer; - typedef _Ty& reference; - typedef const _Ty *const_pointer; - typedef const _Ty& const_reference; + typedef _Ty *pointer; ///< A type that provides a pointer to the type of object managed by the allocator + typedef _Ty& reference; ///< A type that provides a reference to the type of object managed by the allocator + typedef const _Ty *const_pointer; ///< A type that provides a constant pointer to the type of object managed by the allocator + typedef const _Ty& const_reference; ///< A type that provides a constant reference to type of object managed by the allocator - typedef SIZE_T size_type; - typedef ptrdiff_t difference_type; + typedef SIZE_T size_type; ///< An unsigned integral type that can represent the length of any sequence that an object of template class `heap_allocator` can allocate + typedef ptrdiff_t difference_type; ///< A signed integral type that can represent the difference between values of pointers to the type of object managed by the allocator + /// + /// A structure that enables an allocator for objects of one type to allocate storage for objects of another type. + /// template struct rebind { - typedef heap_allocator<_Other> other; + typedef heap_allocator<_Other> other; ///< Other allocator type }; public: @@ -591,10 +534,13 @@ namespace winstd } public: - HANDLE m_heap; + HANDLE m_heap; ///< Heap handle }; + /// + /// Activates given activation context in constructor and deactivates it in destructor + /// class WINSTD_API actctx_activator { public: @@ -619,6 +565,9 @@ namespace winstd }; + /// + /// Lets the calling thread impersonate the security context of a logged-on user + /// class WINSTD_API user_impersonator { public: @@ -643,6 +592,9 @@ namespace winstd }; + /// + /// Memory in virtual address space of a process handle wrapper + /// class WINSTD_API vmemory : public handle { WINSTD_NONCOPYABLE(vmemory) @@ -752,6 +704,9 @@ namespace winstd }; + /// + /// Registry wrapper class + /// class WINSTD_API reg_key : public handle { HANDLE_IMPL(reg_key) @@ -827,6 +782,8 @@ namespace winstd /// virtual void free_internal(); }; + + /// @} } @@ -973,7 +930,7 @@ inline BOOL GetFileVersionInfoW(_In_ LPCWSTR lptstrFilename, __reserved DWORD dw template -inline DWORD ExpandEnvironmentStringsW(_In_ LPCSTR lpSrc, std::basic_string<_Elem, _Traits, _Ax> &sValue) +inline DWORD ExpandEnvironmentStringsA(_In_ LPCSTR lpSrc, std::basic_string<_Elem, _Traits, _Ax> &sValue) { assert(0); // TODO: Test this code. @@ -1281,7 +1238,7 @@ inline int MultiByteToWideChar(_In_ UINT CodePage, _In_ DWORD dwFlags, _In_z_cou template -inline int WINAPI LoadString(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer) +inline int WINAPI LoadStringA(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer) { // Get read-only pointer to string resource. LPCSTR pszStr; @@ -1295,7 +1252,7 @@ inline int WINAPI LoadString(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ template -inline int WINAPI LoadString(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer) +inline int WINAPI LoadStringW(_In_opt_ HINSTANCE hInstance, _In_ UINT uID, _Out_ std::basic_string &sBuffer) { // Get read-only pointer to string resource. LPCWSTR pszStr; diff --git a/src/Base64.cpp b/src/Base64.cpp index c3f51bf4..6e9c1d2e 100644 --- a/src/Base64.cpp +++ b/src/Base64.cpp @@ -25,18 +25,21 @@ // winstd::base64_enc ////////////////////////////////////////////////////////////////////// +/// \cond internal const char winstd::base64_enc::lookup[64] = { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', '/' }; +/// \endcond ////////////////////////////////////////////////////////////////////// // winstd::base64_dec ////////////////////////////////////////////////////////////////////// +/// \cond internal const unsigned char winstd::base64_dec::lookup[256] = { /* 0 1 2 3 4 5 6 7 8 9 A B C D E F */ /* 0 */ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, @@ -56,3 +59,4 @@ const unsigned char winstd::base64_dec::lookup[256] = { /* E */ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, /* F */ 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255 }; +/// \endcond diff --git a/src/EAP.cpp b/src/EAP.cpp index 73f8e4cc..e195cc89 100644 --- a/src/EAP.cpp +++ b/src/EAP.cpp @@ -114,6 +114,8 @@ winstd::eap_method_info_array::~eap_method_info_array() } +/// \cond internal + void winstd::eap_method_info_array::free_internal() { for (DWORD i = 0; i < dwNumberOfMethods; i++) @@ -131,3 +133,5 @@ void winstd::eap_method_info_array::free_internal(_In_ EAP_METHOD_INFO *pMethodI EapHostPeerFreeMemory((BYTE*)pMethodInfo->pwszAuthorName); EapHostPeerFreeMemory((BYTE*)pMethodInfo->pwszFriendlyName); } + +/// \endcond diff --git a/src/Win.cpp b/src/Win.cpp index 23e652ea..97e2ba68 100644 --- a/src/Win.cpp +++ b/src/Win.cpp @@ -25,7 +25,7 @@ // StringToGuidA ////////////////////////////////////////////////////////////////////// -BOOL WINSTD_API StringToGuidA(_In_z_ LPCSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_ LPCSTR *lpszGuidEnd) +BOOL WINSTD_API StringToGuidA(_In_z_ LPCSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_opt_ LPCSTR *lpszGuidEnd) { GUID g; LPSTR lpszEnd; @@ -88,7 +88,7 @@ BOOL WINSTD_API StringToGuidA(_In_z_ LPCSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_ } -BOOL WINSTD_API StringToGuidW(_In_z_ LPCWSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_ LPCWSTR *lpszGuidEnd) +BOOL WINSTD_API StringToGuidW(_In_z_ LPCWSTR lpszGuid, _Out_ LPGUID lpGuid, _Out_opt_ LPCWSTR *lpszGuidEnd) { GUID g; LPWSTR lpszEnd;