C 语言 COM 组件开发系列 第三部分

请注意，ICollection 的 IDispatch 函数使用这个新的 ITypeInfo，而 IExample3 的 IDispatch 函数使用 IExample3 的 ITypeInfo。它们不是同一个 ITypeInfo，也不能互换使用。

剩下要做的就是编写三个额外函数：Count、Item 和 _NewEnum。

Count 函数很简单。它接收一个指向 long 的指针。Count 将该指针填充为我们列表中项的总数。例如，上面我们列表中的三个端口（IENUMITEM 结构），因此我们将返回 3。

这是我们的 Count 函数

STDMETHODIMP Count(ICollection *this, long *total)
{
   DWORD     count;
   IENUMITEM *item;

   // Count how many items in the list by just walking it all
   // the way to the last IENUMITEM, incrementing a count for
   // each item.
   count = 0;
   item = (IENUMITEM *)&PortsList;
   while ((item = item->next)) ++count;

   // Return the total.
   *total = count;

   return(S_OK);
}

Item 函数也很简单。它接收一个 long，告诉我们正在查询哪个项（其中 0 是第一项，1 是第二项，依此类推）。它还接收一个 VARIANT，我们将项的值复制到其中。

这是我们的 Item 函数

STDMETHODIMP Item(ICollection *this, long index, VARIANT *ret)
{
   IENUMITEM  *item;

   // Assume we have nothing to return.
   ret->vt = VT_EMPTY;

   // Locate to the item that the caller wants.
   item = (IENUMITEM *)PortsList;
   while (item && index--) item = item->next;

   // Any more items left?
   if (item)
   {
      // Copy the item's value to the VARIANT that the caller supplied.
      // If what we're returning to the caller is an object, we must AddRef()
      // it on the caller's behalf. The caller is expected to Release() it
      // when done with it. If what we're returning is a BSTR, then we must
      // SysAllocString a copy of it. Caller is expected to SysFreeString it.
      // Other datatypes are simply copied to the caller's VARIANT as is.
      // VariantCopy() does all this for us. It also returns S_OK if all
      // went well.
      return(VariantCopy(ret, &item->value));
   }

   // If no more items, return S_FALSE.
   return(S_FALSE);
}

如上面的注释所示，OLE 函数 VariantCopy 为我们完成了大部分工作。

目前，我们将忽略 _NewEnum 函数。我们将插入一个模拟函数，它返回 E_NOTIMPL。

一旦我们编写了所有 ICollection 函数，我们就可以静态声明其 VTable

static const ICollectionVtbl ICollectionVTable = 
      {Collection_QueryInterface,
       Collection_AddRef,
       Collection_Release,
       GetTypeInfoCount,
       GetTypeInfo,
       GetIDsOfNames,
       Invoke,
       Count,
       Item,
       _NewEnum};

应用程序如何获取我们的集合对象

让我们考虑一下应用程序如何获取我们 MyRealICollection 对象之一。最简单的方法是为我们的 IExample3 对象添加另一个（额外的）函数。应用程序将调用此新函数来分配并接收我们的 MyRealICollection 对象之一。（但我们会欺骗应用程序，告诉它这只是一个普通的 IDispatch。）

我们需要更改 IExample3 VTable 的定义（在 IExample3.h 中），以添加这个新函数，我将任意命名为 GetPorts。我将其定义为接收一个 IDispatch 的句柄，我们将在此处返回指向我们新分配的 MyRealICollection...呃...IDispatch 的指针。是的，就是这样。它只是一个 IDispatch。眨眼眨眼。这是我们更新的 IExample3 VTable

