CComCoClass 类

  • 项目

此类提供用于创建类实例并获取其属性的方法。

语法

template <class T, const CLSID* pclsid = &CLSID_NULL>
class CComCoClass

参数

T
你的类，派生自 CComCoClass。

pclsid
指向对象的 CLSID 的指针。

成员

公共方法

名称 描述
CComCoClass::CreateInstance （静态）创建接口的类和查询的实例。
CComCoClass::Error （静态）为客户端返回丰富的错误信息。
CComCoClass::GetObjectCLSID （静态）返回对象的类标识符。
CComCoClass::GetObjectDescription （静态）进行替代以返回对象的说明。

注解

CComCoClass 提供用于检索对象的 CLSID、设置错误信息和创建类实例的方法。 在对象映射中注册的任何类都应派生自 CComCoClass。

CComCoClass 还定义对象的默认类工厂和聚合模型。 CComCoClass 使用以下两个宏：

可以通过在类定义中指定另一个宏来替代这些默认值中的任何一个。 例如，若要使用 CComClassFactory2 而不是 CComClassFactory，请指定 DECLARE_CLASSFACTORY2 宏：

class ATL_NO_VTABLE CMyClass2 :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyClass2, &CLSID_MyClass>,
   public IDispatchImpl<IMyClass, &IID_IMyClass, &LIBID_NVC_ATL_COMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>,
   public IDispatchImpl<IMyDualInterface, &__uuidof(IMyDualInterface), &LIBID_NVC_ATL_COMLib, /* wMajor = */ 1, /* wMinor = */ 0>
{
public:
   DECLARE_CLASSFACTORY2(CMyLicense)

   // Remainder of class declaration omitted

要求

标头：atlcom.h

CComCoClass::CreateInstance

使用这些 CreateInstance 函数创建 COM 对象的实例，并在不使用 COM API 的情况下检索接口指针。

template <class  Q>
static HRESULT CreateInstance( Q** pp);

template <class  Q>
static HRESULT CreateInstance(IUnknown* punkOuter, Q** pp);

参数

Q
应该通过 pp 返回的 COM 接口。

punkOuter
[in] 聚合的外部未知或控制未知。

pp
[out] 如果创建成功，则为某个接收请求的接口指针的指针变量的地址。

返回值

标准 HRESULT 值。 有关可能的返回值的说明，请参阅 Windows SDK 中的 CoCreateInstance。

备注

将此函数的第一个重载用于典型对象创建；需要聚合所创建的对象时，请使用第二个重载。

实现所需 COM 对象的 ATL 类（即用作 CComCoClass 的第一个模板参数的类）必须与调用代码位于同一项目中。 COM 对象的创建由为此 ATL 类注册的类工厂执行。

这些函数用于创建特定的对象，你已阻止使用 OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO 宏在外部创建这些对象。 在出于效率原因而需要避免使用 COM API 的情况下，它们也很有用。

请注意，接口 Q 必须与可以使用 __uuidof 运算符进行检索的 IID 相关联。

示例

在以下示例中，CDocument 是向导生成的 ATL 类，该类派生自 CComCoClass，而后者可实现 IDocument 接口。 该类使用 OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO 宏在对象映射中注册，因此客户端无法使用 CoCreateInstance 创建文档的实例。 CApplication 是一个 CoClass，它在其自己的 COM 接口之一上提供一个方法来创建文档类的实例。 下面的代码显示使用从 CComCoClass 基类继承的 CreateInstance 成员创建文档类的实例是多么容易。

STDMETHODIMP CMyApp::CreateDocument( /* [out, retval] */ IDocument** ppDoc)
{
   *ppDoc = NULL;
   return CMyDoc::CreateInstance(ppDoc);
}

CComCoClass::Error

此静态函数设置 IErrorInfo 接口，以便向客户端提供错误信息。

static HRESULT WINAPI Error(
    LPCOLESTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCOLESTR lpszDesc,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCSTR lpszDesc,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    LPCSTR lpszDesc,
    DWORD dwHelpID,
    LPCSTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0);

static HRESULT WINAPI Error(
    UINT nID,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance ());

static HRESULT Error(
    UINT nID,
    DWORD dwHelpID,
    LPCOLESTR lpszHelpFile,
    const IID& iid = GUID_NULL,
    HRESULT hRes = 0,
    HINSTANCE hInst = _AtlBaseModule.GetResourceInstance());

参数

lpszDesc
[in] 描述错误的字符串。 Error 的 Unicode 版本指定 lpszDesc 的类型为 LPCOLESTR；ANSI 版本指定的类型为 LPCSTR。

iid
[in] 定义错误的接口的 IID；如果错误由操作系统定义，则为 GUID_NULL（默认值）。

hRes
[in] 你希望其返回到调用方的 HRESULT。 默认值为 0。 有关 hRes 的更多详细信息，请参阅“备注”。

nID
[in] 存储错误说明字符串的资源标识符。 此值应在 0x0200 到 0xFFFF 之间（含）。 在调试版本中，如果 nID 未为有效字符串编制索引，则会导致 ASSERT。 在发布版本中，错误说明字符串将设置为“未知错误。”

dwHelpID
[in] 错误的帮助上下文标识符。

lpszHelpFile
[in] 描述错误的帮助文件的路径和名称。

hInst
[in] 资源的句柄。 默认情况下，此参数为 _AtlModule::GetResourceInstance，其中的 _AtlModule 是 CAtlModule 的全局实例。

返回值

标准 HRESULT 值。 有关详细信息，请参阅“备注”。

备注

若要调用 Error，对象必须实现 ISupportErrorInfo 接口。

如果 hRes 参数不为零，则 Error 返回 hRes 的值。 如果 hRes 为零，则 Error 的前四个版本会返回 DISP_E_EXCEPTION。 最后两个版本会返回宏 MAKE_HRESULT( 1, FACILITY_ITF,nID) 的结果。

CComCoClass::GetObjectCLSID

提供一种检索对象的 CLSID 的一致方法。

static const CLSID& WINAPI GetObjectCLSID();

返回值

对象的类标识符。

CComCoClass::GetObjectDescription

此静态函数检索类对象的文本说明。

static LPCTSTR WINAPI GetObjectDescription();

返回值

类对象的说明。

注解

默认实现返回 NULL。 可以使用 DECLARE_OBJECT_DESCRIPTION 宏替代此方法。 例如：

class ATL_NO_VTABLE CMyDoc :
   public CComObjectRootEx<CComSingleThreadModel>,
   public CComCoClass<CMyDoc, &CLSID_MyDoc>,
   public IDocument
{
public:
   DECLARE_OBJECT_DESCRIPTION("My Document Object 1.0")

   // Remainder of class declaration omitted.

GetObjectDescription 由 IComponentRegistrar::GetComponents 调用。 IComponentRegistrar 是一个自动化接口，可用于在 DLL 中注册和取消注册单个组件。 使用 ATL 项目向导创建组件注册器对象时，向导将自动实现 IComponentRegistrar 接口。 IComponentRegistrar 通常由 Microsoft Transaction Server 使用。

有关 ATL 项目向导的详细信息，请参阅创建 ATL 项目一文。

另请参阅

类概述