IAtlMemMgr Class

Article
12/18/2017

The latest version of this topic can be found at IAtlMemMgr Class.

This class represents the interface to a memory manager.

Syntax

__interface __declspec(uuid("654F7EF5-CFDF-4df9-A450-6C6A13C622C0")) IAtlMemMgr

Members

Methods

Allocate	Call this method to allocate a block of memory.
Free	Call this method to free a block of memory.
GetSize	Call this method to retrieve the size of an allocated memory block.
Reallocate	Call this method to reallocate a block of memory.

Remarks

This interface is implemented by CComHeap, CCRTHeap, CLocalHeap, CGlobalHeap, or CWin32Heap.

Note

The local and global heap functions are slower than other memory management functions, and do not provide as many features. Therefore, new applications should use the heap functions. These are available in the CWin32Heap class.

Example

// Demonstrate IAtlMemMgr using the five possible
// memory function implementation classes. 

HRESULT MemoryManagerDemonstration(IAtlMemMgr& MemoryManager) throw()
{
   // The IAtlMemMgr interface guarantees not to throw exceptions
   // so we can make the same guarantee for this function
   // without adding exception handling code.

   // A variable which will point to some allocated memory.
   void* pMemory = NULL;

   const size_t BytesInChunk = 1024;

   // Allocate a chunk of memory
   pMemory = MemoryManager.Allocate(BytesInChunk);

   // Confirm the validity of the allocated memory
   if (pMemory == NULL)
      return E_OUTOFMEMORY;

   // Confirm the size of the allocated memory
   ATLASSERT(MemoryManager.GetSize(pMemory) == BytesInChunk);

   // Increase the size of the allocated memory
   pMemory = MemoryManager.Reallocate(pMemory, BytesInChunk * 2);

   // Confirm the validity of the allocated memory
   if (pMemory == NULL)
      return E_OUTOFMEMORY;

   // Confirm the size of the reallocated  memory
   ATLASSERT(MemoryManager.GetSize(pMemory) == BytesInChunk * 2);

   // Free the allocated memory
   MemoryManager.Free(pMemory);

   return S_OK;
}

int DoMemoryManagerDemonstration()
{
   CComHeap heapCom;
   CCRTHeap heapCrt;
   CLocalHeap heapLocal;
   CGlobalHeap heapGlobal;
   // It is necessary to provide extra information 
   // to the constructor when using CWin32Heap
   CWin32Heap heapWin32(NULL, 4096); 

   ATLASSERT(S_OK==MemoryManagerDemonstration(heapCom));
   ATLASSERT(S_OK==MemoryManagerDemonstration(heapCrt));
   ATLASSERT(S_OK==MemoryManagerDemonstration(heapLocal));
   ATLASSERT(S_OK==MemoryManagerDemonstration(heapGlobal));
   ATLASSERT(S_OK==MemoryManagerDemonstration(heapWin32));

   return 0;
}

Requirements

Header: atlmem.h

IAtlMemMgr::Allocate

Call this method to allocate a block of memory.

void* Allocate(size_t nBytes) throw();

Parameters

nBytes
The requested number of bytes in the new memory block.

Return Value

Returns a pointer to the start of the newly allocated memory block.

Remarks

Call IAtlMemMgr::Free or IAtlMemMgr::Reallocate to free the memory allocated by this method.

Example

For an example, see the IAtlMemMgr Overview.

IAtlMemMgr::Free

Call this method to free a block of memory.

void Free(void* p) throw();

Parameters

p
Pointer to memory previously allocated by this memory manager.

Remarks

Use this method to free memory obtained by IAtlMemMgr::Allocate or IAtlMemMgr::Reallocate.

Example

For an example, see the IAtlMemMgr Overview.

IAtlMemMgr::GetSize

Call this method to retrieve the size of an allocated memory block.

size_t GetSize(void* p) throw();

Parameters

p
Pointer to memory previously allocated by this memory manager.