// IExample3's VTable
#undef  INTERFACE
#define INTERFACE IExample3
DECLARE_INTERFACE_ (INTERFACE, IDispatch)
{
    // IUnknown functions
    STDMETHOD  (QueryInterface) (THIS_ REFIID, void **) PURE;
    STDMETHOD_ (ULONG, AddRef) (THIS) PURE;
    STDMETHOD_ (ULONG, Release) (THIS) PURE;
    // IDispatch functions
    STDMETHOD_ (ULONG, GetTypeInfoCount)(THIS_ UINT *) PURE;
    STDMETHOD_ (ULONG, GetTypeInfo) (THIS_ UINT, LCID, ITypeInfo **) PURE;
    STDMETHOD_ (ULONG, GetIDsOfNames) (THIS_ REFIID, LPOLESTR *, 
                UINT, LCID, DISPID *) PURE;
    STDMETHOD_ (ULONG, Invoke) (THIS_ DISPID, REFIID, LCID, 
                WORD, DISPPARAMS *, VARIANT *, EXCEPINFO *, UINT *) PURE;
    // Extra functions
    STDMETHOD  (SetString) (THIS_ BSTR) PURE;
    STDMETHOD  (GetString) (THIS_ BSTR *) PURE;
    STDMETHOD  (GetPorts) (THIS_ IDispatch **) PURE;  // <--- Added GetPorts here
};

请注意，我将 GetPorts 添加到了 VTable 的末尾。另请注意，我指定 GetPorts 将填写一个 IDispatch 指针（即使它实际上是我们的 MyRealICollection）。它是一个 IDispatch。诚实。我会撒谎吗？

并且，我必须在 IExample3 VTable 的 IDL 文件中进行相同的更改

[uuid(CFADB388-9563-4591-AABB-BE7794AEC17C), dual, 
             oleautomation, hidden, nonextensible]
interface IExample3VTbl : IDispatch
{
   [helpstring("Sets the test string.")]
   [id(1), propput] HRESULT Buffer([in] BSTR);
   [helpstring("Gets the test string.")]
   [id(1), propget] HRESULT Buffer([out, retval] BSTR *);
   [helpstring("Gets the enumeration for our hardware ports.")]
   [id(2), propget] HRESULT Ports([out, 
           retval] IDispatch **);  // <--- Added GetPorts here
};

请注意，我将这个新添加的函数作为 propget，就像 Buffer 一样。这样，脚本就可以使用普通的赋值指令来获取我们的 MyRealICollection... duh！...IDispatch 对象。从脚本的角度来看，该成员名为“Ports”。我们实际上在 IExample3 对象中没有 Ports 数据成员，这无关紧要。这是一种虚假的成员。但脚本不需要知道这一点。

并且，我任意给它一个 DISPID 为 2。

别忘了，我们需要将此函数添加到 IExample3.c 中的静态声明的 IExample3Vtbl 中

static const IExample3Vtbl IExample3_Vtbl = {QueryInterface,
AddRef,
Release,
GetTypeInfoCount,
GetTypeInfo,
GetIDsOfNames,
Invoke,
SetString,
GetString,
GetPorts}; // <--- Added GetPorts here

所以，我们需要编写 GetPorts 函数

static HRESULT STDMETHODCALLTYPE GetPorts(IExample3 *this, IDispatch **portsObj)
{
   // Create an IDispatch to enumerate our port names.
   // Caller is responsible for Release()'ing
   // it. NOTE: We're really returning a MyRealICollection,
   // but the caller doesn't know that.
   // He thinks we're returning an IDispatch,
   // which is ok because a MyRealICollection's
   // VTable starts with the 3 IUnknown functions
   // followed by the 4 IDispatch functions, just
   // like a real IDispatch object's VTable
   if (!(*portsObj = allocPortsCollection()))
      return(E_OUTOFMEMORY);
}

上面只是调用了我们将在 PortNames.c 中放置的另一个辅助函数（名为 allocPortsCollection）。这个辅助函数负责 GlobalAlloc 一个 MyRealICollection 并对其进行初始化。这与我们 IClassFactory 的 CreateInstance 分配一个 IExample3 并对其进行初始化非常相似。我们甚至增加了未完成对象计数，因为我们的 MyRealICollection...呃...IDispatch 对象将被提供给某个应用程序（预计之后会 Release 它）。

IDispatch * allocPortsCollection(void)
{
   MyRealICollection *collection;

   // Allocate a MyRealICollection
   if ((collection = (MyRealICollection *)GlobalAlloc(
                      GMEM_FIXED, sizeof(MyRealICollection))))
   {
      // Store its VTable
      collection->lpVtbl = (ICollectionVtbl *)&ICollectionVTable;

      // AddRef it
      collection->count = 1;

      // Indicate another outstanding object since we'll be returning it
      // to an application which is expected to Release() it
      InterlockedIncrement(&OutstandingObjects);
   }

   // Return it as if it were an IDispatch (which it can be used as)
   return((IDispatch *)collection);
}

我们完成了。你可以编译 IExample3.dll。要注册它，只需获取 IExample2 的注册实用程序（RegIExample2）并将每个“IExample2”替换为“IExample3”。毕竟，IExample3 没有什么需要我们以不同于 IExample2 的方式注册它的。同样，要注销它，请修改 IExample2 的注销实用程序（UnregIExample2）。

VBScript 示例

让我们编写一个使用我们的集合来显示端口名称的 VBScript 示例。我已经编写了这样一个示例（IExample3.vbs），并将其放在 IExample3 目录中。

当然，VBScript 需要首先调用 CreateObject 来获取我们的 IExample3 对象之一。如果安装正确，它应该具有 ProductID “IExample3.object”。现在脚本拥有了我们的 IExample3，它就可以简单地访问那个虚假的“Ports”成员来获取我们 MyRealICollection... 该死！...IDispatch 对象来使用。这里，我们将其分配给一个名为“coll”的变量。

Set coll = myObj.Ports

接下来，我们可以调用 Count 函数来确定有多少个端口名称。实际上，因为我们的类型库将此函数定义为 propget，所以脚本可以使用赋值。

count = coll.Count

现在，我们循环调用 Item 函数来获取每个端口名称，并显示它

For i = 0 To count - 1
   MsgBox coll.Item(i)
Next

就是这样。

C 语言示例

对于 C/C++ 应用程序使用我们的集合对象，它需要间接通过 Invoke 函数来调用我们的 Count 和 Item 函数。坐稳了，这将会是一段颠簸的旅程。MS Visual Basic 程序员设计了 IDispatch 函数，以便可以轻松地将参数传递给它们，并从中返回参数，以便那些人可以轻松地为 VB 添加 COM 支持并尽快发布。但他们并没有考虑从其他语言使用 IDispatch 函数的便利性。从 C/C++ 来看，这是一个非常麻烦的事情。

在 IExample3App 目录中，有一个 C 语言应用程序示例，它执行与上面的 VBScript 相同的功能。它获取我们的 Ports 集合对象，并使用它来显示所有端口的名称。我不打算讨论 C 应用程序如何获取我们的 IExample3 对象。这与它获取 IExample2 对象的方式完全相同（除了我们 #include IExample3.h，并使用 IExample3 对象的 GUID）。

主要关注点从我们调用我们 IExample3 的 GetPorts 函数以获取我们 MyRealICollection...*咳嗽*...IDispatch 对象开始。这从我在（IExample3App.c 中）放置以下注释的地方开始

// STUDY THIS

仔细阅读所有代码并阅读注释。它们详细说明了您需要采取的步骤才能从 C/C++ 使用 IDispatch 函数。然后，请一位 MS Visual Basic 程序员出去吃午饭以“感谢”他，并在他没注意的时候在他的食物里放很多辣椒。

IEnumVARIANT 对象

如果我们查看我们 Item 函数中的以下几行，可能会引起警觉

// Locate to the item that the caller wants.
item = (IENUMITEM *)PortsList;
while (item && index--) item = item->next;

每次有人调用我们的 Item 函数时，我们都必须从列表开头开始，搜索到所需的项。假设列表中有 30,000 个项。例如，应用程序要求我们获取第 28,000 项。我们必须遍历 27,000 个项才能找到所需的项。现在，假设应用程序再次调用 Item 来请求第 29,000 项。即使它只差一个链接，我们也会从列表开头重新开始，并遍历 28,000 个项。显然，这效率不高。

我们可以也许为我们的 MyRealICollection 添加另一个数据成员。该成员将存储我们最后一次停留在列表中的“位置”。微软考虑了这一点，然后决定，与其 monkey-ing around with the collection object（由于 VB 开发人员的原因，这个对象实际上并不适合从 C/C++ 高效调用），不如定义第二个标准 COM 对象，称为 IEnumVARIANT。IEnumVARIANT 的主要目的是存储应用程序“读取”的列表中的当前位置。但考虑到 C/C++ 应用程序通过 Invoke 间接调用我们集合的 Item 函数是多么低效和麻烦，MS 决定在 IEnumVARIANT 中设置一些函数，应用程序可以直接调用这些函数来完成我们之前使用集合的 Item 函数所做的事情……甚至更多。具体来说，IEnumVARIANT 有四个函数（当然，再加上三个 IUnknown 函数），分别命名为 Next、Skip、Reset 和 Clone。

• IEnumVARIANT 的 Next 函数使我们集合对象的 Item 函数变得多余。通过一次调用 Next，应用程序可以一次返回多个项的值（通过提供要返回的项数，以及一个用于存储所有值的 VARIANT 数组）。因此，应用程序可以调用 Next 来读取四个项。在下一次调用 Next 时，我们的 IEnumVARIANT 将自动从列表中的第五个项开始读取，并返回应用程序请求的任意数量的值。
• IEnumVARIANT 的 Reset 仅将位置重置回列表的开头。
• IEnumVARIANT 的 Skip 将位置设置为某个点（即，它类似于在磁盘文件中查找，但在这里它是在我们的列表中设置位置）。
• IEnumVARIANT 的 Clone 分配（并返回给应用程序）另一个 IEnumVARIANT 对象，其位置与被克隆的 IEnumVARIANT 相同。这用于在应用程序想要嵌套循环并且需要记住特定列表中的多个位置的情况下。

微软已经定义了（在其编译器附带的包含文件中）一个 IEnumVARIANT 对象及其 VTable（即，微软已经决定了 VTable 中有哪些函数、这些函数接收什么参数以及它们返回什么）。因此，我们无需执行此操作。但是，与我们迄今为止创建的所有对象一样，我们需要为我们的 IEnumVARIANT 添加一些额外的成员。因此，我们将再次定义一个 MyRealIEnumVariant，其中包含这些额外成员。

但在我们修改 IExample3 源代码之前，让我们再次创建一个名为 IExample4 的新目录。我们将复制源代码到新目录，然后重命名/编辑它们。搜索并替换“IExample3”为“IExample4”。运行 GUIDGEN.EXE 创建新的 GUID，并将它们放入 IExample4.h、PortNames.h 和 IExample4.idl。再次，我已经为你完成了这些，并创建了一个包含新文件的 IExample4 目录。

在 PortNames.c 中，我们将添加我们 MyRealIEnumVariant 对象的定义，编写其所有函数，并静态声明其 VTable。所有这些都从注释开始

//==============================================================
//=================== IEnumVARIANT functions ===================
//==============================================================

事实上，现在你应该很熟悉它的 QueryInterface、AddRef 和 Release 函数的作用了。而其他四个函数则相当简单，你可以通过阅读源代码注释来了解这些函数的详细信息。

真正的问题是“应用程序如何获取我的 IEnumVARIANT 对象之一？”。还记得之前我们忽略了集合对象的 _NewEnum 函数，并让它返回 E_NOTIMPL 吗？猜猜怎么着。这就是应用程序调用的函数，用于获取我们的 IEnumVARIANT 对象之一，所以现在我们必须编写一些实际的代码。

换句话说，要获取我们的 IEnumVARIANT 之一，应用程序必须首先获取我们的 IExample4 对象，调用我们的 IExample4 的 GetPorts 函数以获取我们的集合对象，然后调用我们集合的 _NewEnum 函数以获取 IEnumVARIANT。这不是最快的方式，但这就是它的工作方式。一些坏消息：C/C++ 应用程序无法直接调用我们集合的 _NewEnum 函数。就像我们集合的 Count 和 Item 函数一样，C/C++ 应用程序必须通过 Invoke 间接调用 _NewEnum。糟糕。好消息是，一旦我们的 C/C++ 应用程序获得了 IEnumVARIANT，就可以 Release() 我们的集合对象，这样我们就可以摆脱后者了。

