C O leSafeArray

COleSafeArray 类 是 用 于 处 理 任 意 类 型 和 维 数 的 数 组 的 类 。 COleSafeArray 是从OLE VARIANT 结 构 派 生 而 来 的 。 OLE SAFEARRAY 成 员 函 数 在 可 以 通 过COleSafeArray 来 访 问 ， 就 象 是 特 别 为 一 维 的 字 节 数 组 所 设 计 的 一 个 成 员 函 数集 。

#include <afxdisp.h>

请 参 阅 COleVariant ， CRecordset， CDatabase

CO leSafeArray 类 成 员

Construction

COleSafeArray 构 造 一 个 COleSafeArray 对象

Operations

Attach 给 COleSafeArray 对 象 以 存 在 的 VARIANT 数 组 的控 制

Clear 释 放 基 VARIANT 中 的 所 有 数 据

Detach 将 VARIANT 数 组 从 COleSafeArray 对 象 中 分 离 出来 （ 这 将 使 数 据 不 会 被 释 放 ）

W in32 API W rappers

AccessData 获 取 一 个 指 向 数 组 数 据 的 指 针

AllocData 为 数 组 分 配 内 存

AllocDescriptor 为 安 全 数 组 描 述 符 分 配 内 存

Copy 创 建 一 个 已 存 在 的 数 组 的 拷 贝

Create 创 建 一 个 安 全 数 组

Destroy 销 毁 一 个 已 经 存 在 的 数 组

DestroyData 销 毁 一 个 安 全 数 组 中 的 数 据DestroyDescriptor 销 毁 一 个 安 全 数 组 的 描 述 符GetDim 返 回 数 组 的 维 数

GetElement 获 取 安 全 数 组 中 的 一 个 单 一 元 素

GetElemSize 返 回 安 全 数 组 中 一 个 元 素 的 按 字 节 表 示 的 大 小

GetLBound 返 回 一 个 安 全 数 组 任 一 维 的 下 界

续 表

GetUBound 返 回 一 个 安 全 数 组 任 一 维 的 上 界

Lock 增 加 一 个 数 组 的 加 锁 计 数 ， 并 将 一 个 指 向 数 组 数据 的 指 针 放 到 数 组 描 述 符 中

PtrOfIndex 返 回 一 个 指 向 被 索 引 的 元 素 的 指 针

PutElement 将 一 个 单 一 的 元 素 放 入 数 组 中

Redim 改 变 一 个 安 全 数 组 的 最 不 重 要 （ 最 右 边 ） 的 边 界

UnaccessData 减 小 一 个 数 组 的 加 锁 计 数 ， 并 使 由 AccessData 获

得 的 指 针 无 效

Unlock 减 小 一 个 数 组 的 加 锁 以 使 它 能 被 释 放 或 改 变 大 小

One-Dimensional Array Operations

CreateOneDim 创 建 一 个 一 维 的 COleSafeArray 对 象

GetOneDimSize 返 回 一 个 一 维 的 COleSafeArray 对 象 中 的 元 素 个

数

ResizeOneDim 改 变 一 个 一 维 的 COleSafeArray 对 象 中 的 元 素 个

数

Operators

Operator = 将 一 些 值 （ 包 括 SAFEARRAY ， VARIANT ， ColeVariant ， 或 ColeSafeArray 对 象 ） 拷 贝 到COleSafeArray 对 象 中

Operator == 比 较 两 个 不 同 的 数 组（ SAFEARRAY ， VARIAN T ， ColeVarian t， 或 COleSafeArray 对 象 ）

Operator << 向 转 储 描 述 表 输 出 一 个 COleSafeArray 对 象 的 内容

Operator LPVARIANT 访 问 COleSafeArray 对 象 的 基 VARIANT 结构

O perator LPCVARIANT 访 问 COleSafeArray 对 象 的 基 VARIANT 结构

成 员 函 数

CO leSafeArray::AccessData

void AccessData( void* ppvData );

ppvData

指 向 数 组 数 据 的 指 针 的 指 针 。

说 明