Return Value

Returns the size of the memory block in bytes.

Example

For an example, see the IAtlMemMgr Overview.

IAtlMemMgr::Reallocate

Call this method to reallocate memory allocated by this memory manager.

void* Reallocate(void* p, size_t nBytes) throw();

Parameters

p
Pointer to memory previously allocated by this memory manager.

nBytes
The requested number of bytes in the new memory block.

Return Value

Returns a pointer to the start of the newly allocated memory block.

Remarks

Call IAtlMemMgr::Free or IAtlMemMgr::Reallocate to free the memory allocated by this method.

Conceptually this method frees the existing memory and allocates a new memory block. In reality, the existing memory may be extended or otherwise reused.

Example

For an example, see the IAtlMemMgr Overview.

IAxWinAmbientDispatch::get_AllowContextMenu

The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.

STDMETHOD(get_AllowContextMenu)(VARIANT_BOOL* pbAllowContextMenu);

Parameters

pbAllowContextMenu
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::get_AllowShowUI

The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.

STDMETHOD(get_AllowShowUI)(VARIANT_BOOL* pbAllowShowUI);

Parameters

pbAllowShowUI
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_FALSE as the default value of this property.

IAxWinAmbientDispatch::get_AllowWindowlessActivation

The AllowWindowlessActivation property specifies whether the container will allow windowless activation.

STDMETHOD(get_AllowWindowlessActivation)(VARIANT_BOOL* pbAllowWindowless);

Parameters

pbAllowWindowless
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::get_BackColor

The BackColor property specifies the ambient background color of the container.

STDMETHOD(get_BackColor)(OLE_COLOR* pclrBackground);

Parameters

pclrBackground
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses COLOR_BTNFACE or COLOR_WINDOW as the default value of this property (depending on whether the parent of the host window is a dialog or not).

IAxWinAmbientDispatch::get_DisplayAsDefault

DisplayAsDefault is an ambient property that allows a control to find out if it is the default control.

STDMETHOD(get_DisplayAsDefault)(VARIANT_BOOL* pbDisplayAsDefault);

Parameters

pbDisplayAsDefault
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_FALSE as the default value of this property.

IAxWinAmbientDispatch::get_DocHostDoubleClickFlags

The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.

STDMETHOD(get_DocHostDoubleClickFlags)(DWORD* pdwDocHostDoubleClickFlags);

Parameters

pdwDocHostDoubleClickFlags
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses DOCHOSTUIDBLCLK_DEFAULT as the default value of this property.

IAxWinAmbientDispatch::get_DocHostFlags

The DocHostFlags property specifies the user interface capabilities of the host object.

STDMETHOD(get_DocHostFlags)(DWORD* pdwDocHostFlags);

Parameters

pdwDocHostFlags
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses DOCHOSTUIFLAG_NO3DBORDER as the default value of this property.

IAxWinAmbientDispatch::get_Font

The Font property specifies the ambient font of the container.

STDMETHOD(get_Font)(IFontDisp** pFont);

Parameters

pFont
[out] The address of an IFontDisp interface pointer used to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the default GUI font or the system font as the default value of this property.

IAxWinAmbientDispatch::get_ForeColor

The ForeColor property specifies the ambient foreground color of the container.

STDMETHOD(get_ForeColor)(OLE_COLOR* pclrForeground);

Parameters

pclrForeground
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the system window text color as the default value of this property.

IAxWinAmbientDispatch::get_LocaleID

The LocaleID property specifies the ambient locale ID of the container.

STDMETHOD(get_LocaleID)(LCID* plcidLocaleID);

Parameters

plcidLocaleID
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the user's default locale as the default value of this property.

With this method you can discover the Ambient LocalID, that is, the LocaleID of the program your control is being used in. Once you know the LocaleID, you can call code to load locale-specific captions, error message text, and so forth from a resource file or satellite DLL.

