IAtlMemMgr 类

项目
10/13/2023

此类表示内存管理器的接口。

语法

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

成员

方法

名称	描述
Allocate	调用此方法来分配内存块。
免费	调用此方法可释放内存块。
GetSize	调用此方法可检索已分配内存块的大小。
Reallocate	调用此方法可重新分配内存块。

注解

此接口由 CComHeap、CCRTHeap、CLocalHeap、CGlobalHeap 或 CWin32Heap 实现。

注意

局部和全局堆函数比其他内存管理函数慢，并且没有提供那么多功能。因此，新的应用程序应使用堆函数。 CWin32Heap 类中提供了这些函数。

示例

// 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;
}

要求

标头：atlmem.h

IAtlMemMgr::Allocate

调用此方法来分配内存块。

void* Allocate(size_t nBytes) throw();

参数

nBytes
新内存块中请求的字节数。

返回值

将指针返回到新分配内存块的起始位置。

备注

调用 IAtlMemMgr::Free 或 IAtlMemMgr::Reallocate 可释放由此方法分配的内存。

示例

有关示例，请参阅 IAtlMemMgr 概述。

IAtlMemMgr::Free

调用此方法可释放内存块。

void Free(void* p) throw();

参数

p
指向此内存管理器以前分配的内存的指针。

备注

使用此方法可释放由 IAtlMemMgr::Allocate 或 IAtlMemMgr::Reallocate 获取的内存。

示例

有关示例，请参阅 IAtlMemMgr 概述。

IAtlMemMgr::GetSize

调用此方法可检索已分配内存块的大小。

size_t GetSize(void* p) throw();

参数

p
指向此内存管理器以前分配的内存的指针。

返回值

返回内存块的大小（以字节为单位）。

示例

有关示例，请参阅 IAtlMemMgr 概述。

IAtlMemMgr::Reallocate

调用此方法以重新分配由该内存管理器分配的内存。

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

参数

p
指向此内存管理器以前分配的内存的指针。

nBytes
新内存块中请求的字节数。

返回值

将指针返回到新分配内存块的起始位置。

注解

调用 IAtlMemMgr::Free 或 IAtlMemMgr::Reallocate 可释放由此方法分配的内存。

从概念上讲，此方法可释放现有内存并分配新的内存块。实际上，现有内存可扩展或重用。

示例

有关示例，请参阅 IAtlMemMgr 概述。

IAxWinAmbientDispatch::get_AllowContextMenu

AllowContextMenu 属性指定是否允许托管控件显示自身的上下文菜单。

STDMETHOD(get_AllowContextMenu)(VARIANT_BOOL* pbAllowContextMenu);

参数

pbAllowContextMenu
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::get_AllowShowUI

AllowShowUI 属性指定是否允许托管控件显示自身的用户界面。

STDMETHOD(get_AllowShowUI)(VARIANT_BOOL* pbAllowShowUI);

参数

pbAllowShowUI
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_FALSE 作为此属性的默认值。

IAxWinAmbientDispatch::get_AllowWindowlessActivation

AllowWindowlessActivation 属性指定容器是否允许无窗口激活。

STDMETHOD(get_AllowWindowlessActivation)(VARIANT_BOOL* pbAllowWindowless);

参数

pbAllowWindowless
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::get_BackColor

BackColor 属性指定容器的环境背景色。

STDMETHOD(get_BackColor)(OLE_COLOR* pclrBackground);

参数

pclrBackground
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 COLOR_BTNFACE 或 COLOR_WINDOW 作为此属性的默认值（具体取决于主机窗口的父级是否为对话框）。

IAxWinAmbientDispatch::get_DisplayAsDefault

DisplayAsDefault 是一个环境属性，它允许控件发现它是否为默认控件。

STDMETHOD(get_DisplayAsDefault)(VARIANT_BOOL* pbDisplayAsDefault);

参数

pbDisplayAsDefault
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 VARIANT_FALSE 作为此属性的默认值。

IAxWinAmbientDispatch::get_DocHostDoubleClickFlags

DocHostDoubleClickFlags 属性指定应响应双击而执行的操作。