此 成 员 函 数 用 来 返 回 一 个 指 向 数 组 数 据 的 指 针 。 如 果 出 错 ， 则 函 数 抛 出 一 个

CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::UnaccessData ， SafeArrayAccessData

CO leSafeArray::AllocData

void AllocData();

此 成 员 函 数 用 来 为 一 个 安 全 数 组 分 配 内 存 。 如 果 出 错 ， 则 函 数 抛 出 一 个

CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::AllocDescriptor， SafeArrayAllocData

CO leSafeArray::AllocDescriptor

void AllocDescriptor( DWORD dwDims );

参 数

dwDims

安 全 数 组 中 的 维 数 。

此 函 数 用 来 为 一 个 安 全 数 组 的 描 述 符 分 配 内 存 。 如 果 出 错 ， 则 函 数 抛 出 一 个

CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::AllocData ， SafeArrayAllocDescriptor

CO leSafeArray::Attach

void Attach( VARIANT& varSrc );

参 数

varSrc

是 一 个 VARIANT 对 象 。 参 数 varSrc 必 须 有 VARTYPE VT_ARRAY 。

此 成 员 函 数 将 对 一 个 已 有 的 VARIANT 数 组 中 的 数 据 的 控 制 传 给 COleSafeArray 对 象 。 源 VARIANT 的 类 型 被 设 置 为 VT_EMPTY 。 如 果 当 前 数 组 有 数 据 的 话 ， 函 数 将 清 掉 这 些 数 据 。

请 参 阅 COleSafeArray::Detach

CO leSafeArray::Clear

void Clear();

说 明

此 函 数 用 来 清 除 安 全 数 组 。 函 数 通 过 将 对 象 的 VARTYPE 设 置 为 VT_EMPTY

来 清 除 一 个 安 全 数 组 。 数 组 中 的 当 前 内 容 被 释 放 ， 数 组 也 被 释 放 了 。

请 参 阅 VariantClear

CO leSafeArray::COle S afeArray

COleSafeArray() ;

COleSafeArray( const SAFEARRAY& saSrc ,VARTYPE vtSrc ); COleSafeArray（ LPCSAFEARRAY psaSrc , VARTYPE vtSrc ） ;

COleSafeArray( const COleSafeArray& saSrc ); COleSafeArray( const VARIANT& varSrc ); COleSafeArray( LPCVARIANT pSrc ); COleSafeArray( const COleVariant& varSrc );

参 数

saSrc

要 被 拷 贝 到 新 的 COleSafeArray 对 象 中 去 的 已 经 存 在 的 COleSafeArray 对象 或 SAFEARRAY 。

vtSrc

新的 COleSafeArray 对 象 的 VARTYPE 。

psaSrc

一 个 指 向 要 被 拷 贝 到 新 的 COleSafeArray 对 象 中 去 的 SAFEARRAY 的 指

• 。

varSrc

要 被 拷 贝 到 新 的 COleSafeArray 对 象 中 去 的 已 经 存 在 的 V A R IANT 或 者

COleVariant 。

pSrc

一 个 指 向 要 被 拷 贝 到 新 的 COleSafeArray 对 象 中 去 的 VARIANT 对 象 的 指

• 。

说 明

所 有 这 些 构 造 函 数 都 创 建 一 个 新 的 COleSafeArray 对 象 。 如 果 没 有 参 数 ， 则 创

建 的 是 一 个 空 的 COleSafeArray 对 象 （ VT_EMPTY ） 。 如 果 COleSafeArray 是从 另 一 个 数 组 拷 贝 来 的 ， 并 且 这 个 数 组 的 VARTYPE 并 不 是 完 全 确 定 的 （ 一 个COleSafeArray， COleVariant ， 或 者 VARIANT ） ， 则 源 数 组 中 的 VARTYPE 被保 留 ， 并 且 不 需 要 说 明 。 如 果 COleSafeArray 是 从 另 一 个 数 组 拷 贝 而 来 ， 并 且该 数 组 的 VARTYPE 是 不 知 道 的 ， 则 VARTYPE 必 须 用 vtSrc 参 数 来 指 定 。