IAxWinAmbientDispatch::get_MessageReflect

The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.

STDMETHOD(get_MessageReflect)(VARIANT_BOOL* pbMessageReflect);

Parameters

pbMessageReflect
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::get_OptionKeyPath

The OptionKeyPath property specifies the registry key path to user settings.

STDMETHOD(get_OptionKeyPath)(BSTR* pbstrOptionKeyPath);

Parameters

pbstrOptionKeyPath
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

IAxWinAmbientDispatch::get_ShowGrabHandles

The ShowGrabHandles ambient property allows the control to find out if it should draw itself with grab handles.

STDMETHOD(get_ShowGrabHandles)(VARIANT_BOOL* pbShowGrabHandles);

Parameters

pbShowGrabHandles
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation always returns VARIANT_FALSE as the value of this property.

IAxWinAmbientDispatch::get_ShowHatching

The ShowHatching ambient property allows the control to find out if it should draw itself hatched.

STDMETHOD(get_ShowHatching)(VARIANT_BOOL* pbShowHatching);

Parameters

pbShowHatching
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation always returns VARIANT_FALSE as the value of this property.

IAxWinAmbientDispatch::get_UserMode

The UserMode property specifies the ambient user mode of the container.

STDMETHOD(get_UserMode)(VARIANT_BOOL* pbUserMode);

Parameters

pbUserMode
[out] The address of a variable to receive the current value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::put_AllowContextMenu

The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.

STDMETHOD(put_AllowContextMenu)(VARIANT_BOOL bAllowContextMenu);

Parameters

bAllowContextMenu
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::put_AllowShowUI

The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.

STDMETHOD(put_AllowShowUI)(VARIANT_BOOL bAllowShowUI);

Parameters

bAllowShowUI
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_FALSE as the default value of this property.

IAxWinAmbientDispatch::put_AllowWindowlessActivation

The AllowWindowlessActivation property specifies whether the container will allow windowless activation.

STDMETHOD(put_AllowWindowlessActivation)(VARIANT_BOOL bAllowWindowless);

Parameters

bAllowWindowless
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::put_BackColor

The BackColor property specifies the ambient background color of the container.

STDMETHOD(put_BackColor)(OLE_COLOR clrBackground);

Parameters

clrBackground
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses COLOR_BTNFACE or COLOR_WINDOW as the default value of this property (depending on whether the parent of the host window is a dialog or not).

IAxWinAmbientDispatch::put_DisplayAsDefault

DisplayAsDefault is an ambient property that allows a control to find out if it is the default control.

STDMETHOD(put_DisplayAsDefault)(VARIANT_BOOL bDisplayAsDefault);

Parameters

bDisplayAsDefault
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_FALSE as the default value of this property.

IAxWinAmbientDispatch::put_DocHostDoubleClickFlags

The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.

STDMETHOD(put_DocHostDoubleClickFlags)(DWORD dwDocHostDoubleClickFlags);

Parameters

dwDocHostDoubleClickFlags
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses DOCHOSTUIDBLCLK_DEFAULT as the default value of this property.

IAxWinAmbientDispatch::put_DocHostFlags

The DocHostFlags property specifies the user interface capabilities of the host object.

STDMETHOD(put_DocHostFlags)(DWORD dwDocHostFlags);

Parameters

dwDocHostFlags
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses DOCHOSTUIFLAG_NO3DBORDER as the default value of this property.

IAxWinAmbientDispatch::put_Font

The Font property specifies the ambient font of the container.

STDMETHOD(put_Font)(IFontDisp* pFont);

Parameters

pFont
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the default GUI font or the system font as the default value of this property.

IAxWinAmbientDispatch::put_ForeColor

The ForeColor property specifies the ambient foreground color of the container.

STDMETHOD(put_ForeColor)(OLE_COLOR clrForeground);

Parameters

clrForeground
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the system window text color as the default value of this property.

