IMAPITable::QueryRows

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

从表中返回一行或多行，从当前游标位置开始。

HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);

参数

lRowCount

[in]要返回的最大行数。

ulFlags

[in]控制如何返回行的标志的位掩码。可以设置以下标志：

TBL_NOADVANCE

防止游标由于行检索而前进。如果设置了TBL_NOADVANCE标志，游标将指向返回的第一行。如果未设置TBL_NOADVANCE标志，则游标指向返回的最后一行之后的行。

lppRows

[out]指向包含表行的 SRowSet 结构的指针的指针。

返回值

S_OK

已成功返回行。

MAPI_E_BUSY

另一个操作正在进行中，该操作阻止行检索操作启动。应允许正在进行的操作完成，或者应停止该操作。

MAPI_E_INVALID_PARAMETER

IRowCount 参数设置为零。

备注

IMAPITable：：QueryRows 方法从表中获取一行或多行数据。 IRowCount 参数的值会影响检索的起点。如果 IRowCount 为正数，则从当前位置开始向前读取行。如果 IRowCount 为负数， QueryRows 通过向后移动指示的行数来重置起点。重置游标后，将按向前顺序读取行。

lppRows 参数指向的 SRowSet 结构中的 cRows 成员指示返回的行数。如果返回零行：

游标已定位在表的开头， 并且 IRowCount 的值为负。 -或-
游标已定位在表的末尾， 并且 IRowCount 的值为正。

每行的列数及其排序相同。如果行不存在属性或读取属性时出错，则该行中该属性的 SPropValue 结构包含以下值：

ulPropTag 成员中属性类型的PT_ERROR。
Value 成员的MAPI_E_NOT_FOUND。

对于 lppRows 参数指向的行集中 SPropValue 结构的内存，必须为每个行单独分配和释放。使用 MAPIFreeBuffer 释放属性值结构和释放行集。但是，当对 QueryRows 的 调用返回零（指示表的开头或末尾）时，只需要释放 SRowSet 结构本身。有关如何在 SRowSet 结构中分配和释放内存的详细信息，请参阅管理 ADRLIST 和 SRowSet 结构的内存。

返回的行及其返回顺序取决于是否已成功调用 IMAPITable：：Restrict 和 IMAPITable：：SortTable。限制视图中的筛选器行，导致 QueryRows 仅返回与限制中指定的条件匹配的行。 SortTable 建立标准排序顺序或分类排序顺序，从而影响 QueryRows 返回的行序列。返回的行按传递到 SortTable 的 SSortOrderSet 结构中指定的顺序排列。

每行返回的列及其返回顺序取决于是否已成功调用 IMAPITable：：SetColumns。 SetColumns 建立一个列集，指定要包含在表中的列中的属性以及它们应包含的顺序。如果已进行 SetColumns 调用，则每行中的特定列和这些列的顺序与调用中指定的列集匹配。如果未进行 SetColumns 调用，则表将返回其默认列集。

如果这些调用均未进行， QueryRows 将返回表中的所有行。每行包含按默认顺序设置的默认列。

在对 IMAPITable：：SetColumns 的调用中建立的列集包含设置为 PR_NULL 的列时，lppRows 中返回的行集中的 SPropValue 数组将包含空槽。

针对实现者的说明

可以允许调用方请求列集中包含不受支持的列。发生这种情况时，请将PT_ERROR放在属性标记的属性类型部分，并在不受支持的列的属性值中MAPI_E_NOT_FOUND。

将行计数视为请求而不是要求。如果查询方向上没有行，则可以在任意位置返回从零行到请求的数目。

仅返回从分类表视图请求行时用户将看到的行，使调用方能够对数据范围做出有效的假设，并避免额外的工作。

给调用方的说明

通常，最终会得到与 lRowCount 参数中指定的行数一样多的行。但是，当内存或实现限制是一个问题，或者当操作过早到达表的开头或末尾时， QueryRows 将返回的行数将少于请求的行数。

如果 QueryRows 返回MAPI_E_BUSY，请调用 IMAPITable：：WaitForCompletion 方法，并在异步操作完成时重试对 QueryRows 的 调用。

调用 QueryRows 时，请注意，异步通知的计时可能会导致从 QueryRows 返回的行集无法准确表示基础数据。例如，在删除邮件后但在收到相应通知之前，对文件夹的内容表调用 QueryRows 将导致在行集中返回已删除的行。在更新用户的数据视图之前，请始终等待通知到达。

有关从表检索行的详细信息，请参阅从表行检索数据。