所以，让我们看看我们集合的 _NewEnum 函数

STDMETHODIMP _NewEnum(ICollection *this, IUnknown **enumObj)
{
   IEnumVARIANT *enumVariant;

   if (!(enumVariant = allocIEnumVARIANT())) return(E_OUTOFMEMORY);
   *enumObj = (IUnknown *)enumVariant;
   return(S_OK);
}

这只是调用我们名为 allocIEnumVARIANT 的辅助函数，它分配并初始化我们的 IEnumVARIANT（实际上是 MyRealIEnumVariant），就像我们 IClassFactory 的 CreateInstance 分配我们的 IExample4 对象，或者我们 IExample4 的 GetPorts 函数分配我们的集合对象一样。这里没有什么新鲜事。

但请注意，_NewEnum 要求应用程序传递一个句柄，我们在其中返回一个 IUnknown 对象——而不是 IEnumVARIANT。是的，我们实际上返回的是我们的 IEnumVARIANT，但它伪装成 IUnknown 对象，并且可以做到这一点，因为它的 VTable 以三个 IUnknown 函数开头。

“但为什么要伪装？你不是刚刚说过 _NewEnum 用于获取我们的 IEnumVARIANT 吗？”

是的……以一种迂回的方式。[切换到恐怖怪物电影配乐。]

在之前的文章中，我曾暗示 COM 对象实际上可能包含多个 VTable。我们说这样的对象具有“多个接口”。微软决定 _NewEnum 应该能够传递一个可以有多个接口的对象，而 IEnumVARIANT 可能只是它其中的一个 VTable（甚至不是对象中的第一个 VTable）。因此，应用程序应该做的是获取我们给它的 IUnknown 对象，并调用该对象的 QueryInterface，传递 IEnumVARIANT 的 GUID（IID_IEnumVARIANT，它在微软的包含文件中为我们定义）。然后，QueryInterface 将返回指向 IEnumVARIANT VTable 的指针（即，基本上是从 whatever object that IUnknown object really is 中嵌入的 IEnumVARIANT——因为你知道它就是别的什么伪装成 IUnknown）。

在我们的例子中，应用程序将调用我们 IEnumVARIANT 的 QueryInterface，要求我们提供一个 IEnumVARIANT。而我们只会再次返回相同的指针。完全不必要。效率低下。不合逻辑。但 COM 有时就是这样，当其中有些部分是由 MS VB 开发人员设计的（他们对使整个 IDispatch 事情变得非常像 VB 内部调用其自身内置函数很感兴趣，从而最大限度地减少了他们的工作，并将这种设计强加给其他人，无论多么不方便和笨拙），而其他程序员则希望使用多接口之类的东西（VB 脚本甚至无法直接使用——真是个笑话）。

总之，我们已经完成了 IEnumVARIANT 的支持，因此我们可以编译 IExample4.dll。要注册它，再次，您可以修改 RegIExample2.c，搜索并替换“IExample2”为“IExample4”。

另一个 VBScript 示例

VBScript 绝对无法调用我们集合的 _NewEnum 函数（因为这可能会返回一个具有多个接口的对象，需要进行 QueryInterface——而 VBScript 无法处理这样的对象）。因此，VBScript 无法获取我们的 IEnumVARIANT 并调用其函数。

这是否意味着 IEnumVARIANT 对 VBScript 无用？不。VBScript 引擎本身可以使用我们的 IEnumVARIANT。引擎何时会这样做？当脚本使用 For Each 循环来枚举我们集合中的项时。在 IExample4 目录中有一个名为 IExample4.vbs 的 VBScript，它使用了这样一个 For Each 循环。这是一种不同的方式，可以让脚本完成与 IExample3.vbs 相同的事情，但在底层更有效率（因为引擎使用我们的 IEnumVARIANT 的 Next 函数，而不是 VBScript 使用我们集合对象的 Item 函数）。而且，脚本端的代码也稍少一些，因为引擎代表脚本检索项的值。下面是如何完成的