IAxWinAmbientDispatch::put_LocaleID

The LocaleID property specifies the ambient locale ID of the container.

STDMETHOD(put_LocaleID)(LCID lcidLocaleID);

Parameters

lcidLocaleID
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses the user's default locale as the default value of this property.

IAxWinAmbientDispatch::put_MessageReflect

The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.

STDMETHOD(put_MessageReflect)(VARIANT_BOOL bMessageReflect);

Parameters

bMessageReflect
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatch::put_OptionKeyPath

The OptionKeyPath property specifies the registry key path to user settings.

STDMETHOD(put_OptionKeyPath)(BSTR bstrOptionKeyPath);

Parameters

bstrOptionKeyPath
[in] The new value of this property.

Return Value

A standard HRESULT value.

IAxWinAmbientDispatch::put_UserMode

The UserMode property specifies the ambient user mode of the container.

STDMETHOD(put_UserMode)(VARIANT_BOOL bUserMode);

Parameters

bUserMode
[in] The new value of this property.

Return Value

A standard HRESULT value.

Remarks

The ATL host object implementation uses VARIANT_TRUE as the default value of this property.

IAxWinAmbientDispatchEx::SetAmbientDispatch

This method is called to supplement the default ambient property interface with a user-defined interface.

virtual HRESULT STDMETHODCALLTYPE SetAmbientDispatch(IDispatch* pDispatch) = 0;

Parameters

pDispatch
Pointer to the new interface.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

When SetAmbientDispatch is called with a pointer to a new interface, this new interface will be used to invoke any properties or methods asked for by the hosted control — if those properties are not already provided by IAxWinAmbientDispatch.

IAxWinHostWindow::AttachControl

Attaches an existing (and previously initialized) control to the host object using the window identified by hWnd.

STDMETHOD(AttachControl)(IUnknown* pUnkControl, HWND hWnd);

Parameters

pUnkControl
[in] A pointer to the IUnknown interface of the control to be attached to the host object.

hWnd
[in] A handle to the window to be used for hosting.

Return Value

A standard HRESULT value.

IAxWinHostWindow::CreateControl

Creates a control, initializes it, and hosts it in the window identified by hWnd.

STDMETHOD(CreateControl)(
    LPCOLESTR lpTricsData,
    HWND hWnd,
    IStream* pStream);

Parameters

lpTricsData
[in] A string identifying the control to create. Can be a CLSID (must include the braces), ProgID, URL, or raw HTML (prefixed by MSHTML:).

hWnd
[in] A handle to the window to be used for hosting.

pStream
[in] An interface pointer for a stream containing initialization data for the control. Can be NULL.

Return Value

A standard HRESULT value.

Remarks

This window will be subclassed by the host object exposing this interface so that messages can be reflected to the control and other container features will work.

Calling this method is equivalent to calling IAxWinHostWindow::CreateControlEx.

To create a licensed ActiveX control, see IAxWinHostWindowLic::CreateControlLic.

IAxWinHostWindow::CreateControlEx

Creates an ActiveX control, initializes it, and hosts it in the specified window, similar to IAxWinHostWindow::CreateControl.

STDMETHOD(CreateControlEx)(
    LPCOLESTR lpszTricsData,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnk,
    REFIID riidAdvise,
    IUnknown* punkAdvise);

Parameters

lpTricsData
[in] A string identifying the control to create. Can be a CLSID (must include the braces), ProgID, URL, or raw HTML (prefixed with MSHTML:).

hWnd
[in] A handle to the window to be used for hosting.

pStream
[in] An interface pointer for a stream containing initialization data for the control. Can be NULL.

ppUnk
[out] The address of a pointer that will receive the IUnknown interface of the created control. Can be NULL.

riidAdvise
[in] The interface identifier of an outgoing interface on the contained object. Can be IID_NULL.

punkAdvise
[in] A pointer to the IUnknown interface of the sink object to be connected to the connection point on the contained object specified by iidSink.