如 果 出 错 ， 则 函 数 抛 出 一 个 CMemoryException 或 COleException 。

请 参 阅 VariantCopy

CO leSafeArray::Copy

void Copy( LPSAFEARRAY* ppsa );

参 数

ppsa

指 向 一 个 特 定 区 域 的 指 针 ， 在 这 个 特 定 区 域 中 将 返 回 新 的 数 组 描 述 符 。

说 明

创 建 一 个 已 经 存 在 的 安 全 数 组 的 拷 贝 。 如 果 出 错 ， 则 函 数 抛 出 一 个

CMemoryException 或 COleException 。

请 参 阅 SafeArrayCopy

CO leSafeArray::Create

void Create( VARTYPE vtSrc , DWORD dwDim s , DWORD* rgElements );

void Create( VARTYPE vtSrc , DWORD dwDim s, SAFEARRAYBOUND*

rgsabounds );

参 数

vtSrc

是 数 组 的 基 本 类 型 （ 也 就 是 说 ， 数 组 的 每 一 个 元 素 的 VARTYPE ） 。VARTYPE 被 限 制 在 可 变 类 型 的 一 个 子 集 。 不 能 设 置 为 VT_ARRAY 和VT_BYREF 标 志 。 对 数 组 来 说 VT_ARRAY 和 VT_BYREF 是 无 效 的 基 本类 型 。 所 有 其 它 的 类 型 都 是 合 法 的 。

dwDims

数 组 中 的 维 数 。 在 数 组 创 建 之 后 ， 可 以 用 Redim 来 改 变 这 个 值 。

rgElements

指 向 一 个 数 组 的 指 针 。 该 数 组 中 记 录 着 被 创 建 的 数 组 的 每 一 维 的 元 素 个

数 。

rgsabounds

指 向 一 个 分 配 给 数 组 的 界 线 向 量 （ 每 一 维 一 个 ） 的 指 针 。

说 明

此 函 数 用 来 给 数 组 分 配 和 初 始 化 数 据 。 如 果 必 要 的 话 ， 这 个 函 数 将 清 除 当 前 的数 组 数 据 。 如 果 出 错 ， 则 函 数 抛 出 一 个 CMemoryException 。

请 参 阅 SafeArrayCreate

CO leSafeArray::CreateOneDim

void CreateOneDim( VARTYPE vtSrc , DWORD dwElememts , const void* pvSrcData = NULL,long nLBound = 0 );

参 数

vtSrc

是 数 组 的 基 本 类 型 （ 也 就 是 说 ， 数 组 的 每 一 个 元 素 的 VARTYPE ） 。

dwElements

数 组 的 维 数 。 在 数 组 被 创 建 之 后 可 以 用 ResizeOne D im 来 改 变 这 个 值 。

pvSrcData

指 向 要 拷 贝 到 数 组 中 去 的 数 据 的 指 针 。

nL B ound

数 组 的 下 界 。

说 明

此 函 数 用 来 创 建 一 个 一 维 的 COleSafeArray 对 象 。 函 数 为 数 组 分 配 并 初 始 化 数据 ， 如 果 指 针 pvSrcData 不 是 NULL ， 则 将 指 定 的 数 据 拷 贝 到 数 组 中 。

如 果 出 错 ， 则 函 数 抛 出 一 个 CMemoryException 。

请 参 阅 COleSafeArray::GetOneDimSize ， COleSafeArray::ResizeOneDim ，

COleSafeArray::Create

CO leSafeArray::Destroy

void Destroy();

说 明

此 函 数 用 来 销 毁 一 个 已 经 存 在 的 数 组 描 述 符 和 数 组 中 的 所 有 数 据 。 如 果 数 组 中保 存 有 对 象 ， 则 每 一 个 对 象 都 被 释 放 。 如 果 出 错 ， 则 函 数 抛 出 一 个CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::DestroyData ， COleSafeArray::DestroyDescriptor ，

SafeArrayDestroy

CO leSafeArray::DestroyData

