CHandle Class
This class provides methods for creating and using a handle object.
class CHandle
| Name | Description |
|---|---|
| CHandle::CHandle | The constructor. |
| CHandle::~CHandle | The destructor. |
| Name | Description |
|---|---|
| CHandle::Attach | Call this method to attach the CHandle object to an existing handle. |
| CHandle::Close | Call this method to close a CHandle object. |
| CHandle::Detach | Call this method to detach a handle from a CHandle object. |
| Name | Description |
|---|---|
| CHandle::operator HANDLE | Returns the value of the stored handle. |
| CHandle::operator = | Assignment operator. |
| Name | Description |
|---|---|
| CHandle::m_h | The member variable that stores the handle. |
A CHandle object can be used whenever a handle is required: the main difference is that the CHandle object will automatically be deleted.
Note
Some API functions will use NULL as an empty or invalid handle, while others use INVALID_HANDLE_VALUE. CHandle only uses NULL and will treat INVALID_HANDLE_VALUE as a real handle. If you call an API which can return INVALID_HANDLE_VALUE, you should check for this value before calling CHandle::Attach or passing it to the CHandle constructor, and instead pass NULL.
Header: atlbase.h
Call this method to attach the CHandle object to an existing handle.
void Attach(HANDLE h) throw();
h
CHandle will take ownership of the handle h.
Assigns the CHandle object to the h handle and then calls h.Detach(). In debugs builds, an ATLASSERT will be raised if h is NULL. No other check as to the validity of the handle is made.
The constructor.
CHandle() throw();
CHandle(CHandle& h) throw();
explicit CHandle(HANDLE h) throw();
h
An existing handle or CHandle.
Creates a new CHandle object, optionally using an existing handle or CHandle object.
The destructor.
~CHandle() throw();
Frees the CHandle object by calling CHandle::Close.
Call this method to close a CHandle object.
void Close() throw();
Closes an open object handle. If the handle is NULL, which will be the case if Close has already been called, an ATLASSERT will be raised in debug builds.
Call this method to detach a handle from a CHandle object.
HANDLE Detach() throw();
Returns the handle being detached.
Releases ownership of the handle.
The member variable that stores the handle.
HANDLE m_h;
The assignment operator.
CHandle& operator=(CHandle& h) throw();
h
CHandle will take ownership of the handle h.
Returns a reference to the new CHandle object.
If the CHandle object currently contains a handle, it will be closed. The CHandle object being passed in will have its handle reference set to NULL. This ensures that two CHandle objects will never contain the same active handle.
Returns the value of the stored handle.
operator HANDLE() const throw();
Returns the value stored in CHandle::m_h.