Amebis/atlex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doxygen source annotation added

Browse Source
This commit is contained in:
Simon Rozman
2015-10-10 19:54:30 +02:00
parent 0ff5587137
commit 6dbd4151b7
8 changed files with 850 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

497
include/atlex.h
View File

@@ -26,191 +26,213 @@
namespace ATL
{
/**
* Base abstract template class to support generic object handle keeping
* It provides basic operators and methods to ease the replacement of native object handle type with this template class and its descendands.
*/
///
/// \defgroup ATLSysHandles 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 T> class CObjectWithHandleT
{
public:
/**
* Datatype of the object handle this template class handles
*/
///
/// Datatype of the object handle this template class handles
///
typedef T HANDLE;
/**\name Constructors */
/**@{*/
/**
* The default constructor
* Sets the object handle to NULL.
*/
inline CObjectWithHandleT() throw() : m_h(NULL)
///
/// Initializes a new class instance with the object handle set to NULL.
///
inline CObjectWithHandleT() : m_h(NULL)
{
}
/**
*\param h Initial object handle value
*/
inline CObjectWithHandleT(_In_opt_ HANDLE h) throw() : m_h(h)
///
/// Initializes a new class instance with an available object handle.
///
/// \param[in] h Initial object handle value
///
inline CObjectWithHandleT(_In_opt_ HANDLE h) : m_h(h)
{
}
/**@}*/
/**\name Operators to allow transparent use of this class */
/**@{*/
/**
* Auto-typecasting operator
*\return Object handle
*/
inline operator HANDLE() const throw()
/// \name Operators for transparent usage of this class
/// @{
///
/// Auto-typecasting operator
///
/// \return Object handle
///
inline operator HANDLE() const
{
return m_h;
}
/**
* Operator to return object handle value when the object handle is a pointer to a value (class, struct, etc.)
*\return Object handle value
*/
///
/// Returns the object handle value when the object handle is a pointer to a value (class, struct, etc.).
///
/// \return Object handle value
///
inline HANDLE*& operator*() const
{
ATLENSURE(m_h != NULL);
return *m_h;
}
/**
* Operator to return object handle reference
*\return Object handle reference
*/
inline HANDLE* operator&() throw()
///
/// Returns the object handle reference.
/// \return Object handle reference
///
inline HANDLE* operator&()
{
ATLASSERT(m_h == NULL);
return &m_h;
}
/**
* Operator for object handle member access when the object handle is a pointer to a class or struct
*\return Object handle
*/
inline HANDLE operator->() const throw()
///
/// Provides object handle member access when the object handle is a pointer to a class or struct.
///
/// \return Object handle
///
inline HANDLE operator->() const
{
ATLASSERT(m_h != NULL);
return m_h;
}
/**@}*/
/**
* Test if the object handle is NULL
*\return
* - Non zero when object handle is NULL;
* - Zero otherwise.
*/
inline bool operator!() const throw()
/// @}
/// \name Comparison operators
/// @{
///
/// Tests if the object handle is NULL.
///
/// \return
/// - Non zero when object handle is NULL;
/// - Zero otherwise.
///
inline bool operator!() const
{
return m_h == NULL;
}
/**\name Comparison operators */
/**@{*/
/**
* Is less than
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is less than h;
* - Zero otherwise.
*/
inline bool operator<(_In_opt_ HANDLE h) const throw()
///
/// Is handle less than?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is less than h;
/// - Zero otherwise.
///
inline bool operator<(_In_opt_ HANDLE h) const
{
return m_h < h;
}
/**
* Is less than or equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is less than or equal to h;
* - Zero otherwise.
*/
inline bool operator<=(_In_opt_ HANDLE h) const throw()
///
/// Is handle less than or equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is less than or equal to h;
/// - Zero otherwise.
///
inline bool operator<=(_In_opt_ HANDLE h) const
{
return m_h <= h;
}
/**
* Is greater than or equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is greater than or equal to h;
* - Zero otherwise.
*/
inline bool operator>=(_In_opt_ HANDLE h) const throw()
///
/// Is handle greater than or equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is greater than or equal to h;
/// - Zero otherwise.
///
inline bool operator>=(_In_opt_ HANDLE h) const
{
return m_h >= h;
}
/**
* Is greater than
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is greater than h;
* - Zero otherwise.
*/
inline bool operator>(_In_opt_ HANDLE h) const throw()
///
/// Is handle greater than?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is greater than h;
/// - Zero otherwise.
///
inline bool operator>(_In_opt_ HANDLE h) const
{
return m_h > h;
}
/**
* Is not equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is not equal to h;
* - Zero otherwise.
*/
///
/// Is handle not equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is not equal to h;
/// - Zero otherwise.
///
inline bool operator!=(_In_opt_ HANDLE h) const
{
return !operator==(h);
}
/**
* Is equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is equal to h;
* - Zero otherwise.
*/
inline bool operator==(_In_opt_ HANDLE h) const throw()
///
/// Is handle equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is equal to h;
/// - Zero otherwise.
///
inline bool operator==(_In_opt_ HANDLE h) const
{
return m_h == h;
}
/**@}*/
/**
* Set a new object handle for the class
* When the current object handle of the class is non NULL, the object is destroyed first.
*\param h New object handle
*/
inline void Attach(_In_opt_ HANDLE h) throw()
/// @}
///
/// Sets a new object handle for the class
///
/// When the current object handle of the class is non-NULL, the object is destroyed first.
///
/// \param[in] h New object handle
///
inline void Attach(_In_opt_ HANDLE h)
{
if (m_h)
InternalFree();
m_h = h;
}
/**
* Dismiss the object handle from this class
*\return Object handle
*/
inline HANDLE Detach() throw()
///
/// Dismisses the object handle from this class
///
/// \return Object handle
///
inline HANDLE Detach()
{
HANDLE h = m_h;
m_h = NULL;
return h;
}
/**
* Destroys the object
*/
inline void Free() throw()
///
/// Destroys the object
///
inline void Free()
{
if (m_h) {
InternalFree();
@@ -218,31 +240,45 @@ namespace ATL
}
}
/// @}
protected:
/**
* Abstract method that must be implemented by child classes to do the actual object destruction
*/
///
/// Abstract member function that must be implemented by child classes to do the actual object destruction.
///
virtual void InternalFree() = 0;
protected:
/*** Object handle */
HANDLE m_h;
HANDLE m_h; ///< Object handle
};
//
// CObjectWithHandleDuplT
//
///
/// Base abstract template class to support object handle keeping for objects that support handle duplication
///
template <class T>
class CObjectWithHandleDuplT : public CObjectWithHandleT<T>
{
public:
///
/// Duplicates and returns a new object handle.
///
/// \return Duplicated object handle
///
inline HANDLE GetDuplicate() const
{
return m_h ? InternalDuplicate(m_h) : NULL;
}
inline BOOL DuplicateAndAttach(_In_opt_ HANDLE h) throw()
///
/// Duplicates an object handle and sets a new object handle.
///
/// \param[in] h Object handle of existing object
/// \return
/// - TRUE when duplication succeeds;
/// - FALSE when duplication fails. In case of failure obtaining the extended error information is object type specific (for example: `GetLastError()`).
///
inline BOOL DuplicateAndAttach(_In_opt_ HANDLE h)
{
if (m_h)
InternalFree();
@@ -268,18 +304,46 @@ namespace ATL
//}
protected:
virtual HANDLE InternalDuplicate(HANDLE h) const = 0;
///
/// Abstract member function that must be implemented by child classes to do the actual object handle duplication.
///
/// \param[in] h Object handle of existing object
/// \return Duplicated object handle
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const = 0;
};
/// @}
//
// CStrFormatT, CStrFormatW, CStrFormatA, CStrFormat
//
///
/// \defgroup ATLStrFormat 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)(CStrFormatA("%i is less than %i.\n", 1, 5));
/// \endcode
///
/// @{
///
/// Base template class to support string formatting using `printf()` style templates
///
template<typename BaseType, class StringTraits>
class CStrFormatT : public CStringT<BaseType, StringTraits>
{
public:
CStrFormatT(_In_z_ _FormatMessage_format_string_ PCXSTR pszFormat, ...)
/// \name Initializing string using template in memory
/// @{
///
/// Initializes a new string and formats its contents using `printf()` style template.
///
/// \param[in] pszFormat String template using `printf()` style
///
CStrFormatT(_In_z_ _Printf_format_string_ PCXSTR pszFormat, ...)
{
ATLASSERT(AtlIsValidString(pszFormat));
@@ -289,7 +353,17 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ _FormatMessage_format_string_ UINT nFormatID, ...)
/// @}
/// \name Initializing string using template in resources
/// @{
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(nFormatID));
@@ -300,7 +374,13 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ HINSTANCE hInstance, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ HINSTANCE hInstance, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID));
@@ -311,7 +391,14 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] wLanguageID Resource language
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID, wLanguageID));
@@ -321,20 +408,41 @@ namespace ATL
FormatV(strFormat, argList);
va_end(argList);
}
/// }@
};
///
/// Wide character implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< wchar_t, StrTraitATL< wchar_t, ChTraitsCRT< wchar_t > > > CStrFormatW;
///
/// Single-byte character implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< char, StrTraitATL< char, ChTraitsCRT< char > > > CStrFormatA;
///
/// TCHAR implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< TCHAR, StrTraitATL< TCHAR, ChTraitsCRT< TCHAR > > > CStrFormat;
//
// CStrFormatMsgT, CStrFormatMsgW, CStrFormatMsgA, CStrFormatMsg
//
///
/// Base template class to support string formatting using `FormatMessage()` style templates
///
template<typename BaseType, class StringTraits>
class CStrFormatMsgT : public CStringT<BaseType, StringTraits>
{
public:
/// \name Initializing string using template in memory
/// @{
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template.
///
/// \param[in] pszFormat String template using `FormatMessage()` style
///
CStrFormatMsgT(_In_z_ _FormatMessage_format_string_ PCXSTR pszFormat, ...)
{
ATLASSERT(AtlIsValidString(pszFormat));
@@ -345,7 +453,17 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ _FormatMessage_format_string_ UINT nFormatID, ...)
/// @}
/// \name Initializing string using template in resources
/// @{
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(nFormatID));
@@ -356,7 +474,13 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID));
@@ -367,7 +491,14 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] wLanguageID Resource language
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID, wLanguageID));
@@ -377,32 +508,82 @@ namespace ATL
FormatMessageV(strFormat, &argList);
va_end(argList);
}
/// @}
};
///
/// Wide character implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< wchar_t, StrTraitATL< wchar_t, ChTraitsCRT< wchar_t > > > CStrFormatMsgW;
///
/// Single-byte character implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< char, StrTraitATL< char, ChTraitsCRT< char > > > CStrFormatMsgA;
///
/// TCHAR implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< TCHAR, StrTraitATL< TCHAR, ChTraitsCRT< TCHAR > > > CStrFormatMsg;
/// @}
//
// CParanoidHeap
//
/// \defgroup ATLMemSanitize Auto-sanitize Memory Management
/// Sanitizes memory before dismissed
///
/// @{
///
/// A heap template that sanitizes each memory block before it is destroyed or reallocated
///
/// This template is typcally used to extend one of the base ATL heap management classes.
///
/// \par Example
/// \code
/// CParanoidHeap<CWin32Heap> myHeap;
/// \endcode
///
/// \note
/// CParanoidHeap introduces a performance penalty. However, it provides an additional level of security.
/// Use for security sensitive data memory storage only.
///
/// \sa [Memory Management Classes](https://msdn.microsoft.com/en-us/library/44yh1z4f.aspx)
///
template <class BaseHeap>
class CParanoidHeap : public BaseHeap {
public:
virtual void Free(_In_opt_ void* p) throw()
///
/// Sanitizes memory before freeing it
///
/// \param[in] p Pointer to heap memory block
///
virtual void Free(_In_opt_ void* p)
{
// Sanitize then free.
SecureZeroMemory(p, GetSize(p));
BaseHeap::Free(p);
}
_Ret_opt_bytecap_(nBytes) virtual void* Reallocate(_In_opt_ void* p, _In_ size_t nBytes) throw()
///
/// Safely reallocates the memory block by sanitizing memory at the previous location
///
/// This member function always performs the following steps (regardless of the current and new size):
/// 1. Allocates a new memory block,
/// 2. Copies the data,
/// 3. Sanitizes the old memory block,
/// 4. Frees the old memory block.
///
/// \param[in] p Pointer to heap memory block
/// \param[in] nBytes New size in bytes
/// \return Pointer to the new heap memory block
///
virtual /*_Ret_opt_bytecap_(nBytes)*/ void* Reallocate(_In_opt_ void* p, _In_ size_t nBytes)
{
// Create a new sized copy.
void *pNew = Allocate(nBytes);
size_t nSizePrev = GetSize(p);
memcpy(pNew, p, nSizePrev);
CopyMemory(pNew, p, nSizePrev);
// Sanitize the old data then free.
SecureZeroMemory(p, nSizePrev);
@@ -413,15 +594,31 @@ namespace ATL
};
//
// CW2AParanoidEX
//
///
/// Base template class to support string conversion with memory sanitization after use
///
template<int t_nBufferLength = 128>
class CW2AParanoidEX : public CW2AEX<t_nBufferLength> {
public:
///
/// Initializes a new class instance with the string provided.
///
/// \param[in] psz Pointer to wide string
///
CW2AParanoidEX(_In_z_ LPCWSTR psz) throw(...) : CW2AEX<t_nBufferLength>(psz) {}
///
/// Initializes a new class instance with the string provided.
///
/// \param[in] psz Pointer to wide string
/// \param[in] nCodePage Code page to use when converting to single-byte string
///
CW2AParanoidEX(_In_z_ LPCWSTR psz, _In_ UINT nCodePage) throw(...) : CW2AEX<t_nBufferLength>(psz, nCodePage) {}
~CW2AParanoidEX() throw()
///
/// Sanitizes string memory, then destroys it
///
~CW2AParanoidEX()
{
// Sanitize before free.
if (m_psz != m_szBuffer)
@@ -431,8 +628,10 @@ namespace ATL
}
};
//
// CW2AParanoid
//
///
/// Support for string conversion with memory sanitization after use
///
typedef CW2AParanoidEX<> CW2AParanoid;
/// @}
}