void DestroyData() ;

说 明

此 函 数 销 毁 一 个 安 全 数 组 中 的 所 有 数 据 。 如 果 数 组 中 保 存 有 对 象 ， 则 每 一 个 都被 释 放 。 如 果 出 错 ， 则 函 数 抛 出 一 个 CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::DestroyData ， COleSafeArray::DestroyDescriptor， SafeArrayDestroyData

CO leSafeArray::DestroyDescriptor

void DestroyDescriptor();

说 明

此 函 数 用 来 销 毁 一 个 安 全 数 组 的 描 述 符 。 如 果 出 错 ， 则 函 数 抛 出 一 个

CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::DestroyData ， COleSafeArray::DestroyDescriptor， SafeArrayDestroyDescriptor

CO leSafeArray::Detach

VARIANT D e tach();

返 回 COleSafeArray 对 象 中 的 基 VARIANT 值 。

说 明

此 成 员 函 数 用 来 将 VARIANT 数 据 从 COleSafeArray 对 象 中 分 离 出 来 。 函 数 通过 将 对 象 的 VARTYPE 设 置 为 VT_EMPTY 来 分 离 出 安 全 数 组 中 的 数 据 。 调 用者 通 过 调 用 W indows 函 数 VariantClear 来 负 责 释 放 数 组 。

如 果 出 错 ， 则 函 数 抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::Attach ， VariantClear

CO leSafeArray::GetDim

DWORD GetDim();

安 全 数 组 的 维 数 。

说 明

此 函 数 返 回 COleSafeArray 对 象 中 的 维 数 。

请 参 阅 COleSafeArray::Create ， COleSafeArray::Redim ， SafeArrayGetDim

CO leSafeArray::GetElement

void GetElement( long* rgIndices , void* pvData );

参 数

rgIndices

指 向 一 个 数 组 的 指 针 。 该 数 组 包 含 安 全 数 组 的 每 一 维 的 索 引 。

pvData

指 向 用 来 放 置 数 组 的 元 素 的 特 定 区 域 的 指 针 。

说 明

此 函 数 用 来 获 取 安 全 数 组 中 的 一 个 单 一 的 元 素 。 在 获 取 元 素 之 前 和 获 取 元 素 之后 ， 此 函 数 自 动 调 用 W indows 函数 Safe A rrayLock 和 SafeArrayUnlock 。 如 果 此数 据 元 素 是 一 个 字 符 串 ， 对 象 或 可 变 类 型 ， 则 函 数 会 用 正 确 的 方 法 来 拷 贝 这 个元 素 。 参 数 pvData 应 该 指 向 足 够 大 的 缓 冲 区 以 保 存 这 个 元 素 。

如 果 出 错 ， 函 数 将 抛 出 一 个 CMemoryException 和 COleException 。

请 参 阅 COleSafeArray::PutElemen t， SafeArrayGetElement

CO leSafeArray::GetElemSize

DWORD GetElemSize();

返 回 值

以 字 节 表 示 的 安 全 数 组 中 的 元 素 的 大 小 。

说 明

此 函 数 用 来 获 取 一 个 COleSafeArray 大 小 中 的 一 个 元 素 的 大 小 。

请 参 阅 COleSafeArray::GetDim ， SafeArrayGetElemSize

CO leSafeArray::GetBound

void GetBound( D W O R D dwDim , long* pLBound );

参 数

dwDim

要 获 得 其 下 界 的 数 组 的 维 数 。

b pLBound

指 向 要 返 回 下 界 的 位 置 的 指 针 。

说 明

此 成 员 函 数 返 回 一 个 COleSafeArray 对 象 的 任 何 维 的 下 界 。 如 果 出 错 ， 则 函 数抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::GetUBound ， SafeArrayGetLBound

CO leSafeArray::GetOneDimSize

DWORD GetOneDimSize();

返 回 值

• 维 安 全 数 组 中 的 元 素 个 数 。

此 成 员 函 数 用 来 返 回 一 个 一 维 的 COleSafeArray 对 象 的 元 素 个 数 。

请 参 阅 COleSafeArray::CreateOneDimSize ， COleSafeArray::ResizeOneDim ，

SafeArrayRedim

CO leSafeArray::GetUBound

void GetUBound ( DWORD dwDim , long* pUBound );

参 数

dwDim

要 获 得 其 上 界 的 数 组 的 维 数 。

pUBound

指 向 要 返 回 上 界 的 位 置 的 指 针 。

此 成 员 函 数 返 回 一 个 COleSafeArray 对 象 的 任 何 维 的 上 界 。 如 果 出 错 ， 则 函 数抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::GetLBound ， SafeArrayGetUBound

CO leSafeArray::Lock

void Lock();

说 明

此 成 员 函 数 用 来 增 加 一 个 数 组 的 加 锁 计 数 ， 并 在 数 组 描 述 符 中 放 置 一 个 指 向 数组 数 据 的 指 针 。 如 果 出 错 ， 则 函 数 抛 出 一 个 COleException 。

数 组 描 述 符 中 的 指 针 一 直 有 效 ， 直 到 调 用 了 Unlock 。 对 Lock 的 调 用 可 以 是 嵌

套 的 ； 这 时 就 需 要 对 Unlock 进 行 相 同 次 数 的 调 用 。当 一 个 数 组 被 锁 住 时 是 不 能 被 删 除 的 。

请 参 阅 COleSafeArray ::Unlock ， SafeArrayLock

CO leSafeArray::PtrOfIndex

void PtrOfIndex( long* rgIndices , void** ppvData );

参 数

rgIndices

一 个 索 引 值 数 组 。 这 些 索 引 值 用 来 标 识 数 组 中 的 一 个 元 素 。 元 素 的 索 引 都必 须 被 指 明 。

ppvData

在 返 回 时 ， 指 向 由 rgIndices 中 的 值 标 识 的 元 素 。

此 函 数 返 回 一 个 指 向 由 索 引 值 指 定 的 元 素 的 指 针 。

请 参 阅 SafeArrayPtrOfIndex

CO leSafeArray::PutElement

void PutElement( long* rgIndices ， LPVOID pvData );

参 数

rgIndices

指 向 一 个 数 组 的 指 针 。 该 数 组 包 含 安 全 数 组 的 每 一 个 元 素 的 索 引 。

pvData

指 向 要 赋 给 数 组 的 数 据 的 指 针 。 VT_DISPATCH ， VT_UNKNOWN ， 和

VT_BSTR 可 变 类 型 都 是 指 针 ， 它 们 不 需 要 其 它 级 别 的 迂 回 。

这 个 函 数 用 来 将 一 个 单 一 的 元 素 赋 给 数 组 。 在 分 配 元 素 之 前 和 分 配 元 素 之 后 ， 此 函 数 自 动 调 用 W indows 函 数 SafeArrayLock 和 SafeArrayUnlock 。 如 果 数 据 元素 是 一 个 字 符 串 ， 对 象 或 可 变 类 型 ， 则 函 数 会 正 确 拷 贝 它 们 ， 并 且 如 果 已 经 存在 的 元 素 是 一 个 字 符 串 ， 对 象 ， 或 可 变 类 型 ， 它 们 将 被 清 除 。

注 意 你 可 以 对 一 个 数 组 进 行 多 重 锁 定 ， 这 样 当 数 组 被 其 它 操 作 加 锁 时 ， 你 仍 然可 以 将 元 素 放 入 这 个 数 组 中 。

如 果 出 错 ， 函 数 将 抛 出 一 个 CMemoryException 或 COleException 。

请 参 阅 COleSafeArray::GetElemen t， SafeArrayPutElement

CO leSafeArray::Redim

void Redim( SAFEARRAYBOUND* psaboundNew );

psaboundNew

指 向 一 个 新 的 安 全 数 组 边 界 结 构 的 指 针 ， 这 个 边 界 结 构 包 含 新 数 组 的 边界 。 只 有 数 组 的 最 不 重 要 的 维 是 可 以 改 变 的 。

说 明

此 函 数 用 来 改 变 一 个 安 全 数 组 的 最 不 重 要 的 （ 最 右 边 的 ） 边 界 。 如 果 出 错 ， 函数 将 抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::Create ， COleSafeArray::GetDim ，

COleSafeArray::ResizeOneDim ，

SafeArrayRedim

void ResizeOneDim( DWORD dwElements );

参 数

dwElements

一 维 安 全 数 组 中 的 元 素 个 数 。

说 明

此 函 数 用 来 改 变 一 个 一 维 COleSafeArray 对 象 的 元 素 个 数 。 如 果 错 误 ， 函 数 将抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::Redim ， COleSafeArray::GetOneDimSize ， COleSafeArray::CreateOneDim ， SafeArrayRedim

void UnaccessData();

说 明

此 函 数 用 来 减 小 一 个 数 组 中 的 锁 定 计 数 ， 并 使 由 AccessData 获 取 的 指 针 无 效 。如 果 出 错 ， 函 数 将 抛 出 一 个 COleException 。

请 参 阅 COleSafeArray::AccessData ， SafeArrayUnaccessData

CO leSafeArray::Unlock

void Unlock();

说 明

此 函 数 用 来 减 小 一 个 数 组 的 锁 定 计 数 ， 以 使 数 组 能 够 被 释 放 或 改 变 大 小 。 此 函

COleException 。

请 参 阅 COleSafeArray::Lock ， SafeArrayUnlock

操 作 符

CO leSafeArray::operator =

COleSafeArray& operator = ( const COleSafeArray& saSrc ); COleSafeArray& operator = ( const VARIANT& varSrc ); COleSafeArray& operator = ( LPCVARIANT pSrc ); COleSafeArray& operator = ( const COleVariant& varSrc );

说 明

这 些 重 载 的 赋 值 操 作 符 将 源 值 拷 贝 到 COleSafeArray 对 象 。 一 个 有 关 每 个 操 作

• operator = (saSrc) 将 一 个 已 经 存 在 的 COleSafeArray 对 象 拷 贝

  到 这 个 对 象中 。

• operator = (varSrc) 将 一 个 已 经 存 在 的 VARIANT 或 COleVariant

  数 组 拷 贝到 这 个 对 象 中 。

• operator = (pSrc) 将 一 个 由 pSrc 访 问 的 VARIANT 数 组 拷 贝 到

  这 个 对 象 中 。

请 参 阅 VariantCopy

CO leSafeArray::operator ==

BOOL operator = = ( const SAFEARRAY& saSrc ) const; BOOL operator = = ( LPCSAFEARRAY pSrc ) const; BOOL operator = = ( const COleSafeArray& saSrc ) const; BOOL operator = = ( const VARIANT& varSrc ) const; BOOL operator = = ( LPCVARIANT pSrc ) const;

BOOL operator = = ( const COleVariant& varSrc ) const;

说 明

这 个 操 作 符 比 较 两 个 数 组 （ SAFEARRAY ， VARIANT ， COleVariant ， 或COleSafeArray 数 组 ） ， 如 果 它 们 相 等 则 返 回 非 零 值 ； 否 则 就 返 回 零 。 如 果 两个 数 组 具 有 相 同 的 维 数 ， 每 一 维 的 大 小 相 等 ， 且 元 素 值 相 等 ， 则 它 们 就 是 相 等 。

CO leSafeArray::operator <<

CDumpContext& AFXAPI operato r<<( CDumpContext& dc ， COleSafeArray&

saSrc );

说 明

此 强 制 转 换 操 作 符 用 来 访 问 COleSafeArray 对 象 的 基 VARIANT 结 构 。

CO leSafeArray::operator LPVARIANT

operator LPVARIANT();

说 明

此 强 制 转 换 操 作 符 用 来 访 问 COleSafeArray 对 象 的 基 VARIANT 结 构 。

注 意 ， 改 变 由 这 个 函 数 的 返 回 指 针 访 问 的 VARIANT 结 构 的 值 ， 将 改 变 这 个

COleSafeArray 对 象 的 值 。