STDMETHOD(get_DocHostDoubleClickFlags)(DWORD* pdwDocHostDoubleClickFlags);

参数

pdwDocHostDoubleClickFlags
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 DOCHOSTUIDBLCLK_DEFAULT 作为此属性的默认值。

IAxWinAmbientDispatch::get_DocHostFlags

DocHostFlags 属性指定主机对象的用户界面功能。

STDMETHOD(get_DocHostFlags)(DWORD* pdwDocHostFlags);

参数

pdwDocHostFlags
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 DOCHOSTUIFLAG_NO3DBORDER 作为此属性的默认值。

IAxWinAmbientDispatch::get_Font

Font 属性指定容器的环境字体。

STDMETHOD(get_Font)(IFontDisp** pFont);

参数

pFont
[out] 用于接收此属性当前值的 IFontDisp 接口指针的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用默认 GUI 字体或系统字体作为此属性的默认值。

IAxWinAmbientDispatch::get_ForeColor

ForeColor 属性指定容器的环境前景色。

STDMETHOD(get_ForeColor)(OLE_COLOR* pclrForeground);

参数

pclrForeground
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用系统窗口文本颜色作为此属性的默认值。

IAxWinAmbientDispatch::get_LocaleID

LocaleID 属性指定容器的环境区域设置 ID。

STDMETHOD(get_LocaleID)(LCID* plcidLocaleID);

参数

plcidLocaleID
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用用户的默认区域设置作为此属性的默认值。

使用此方法可以发现环境 LocalID，即所用控件所在的程序的 LocaleID。知晓 LocaleID 后，可以调用代码，从资源文件或附属 DLL 加载特定于区域设置的描述文字、错误消息文本等。

IAxWinAmbientDispatch::get_MessageReflect

MessageReflect 环境属性指定容器是否将消息反映到托管控件。

STDMETHOD(get_MessageReflect)(VARIANT_BOOL* pbMessageReflect);

参数

pbMessageReflect
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::get_OptionKeyPath

OptionKeyPath 属性指定用户设置的注册表项路径。

STDMETHOD(get_OptionKeyPath)(BSTR* pbstrOptionKeyPath);

参数

pbstrOptionKeyPath
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

IAxWinAmbientDispatch::get_ShowGrabHandles

ShowGrabHandles 环境属性允许控件发现它是否应使用抓取句柄绘制自身。

STDMETHOD(get_ShowGrabHandles)(VARIANT_BOOL* pbShowGrabHandles);

参数

pbShowGrabHandles
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现始终返回 VARIANT_FALSE 作为此属性的值。

IAxWinAmbientDispatch::get_ShowHatching

ShowHatching 环境属性允许控件发现它是否应绘制自身阴影。

STDMETHOD(get_ShowHatching)(VARIANT_BOOL* pbShowHatching);

参数

pbShowHatching
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现始终返回 VARIANT_FALSE 作为此属性的值。

IAxWinAmbientDispatch::get_UserMode

UserMode 属性指定容器的环境用户模式。

STDMETHOD(get_UserMode)(VARIANT_BOOL* pbUserMode);

参数

pbUserMode
[out] 用于接收此属性当前值的变量的地址。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::put_AllowContextMenu

AllowContextMenu 属性指定是否允许托管控件显示自身的上下文菜单。

STDMETHOD(put_AllowContextMenu)(VARIANT_BOOL bAllowContextMenu);

参数

bAllowContextMenu
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::put_AllowShowUI

AllowShowUI 属性指定是否允许托管控件显示自身的用户界面。

STDMETHOD(put_AllowShowUI)(VARIANT_BOOL bAllowShowUI);

参数

bAllowShowUI
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_FALSE 作为此属性的默认值。

IAxWinAmbientDispatch::put_AllowWindowlessActivation

AllowWindowlessActivation 属性指定容器是否允许无窗口激活。

STDMETHOD(put_AllowWindowlessActivation)(VARIANT_BOOL bAllowWindowless);

参数

bAllowWindowless
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::put_BackColor

BackColor 属性指定容器的环境背景色。

STDMETHOD(put_BackColor)(OLE_COLOR clrBackground);

