CHandle Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CHandle Class on docs.microsoft.com. This class provides methods for creating and using a handle object.

class CHandle

Public Constructors

NameDescription
CHandle::CHandleThe constructor.
CHandle::~CHandleThe destructor.

Public Methods

NameDescription
CHandle::AttachCall this method to attach the CHandle object to an existing handle.
CHandle::CloseCall this method to close a CHandle object.
CHandle::DetachCall this method to detach a handle from a CHandle object.

Public Operators

NameDescription
CHandle::operator HANDLEReturns the value of the stored handle.
CHandle::operator =Assignment operator.

Public Data Members

NameDescription
CHandle::m_hThe 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.

System_CAPS_ICON_note.jpg 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();

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.

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.

The destructor.

~CHandle() throw();

Remarks

Frees the CHandle object by calling 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.

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.

The member variable that stores the handle.

HANDLE m_h;

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.

Returns the value of the stored handle.

operator HANDLE() const throw();

Remarks

Returns the value stored in CHandle::m_h.

Class Overview

Show: