CHandle Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CHandle Class.
This class provides methods for creating and using a handle object.
Syntax
class CHandle
Members
Public Constructors
| Name | Description |
|---|---|
| CHandle::CHandle | The constructor. |
| CHandle::~CHandle | The destructor. |
Public Methods
| 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. |
Public Operators
| Name | Description |
|---|---|
| CHandle::operator HANDLE | Returns the value of the stored handle. |
| CHandle::operator = | Assignment operator. |
Public Data Members
| Name | Description |
|---|---|
| CHandle::m_h | The member variable that stores the handle. |
Remarks
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.
Requirements
Header: atlbase.h
CHandle::Attach
Call this method to attach the CHandle object to an existing handle.
void Attach(HANDLE h) throw();
Parameters
h
CHandle will take ownership of the handle h.
Remarks
Assigns the CHandle object to the h handle. In debugs builds, an ATLASSERT will be raised if h is NULL. No other check as to the validity of the handle is made.
CHandle::CHandle
The constructor.
CHandle() throw();
CHandle(CHandle& h) throw();
explicit CHandle(HANDLE h) throw();
Parameters
h
An existing handle or CHandle.
Remarks
Creates a new CHandle object, optionally using an existing handle or CHandle object.
CHandle::~CHandle
The destructor.
~CHandle() throw();
Remarks
Frees the CHandle object by calling CHandle::Close.
CHandle::Close
Call this method to close a CHandle object.
void Close() throw();
Remarks
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.
CHandle::Detach
Call this method to detach a handle from a CHandle object.
HANDLE Detach() throw();
Return Value
Returns the handle being detached.
Remarks
Releases ownership of the handle.
CHandle::m_h
The member variable that stores the handle.
HANDLE m_h;
CHandle::operator =
The assignment operator.
CHandle& operator=(CHandle& h) throw();
Parameters
h
CHandle will take ownership of the handle h.
Return Value
Returns a reference to the new CHandle object.
Remarks
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.
CHandle::operator HANDLE
Returns the value of the stored handle.
operator HANDLE() const throw();
Remarks
Returns the value stored in CHandle::m_h.