Return Value

A standard HRESULT value.

Remarks

Unlike the CreateControl method, CreateControlEx also allows you to receive an interface pointer to the newly created control and set up an event sink to receive events fired by the control.

To create a licensed ActiveX control, see IAxWinHostWindowLic::CreateControlLicEx.

IAxWinHostWindow::QueryControl

Returns the specified interface pointer provided by the hosted control.

STDMETHOD(QueryControl)(REFIID riid, void** ppvObject);

Parameters

riid
[in] The ID of an interface on the control being requested.

ppvObject
[out] The address of a pointer that will receive the specified interface of the created control.

Return Value

A standard HRESULT value.

IAxWinHostWindow::SetExternalDispatch

Sets the external dispinterface, which is available to contained controls through the IDocHostUIHandlerDispatch::GetExternal method.

STDMETHOD(SetExternalDispatch)(IDispatch* pDisp);

Parameters

pDisp
[in] A pointer to an IDispatch interface.

Return Value

A standard HRESULT value.

IAxWinHostWindow::SetExternalUIHandler

Call this function to set the external IDocHostUIHandlerDispatch interface for the CAxWindow object.

STDMETHOD(SetExternalUIHandler)(IDocHostUIHandlerDispatch* pDisp);

Parameters

pDisp
[in] A pointer to an IDocHostUIHandlerDispatch interface.

Return Value

A standard HRESULT value.

Remarks

This function is used by controls (such as the Web browser control) that query the host's site for the IDocHostUIHandlerDispatch interface.

IAxWinHostWindowLic::CreateControlLic

Creates a licensed control, initializes it, and hosts it in the window identified by hWnd.

STDMETHOD(CreateControlLic)(
    LPCOLESTR lpTricsData,
    HWND hWnd,
    IStream* pStream,
    BSTR bstrLic);

Parameters

bstrLic
[in] The BSTR that contains the license key for the control.

Remarks

See IAxWinHostWindow::CreateControl for a description of the remaining parameters and return value.

Calling this method is equivalent to calling IAxWinHostWindowLic::CreateControlLicEx

Example

See Hosting ActiveX Controls Using ATL AXHost for a sample that uses IAxWinHostWindowLic::CreateControlLic.

IAxWinHostWindowLic::CreateControlLicEx

Creates a licensed ActiveX control, initializes it, and hosts it in the specified window, similar to IAxWinHostWindow::CreateControl.

STDMETHOD(CreateControlLicEx)(
    LPCOLESTR lpszTricsData,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnk,
    REFIID riidAdvise,
    IUnknown* punkAdvise,
    BSTR bstrLic);

Parameters

bstrLic
[in] The BSTR that contains the license key for the control.

Remarks

See IAxWinHostWindow::CreateControlEx for a description of the remaining parameters and return value.

Example

See Hosting ActiveX Controls Using ATL AXHost for a sample that uses IAxWinHostWindowLic::CreateControlLicEx.

Share via

IAtlMemMgr Class

Syntax

Members

Methods

Remarks

Example

Requirements

IAtlMemMgr::Allocate

Parameters

Return Value

Remarks

Example

IAtlMemMgr::Free

Parameters

Remarks

Example

IAtlMemMgr::GetSize

Parameters

Return Value

Example

IAtlMemMgr::Reallocate

Parameters

Return Value

Remarks

Example

IAxWinAmbientDispatch::get_AllowContextMenu

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_AllowShowUI

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_AllowWindowlessActivation

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_BackColor

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_DisplayAsDefault

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_DocHostDoubleClickFlags

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_DocHostFlags

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_Font

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_ForeColor

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_LocaleID

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_MessageReflect

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_OptionKeyPath

Parameters

Return Value

IAxWinAmbientDispatch::get_ShowGrabHandles

Parameters

Return Value

Remarks

IAxWinAmbientDispatch::get_ShowHatching

Parameters

Return Value