IAtlMemMgr Class
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.