参数

clrBackground
[in] 此属性的新值。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用 COLOR_BTNFACE 或 COLOR_WINDOW 作为此属性的默认值（具体取决于主机窗口的父级是否为对话框）。

IAxWinAmbientDispatch::put_DisplayAsDefault

DisplayAsDefault 是一个环境属性，它允许控件发现它是否为默认控件。

STDMETHOD(put_DisplayAsDefault)(VARIANT_BOOL bDisplayAsDefault);

参数

bDisplayAsDefault
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_FALSE 作为此属性的默认值。

IAxWinAmbientDispatch::put_DocHostDoubleClickFlags

DocHostDoubleClickFlags 属性指定应响应双击而执行的操作。

STDMETHOD(put_DocHostDoubleClickFlags)(DWORD dwDocHostDoubleClickFlags);

参数

dwDocHostDoubleClickFlags
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 DOCHOSTUIDBLCLK_DEFAULT 作为此属性的默认值。

IAxWinAmbientDispatch::put_DocHostFlags

DocHostFlags 属性指定主机对象的用户界面功能。

STDMETHOD(put_DocHostFlags)(DWORD dwDocHostFlags);

参数

dwDocHostFlags
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 DOCHOSTUIFLAG_NO3DBORDER 作为此属性的默认值。

IAxWinAmbientDispatch::put_Font

Font 属性指定容器的环境字体。

STDMETHOD(put_Font)(IFontDisp* pFont);

参数

pFont
[in] 此属性的新值。

返回值

标准 HRESULT 值。

注解

ATL 主机对象实现使用默认 GUI 字体或系统字体作为此属性的默认值。

IAxWinAmbientDispatch::put_ForeColor

ForeColor 属性指定容器的环境前景色。

STDMETHOD(put_ForeColor)(OLE_COLOR clrForeground);

参数

clrForeground
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用系统窗口文本颜色作为此属性的默认值。

IAxWinAmbientDispatch::put_LocaleID

LocaleID 属性指定容器的环境区域设置 ID。

STDMETHOD(put_LocaleID)(LCID lcidLocaleID);

参数

lcidLocaleID
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用用户的默认区域设置作为此属性的默认值。

IAxWinAmbientDispatch::put_MessageReflect

MessageReflect 环境属性指定容器是否将消息反映到托管控件。

STDMETHOD(put_MessageReflect)(VARIANT_BOOL bMessageReflect);

参数

bMessageReflect
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatch::put_OptionKeyPath

OptionKeyPath 属性指定用户设置的注册表项路径。

STDMETHOD(put_OptionKeyPath)(BSTR bstrOptionKeyPath);

参数

bstrOptionKeyPath
[in] 此属性的新值。

返回值

标准 HRESULT 值。

IAxWinAmbientDispatch::put_UserMode

UserMode 属性指定容器的环境用户模式。

STDMETHOD(put_UserMode)(VARIANT_BOOL bUserMode);

参数

bUserMode
[in] 此属性的新值。

返回值

标准 HRESULT 值。

备注

ATL 主机对象实现使用 VARIANT_TRUE 作为此属性的默认值。

IAxWinAmbientDispatchEx::SetAmbientDispatch

调用此方法可使用用户定义的接口补充默认环境属性接口。

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

参数

pDispatch
指向新接口的指针。

返回值

如果成功，则返回 S_OK；否则返回错误 HRESULT。

注解

当使用指向新接口的指针调用 SetAmbientDispatch 时，此新接口将用于调用托管控件要求的任何属性或方法（如果 IAxWinAmbientDispatch 尚未提供这些属性）。

IAxWinHostWindow::AttachControl

使用 hWnd 标识的窗口将现有（和以前初始化的）控件附加到主机对象。

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

参数

pUnkControl
[in] 指向要附加到主机对象的控件的 IUnknown 接口的指针。

hWnd
[in] 要用于托管的窗口的句柄。

返回值

标准 HRESULT 值。

IAxWinHostWindow::CreateControl

创建一个控件，初始化它，并将其托管在由 hWnd 标识的窗口中。

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

参数

