diff --git a/include/atlex.h b/include/atlex.h index adf0e93..e53ca05 100644 --- a/include/atlex.h +++ b/include/atlex.h @@ -26,66 +26,169 @@ namespace ATL { - // - // CObjectWithHandleT - // - template - class CObjectWithHandleT + /** + * 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. + */ + template class CObjectWithHandleT { public: + /** + * 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) { } - inline CObjectWithHandleT(HANDLE h) throw() : m_h(h) + /** + *\param h Initial object handle value + */ + inline CObjectWithHandleT(_In_opt_ HANDLE h) throw() : m_h(h) { } + /**@}*/ + /**\name Operators to allow transparent use of this class */ + /**@{*/ + /** + * Auto-typecasting operator + *\return Object handle + */ inline operator HANDLE() const throw() { 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 + */ 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() { 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() { 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() { 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() { 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() + { + 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() + { + 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() + { + 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. + */ 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() { 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() { if (m_h) @@ -93,6 +196,10 @@ namespace ATL m_h = h; } + /** + * Dismiss the object handle from this class + *\return Object handle + */ inline HANDLE Detach() throw() { HANDLE h = m_h; @@ -100,6 +207,9 @@ namespace ATL return h; } + /** + * Destroys the object + */ inline void Free() throw() { if (m_h) { @@ -109,9 +219,13 @@ namespace ATL } protected: + /** + * Abstract method that must be implemented by child classes to do the actual object destruction + */ virtual void InternalFree() = 0; protected: + /*** Object handle */ HANDLE m_h; };