set myObj = CreateObject("IExample4.object")
Set coll = myObj.Ports
For Each elem In coll
   MsgBox elem
Next

前两行与 IExample3.vbs 相同（只是我们现在使用的是 IExample4.dll 的 ProductID）。

但循环不同。当 VBScript 引擎执行 For Each 行时，它会获取我们的 IEnumVARIANT（通过调用我们集合的 _NewEnum，并执行 QueryInterface 以获取 IID_IEnumVARIANT）。它将此 IEnumVARIANT 存储在内部，以便在循环的后续迭代中使用。然后，它调用我们 IEnumVARIANT 的 Next 函数，请求返回一项的值。当然，第一次调用 Next 时，我们返回第一个项的端口名称（即字符串“Port 1”）。VB 引擎将此字符串存入变量“elem”。这一切都在这一行 VBScript 指令中完成。现在，脚本只需显示“elem”的值（即字符串“Port 1”）。在下一次循环迭代中，VB 引擎再次调用我们 IEnumVARIANT 的 Next 函数，请求另一个项的值。这是第二次调用 Next，因此，当然，我们返回第二项的值，即字符串“Port 2”。VB 引擎现在将 elem 变量更新为这个新值。然后脚本显示“Port 2”。这会一直持续下去，直到 VB 引擎调用我们 IEnumVARIANT 的 Next，而我们没有更多项要返回。此时，Next 返回 S_FALSE（而不是 S_OK）给引擎。然后，引擎退出循环（并 Release 我们的 IEnumVARIANT）。

另一个 C 语言示例

在 IExample4App 目录中，有一个 C 语言示例演示了如何获取和使用我们的 IEnumVARIANT。我们仍然需要处理集合对象及其 Invoke。但至少，循环更有效率。而且整个过程比使用集合对象的 Item 函数要简单一些。

更通用的方法

如果您查看 PortName.c 中的 IEnumVARIANT 和集合函数，您会发现它们是硬编码的，只能作用于我们的端口名称列表（即 PortsList）。但是，通过一点重构，我们可以重写这些函数，使它们能够作用于我们提供的任何 IENUMITEM 链表。换句话说，我们可以使这些函数通用，因此如果我们的组件需要维护几种不同类型的列表，我们可以更容易地提供进一步的集合和 IEnumVARIANT 对象，它们可以重用这些相同的函数而无需进一步修改。因此，让我们将 IEnumVARIANT 和集合函数分离到一个名为 IEnumVariant.c 的新独立源文件中。唯一留在 PortNames.c 中的代码是专门访问我们 PortsList 的代码。

但首先，我们将执行创建新的 IExample5 目录、将文件复制到那里、然后重命名/编辑它们的操作。您现在应该熟悉这个过程了。我已经完成了工作，并创建了一个 IExample5 目录。

与仅声明一个表示列表本身的全局变量不同，我们将把列表包装在一个我们称之为 IENUMLIST 的新结构中，如下所示

typedef struct {
   struct _IENUMITEM *head;
   DWORD             count;
} IENUMLIST;

head 成员是存储列表的地方。并且我们添加了一个 count 字段，每次我们创建一个使用该特定列表的集合或 IEnumVariant 对象时，该字段都会递增。

现在，我们将 PortsList 全局变量更改为此新结构

IENUMLIST    PortsList;

使我们的集合和 IEnumVARIANT 函数更通用的关键是向我们的 MyRealIEnumVariant 和 MyRealICollection 对象添加一个额外的数据成员。我们将向我们的 MyRealICollection 添加一个成员，该成员持有指向它应该操作的 IENUMLIST 的指针。并且，我们将编写一个新的辅助函数来分配一个 MyRealICollection 对象。此辅助函数将接收该 IENUMLIST 指针，并将其存储在我们 MyRealICollection 中添加的这个新数据成员中。我已经编写了一个这样的函数（allocICollection）并将其放在 IEnumVariant.c 中。它接收指向我们希望集合对象操作的任何 IENUMLIST 的指针。