lpTricsData
[in] 标识要创建的控件的字符串。可以是 CLSID（必须包含大括号）、ProgID、URL 或原始 HTML（以 MSHTML: 为前缀）。

hWnd
[in] 要用于托管的窗口的句柄。

pStream
[in] 包含控件初始化数据的流的接口指针。可以为 NULL。

返回值

标准 HRESULT 值。

备注

公开此接口的主机对象将子类化此窗口，以便消息能够反映到控件，其他容器功能能够正常工作。

调用此方法等效于调用 IAxWinHostWindow::CreateControlEx。

若要创建许可 ActiveX 控件，请参阅 IAxWinHostWindowLic::CreateControlLic。

IAxWinHostWindow::CreateControlEx

创建 ActiveX 控件，初始化它，并将其托管在指定窗口中，类似于 IAxWinHostWindow::CreateControl。

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

参数

lpTricsData
[in] 标识要创建的控件的字符串。可以是 CLSID（必须包含大括号）、ProgID、URL 或原始 HTML（以 MSHTML: 为前缀）。

hWnd
[in] 要用于托管的窗口的句柄。

pStream
[in] 包含控件初始化数据的流的接口指针。可以为 NULL。

ppUnk
[out] 将接收所创建控件 IUnknown 接口的指针的地址。可以为 NULL。

riidAdvise
[in] 所包含对象的传出接口的接口标识符。可为 IID_NULL。

punkAdvise
[in] 指向要连接到由 iidSink 指定的所含对象上的连接点的接收器对象的 IUnknown 接口的指针。

返回值

标准 HRESULT 值。

注解

与 CreateControl 方法不同，CreateControlEx 还允许接收指向新创建的控件的接口指针，并设置事件接收器以接收该控件触发的事件。

若要创建许可 ActiveX 控件，请参阅 IAxWinHostWindowLic::CreateControlLicEx。

IAxWinHostWindow::QueryControl

返回由托管控件提供的指定接口指针。

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

参数

riid
[in] 所请求的控件上的接口的 ID。

ppvObject
[out] 将接收所创建控件的指定接口的指针的地址。

返回值

标准 HRESULT 值。

IAxWinHostWindow::SetExternalDispatch

设置外部调度接口，该接口可通过 IDocHostUIHandlerDispatch::GetExternal 方法用于所含控件。

STDMETHOD(SetExternalDispatch)(IDispatch* pDisp);

参数

pDisp
[in] 指向 IDispatch 接口的指针。

返回值

标准 HRESULT 值。

IAxWinHostWindow::SetExternalUIHandler

调用此函数可为 CAxWindow 对象设置外部 IDocHostUIHandlerDispatch 接口。

STDMETHOD(SetExternalUIHandler)(IDocHostUIHandlerDispatch* pDisp);

参数

pDisp
[in] 指向 IDocHostUIHandlerDispatch 接口的指针。

返回值

标准 HRESULT 值。

备注

此函数由查询主机站点的 IDocHostUIHandlerDispatch 接口的控件（如 Web 浏览器控件）使用。

IAxWinHostWindowLic::CreateControlLic

创建一个许可控件，初始化它，并将其托管在由 hWnd 标识的窗口中。

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

参数

bstrLic
[in] 包含控件许可证密钥的 BSTR。

备注

有关剩余参数和返回值的说明，请参阅 IAxWinHostWindow::CreateControl。

调用此方法等效于调用 IAxWinHostWindowLic::CreateControlLicEx

示例

有关使用 IAxWinHostWindowLic::CreateControlLic 的示例，请参阅使用 ATL AXHost 托管 ActiveX 控件。

IAxWinHostWindowLic::CreateControlLicEx

创建许可 ActiveX 控件，初始化它，并将其托管在指定窗口中，类似于 IAxWinHostWindow::CreateControl。

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

参数

bstrLic
[in] 包含控件许可证密钥的 BSTR。

备注

有关剩余参数和返回值的说明，请参阅 IAxWinHostWindow::CreateControlEx。

示例

有关使用 IAxWinHostWindowLic::CreateControlLicEx 的示例，请参阅使用 ATL AXHost 托管 ActiveX 控件。

另请参阅

类概述