在COM中使用数组参数-ICollection
关键字:DCOM、数组、自定义类型、Marshal、SafeArray、ICollection
ICollection是从 IDispatch继承的接口。ICollection还需要一个IEnumVARIANT接口配合实现功能。IEnumVARIANT是从IUnknown继承的,而不是从IDispatch接口继承。
ICollection接口提供了最大的面向对象的设计灵活性和可重用性。在数组指针和SafeArray方法中,数组的每个元素必须事先计算出来,并且保存在特定的数据结构中。使用ICollection接口,可以设计出动态生成的数组,就是说数组的元素在需要的时候才进行计算,以便减少内存使用并加快处理速度。
ICollection接口用于定义数组对象,而IEnumVARIANT接口用于定义枚举对象。枚举对象的作用是按顺序读取数组元素,有时,通过枚举对象可以获得更高的效率。
ICollection和IEnumVARIANT的定义如下:
interface ICollection : IDispatch
{
[propget, id(DISPID_LISTITEM)] HRESULT Item(
[in] const VARIANT varIndex,
[out, retval] VARIANT *pVal);
[propget, id(DISPID_LISTCOUNT)] HRESULT Count(
[out, retval] long *pVal);
[propget, id(DISPID_COLLCOUNT)] HRESULT length(
[out, retval] long *pVal);
[propget, id(DISPID_NEWENUM), restricted, hidden]
HRESULT _NewEnum([out, retval] IUnknown* *pVal);
... // 其它方法或属性
};
interface IEnumVARIANT : IUnknown
{
HRESULT Next(
unsigned long celt,
VARIANT * rgvar,
unsigned long * pceltFetched);
HRESULT Skip(unsigned long celt);
HRESULT Reset();
HRESULT Clone(IEnumVARIANT ** ppenum);
};
有的时候,COM对象不但要实现数组功能,而且还要实现其它功能。所以,大多数时候,COM对象实现的接口是从ICollection继承来的。
通过ICollection操纵数组大体上有两种方法。一种是通过Item属性用数组下标取得元素。这种方式,每次只能取得一个元素,而且要传递下标对象,所以效率比较低下。另一种方法是通过枚举器。数组对象的枚举器通过_NewEnum属性取得。通过枚举器只能按顺序获取元素,但每次可以取得任意多的元素,所以效率较高。ICollection对象可以只实现其中的一种访问方法,也可以两种都实现。ICollection中还有一个重要属性:Count。Count属性返回数组的长度,对于无法确定长度的数组,也可以不实现Count属性。
IEnumVARIANT接口用于定义枚举器。枚举器用于顺序读取数组元素。通过Next方法,可以一次读取任意多的元素。由于枚举器只可以按顺序访问数组元素,所以Next方法不需要传递下标。Skip方法用于跳过若干元素,而不读取。Reset把当前元素设置到数组头,这样就可以重新开始枚举。Clone用于获得一个新的枚举器。两个枚举器可以互不干扰的工作。
要注意的事,可能有某些数组对象的实现方法使用不同的属性名称。实际上ICollection中的属性名称是不重要的,重要的是Dispatch ID。只要通过Dispatch ID就可以取得正确的属性。
数组对象是实现了ICollection接口的COM对象。数组对象的使用者通过ICollection接口取得数组中的数据,而完全不需要知道数组的具体实现方式。这种设计的好处是使用数组的代码可以完全不理会数组的实现方法,而当数组的实现发生变化时,使用数组的代码可以在二进制代码上保持兼容,也就是说目标代码不用编译就可以使用。
最简单制作数组对象的方法是使用ATL的模板。CComEnumOnSTL模板用于生成实现IEnumVARIANT接口的枚举对象。当然,如果要实现数组对象的所有优点,最好自己编写数组对象的代码。
在IDL声明中。数组对象应该声明成IDispatch *。如果是输出或输入输出参数,则应该使用双重指针。
[id(0)] GetNumber([out] IDispatch ** ppObj);
[id(1)] SetNumber([in] IDispatch * pObj);
目前,我们看到的ICollection数组都是只读的。实际上ICollection完全可以设计成可读写的数组对象,只要把ICollection的Item属性设置成可读写的就可以了。关于可读写的ICollection对象请参考相关资料。
ATL通过两个模板实现对ICollection的支持。它们就是CComEnumOnSTL和ICollectionOnSTLImpl。CComEnumOnSTL用于实现基于STL对象的枚举器。ICollectionOnSTLImpl用于实现ICollection接口。下面详细描述这两个模板的功能和用法。
CComEnumOnSTL的定义如下:
template
const IID* piid,
class T,
class Copy,
class CollType,
class ThreadModel = CComObjectThreadModel>
class ATL_NO_VTABLE CComEnumOnSTL :
public IEnumOnSTLImpl
public CComObjectRootEx< ThreadModel >
模板参数中,Base是枚举器所实现的接口,通常是IEnumVARIANT。piid是枚举器接口的IID,通常是IID_IEnumVARIANT。T是枚举器输出数值的类型,通常是VARIANT。Copy是复制类,用于将STL对象中的值转换成枚举器输出参数。CollType是用于存储数据的STL类型。ThreadModel是线程模式参数,可以是CComSingleThreadModel或CcomMultiThreadModel,缺省值是当前缺省的线程模式。
假设使用vector类保存数组元素。而vector参数是long型数据。可以通过以下方法实现枚举器。
typedef std::vector
Copy类用于在STL类的元素类型和枚举器类型之间进行参数转换。每个Copy类必须有三个静态函数:init、copy、destroy。Init用于初始化枚举器类、copy用于把STL元素复制到枚举器参数、destroy用于销毁枚举器参数。
下面是用于在long和VARIANT之间转换的Copy类实例。
class CopyVariantLong
{
public:
static void init(VARIANT * p)
{
VariantInit(p);
}
static HRESULT copy(VARIANT * pTo, const LONG * pFrom)
{
pTo->vt = VT_I4;
pTo->lVal = *pFrom;
return S_OK;
}
static void destroy(VARIANT * p)
{
VariantClear(p);
}
};
通过以上定义的类就可以方便的定义枚举器类型了。
typedef CComEnumOnSTL
&IID_IEnumVARIANT,
VARIANT,
CopyVariantLong,
CollType> EnumType;
ICollectionOnSTLImpl用于帮助实现ICollection接口。ICollectionOnSTLImpl定义如下:
template
class CollType,
class ItemType,
class CopyItem,
class EnumType>
class ICollectionOnSTLImpl : public T
在ICollectionOnSTLImpl模板中,T是要实现的接口,一般会使用从ICollection继承的接口。CollType参数是用于保存数据的STL类型,这个类型应该和枚举器中的相同。ItemType是ICollection中Item属性的类型,一般是VARIANT。CopyItem是Item属性的Copy类,和枚举器中的Copy类是相同的。EnumType是枚举器的类型。
可以通过以下步骤实现ICollection接口。
typedef ICollectionOnSTLImpl
CollType,
VARIANT,
CopyVariantLong,
EnumType> CollectionType;
定义数组对象和定义普通ATL的COM对象是类似的。只要把IDispatchImpl中的接口参数(第一个参数)变成刚刚完成的ICollectionOnSTLImpl参数就可以了。
class ATL_NO_VTABLE CNumberCollection :
public CComObjectRootEx
public CComCoClass
public IDispatchImpl
&IID_INumberCollection,
&LIBID_COLLECTIONOBJLib>
{
...
}
对于通用的ICollection对象,只能够通过IDispatch访问。也就是说通过IDispatch::Invoke方法访问数组中的元素。
另一方面,ICollection对象通常指通过VARIANT类型传递数据。所以,我们也必须了解如何访问VARIANT类型的变量。
IDispatch是Automation中定义的接口。通过IDispatch,COM客户可以取得接口中每个方法和属性的类型、参数和返回值等信息。通过IDispatch的Invoke方法,COM客户还可以直接调用接口中的方法和属性。IDispatch的内容非常丰富,这里不可能做全面地介绍,所以指对如何通过Invoke方法调用IDispatch做一个简单的说明。
HRESULT Invoke(
DISPID dispIdMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS FAR* pDispParams,
VARIANT FAR* pVarResult,
EXCEPINFO FAR* pExcepInfo,
unsigned int FAR* puArgErr
);
Invoke的参数如下:
l dispIdMember:所调用的属性或方法的dispatch id
l riid:保留,必须是IID_NULL
l lcid:语言环境。一般使用LOCALE_THREAD_DEFAULT
l wFlags:可以是以下四个参数之一:
DISPATCH_METHOD方法调用
DISPATCH_PROPERTYGET()读属性
DISPATCH_PROPERTYPUT()写属性
DISPATCH_PROPERTYPUTREF()通过引用写属性
l pDispParams:参数数组
l pVarResult:返回值
l pExcepInfo:被调用方法或属性内部异常(如果发生异常)
l puArgErr:当返回DISP_E_PARAMNOTFOUND或DISP_E_TYPEMISMATCH时,返回出错的参数序号。
以下是使用Invoke的例子。下例返回一个dispatch id是DISPID_LISTCOUNT的简单参数,实际上就是数组的长度。
VARIANT varResult;
DISPPARAMS DispParams;
EXCEPINFO excepInfo;
UINT errArg;
VariantInit(&varResult);
DispParams.cArgs = 0;
DispParams.cNamedArgs = 0;
DispParams.rgdispidNamedArgs = NULL;
DispParams.rgvarg = NULL;
hr = pObj->Invoke(
DISPID_LISTCOUNT,
IID_NULL,
LOCALE_USER_DEFAULT,
DISPATCH_PROPERTYGET,
&DispParams,
&varEnum,
&excepInfo,
&errArg);
if (FAILED(hr))
{
goto CleanUp;
}
下例返回一个带参数的属性。
VARIANT varIndex;
VARIANT varResult;
DISPPARAMS DispParams;
EXCEPINFO excepInfo;
UINT errArg;
VariantInit(&varIndex);
VariantInit(&varResult);
DispParams.cArgs = 1;
DispParams.cNamedArgs = 0;
DispParams.rgdispidNamedArgs = NULL;
DispParams.rgvarg = &varIndex;
VariantClear(&varIndex);
VariantClear(&varResult);
varIndex.vt = VT_I2;
varIndex.iVal = (short) Index;
hr = pObj->Invoke(
DISPID_LISTITEM,
IID_NULL,
LOCALE_USER_DEFAULT,
DISPATCH_PROPERTYGET,
&DispParams,
&varResult,
&excepInfo,
&errArg);
if (FAILED(hr))
{
...
}
要使用IEnumVARIANT枚举数据,首先必须取得IEnumVARIANT指针。取得IEnumVARIANT指针是通过ICollection的_NewEnum属性。具体操作可以参考上一节关于Invoke的说明。
在取得了IEnumVARIANT之后,就可以通过IEnumVARIANT顺序读取数组元素了。
请参考以下代码枚举数据:这段代码是将数组中的元素相加求总和。
ULONG Result = 0;
ULONG res;
while (1)
{
hr = pEnum->Next(1, &var, &res);
if (FAILED(hr))
{
goto CleanUp;
}
if (hr != S_OK || res != 1)
{
break;
}
hr = VariantChangeType(&var, &var, 0, VT_I4);
if (FAILED(hr))
{
goto CleanUp;
}
Result += var.lVal;
}
除了使用枚举器,还可以使用Item和Count属性读取元素。和使用枚举器相比,使用Item和Count可以随时取得任一个元素,但是速度会比使用枚举器慢。
可以参考通过Invoke读取Automation属性的方法取得数组元素。
在ICollection中,大量使用VARIANT数据。这里把VARIANT的使用方法总结一下:
可以直接定义VARIANT类型的变量。
VARIANT val;
在使用VARIANT变量之前,一定要初始化。
VariantInit(&val);
设置变量值前如果VARIANT变量中已经有值,先要清除原有数据。
VariantClear(&val);
val.vt = VT_I4; // 设置类型
val.lVal = 10; // 设置变量值
在使用完VARIANT变量后,要清除变量,否则会发生内存泄漏。
VariantClear(&val);
如果要动态分配VARIANT变量,应该使用标准的COM内存管理函数。
标准COM内存管理函数包括CoTaskMemAlloc、CoTaskMemFree和CoTaskMemRealloc。
VARIANT * pVal;
pVal = (VARIANT *)CoTaskMemAlloc(size_of(VARIANT));
VariantInit(pVal);
pVal->vt = VT_I4;
pVal->lVal = 10;
...
VariantClear(pVal);
CoTaskMemFree(pVal);
CComVariant是ATL对于VARIANT的简单包装。通过CComVariant可以更简单的使用VARIANT,而不必担心没有进行初始化或清除。如果没有特殊情况,应该尽量使用CComVariant而不要使用VARIANT。
以下是使用CComVariant的代码实例。
CComVariant Val;
Val.vt = VT_I4;
Val.lVal = 10;
// Val 不必清除
以下是使用CComVariant数组的例子。
CComVariant * pVal;
pVal = new CComVariant[10];
for (int i = 0; i < 10; ++i)
{
pVal[i].vt = VT_I4;
pVal[I].lVal = i + 1;
}
...
delete[] pVal;
由于时间关系,以及COM规范本身的复杂性。本文不可能面面俱到,只能起到抛砖引玉的作用。我这里有关于本文内容的实例代码,大家可以通过email索取。我的email地址是[email protected]。
大家如果有什么不清楚的地方,也可以通过email探讨。如果大家想了解关于COM或dotNet的其它内容也可以告诉我。我以后会发表更多的文章,希望能对大家有所帮助。