ADS_VLV 结构 (iads.h)

项目
08/24/2023

ADS_VLV 结构包含用于 (VLV) 搜索执行虚拟列表视图的元数据。此结构提供两个角色。首先，它指定发送到服务器的搜索首选项。其次，它从服务器返回 VLV 元数据。

语法

typedef struct _ads_vlv {
  DWORD  dwBeforeCount;
  DWORD  dwAfterCount;
  DWORD  dwOffset;
  DWORD  dwContentCount;
  LPWSTR pszTarget;
  DWORD  dwContextIDLength;
  LPBYTE lpContextID;
} ADS_VLV, *PADS_VLV;

成员

dwBeforeCount

指示客户端从服务器请求的目标项前的条目数。

dwAfterCount

指示客户端从服务器请求的目标条目之后的条目数。

dwOffset

输入时，指示目标条目在列表中请求的偏移量。如果客户端指定的偏移量等于客户端的假定内容计数，则目标是列表中的最后一个条目。在输出时，指示服务器对返回的目标条目在列表中的位置的实际偏移量的最佳估计值。

dwContentCount

输入值表示客户端的内容计数的估计值。输出值是服务器对内容计数的估计值。如果客户端发送的内容计数为零，则意味着服务器必须使用其内容计数估算值来代替客户端的。

pszTarget

可选。以 Null 结尾的 Unicode 字符串，指示客户端请求的所需目标条目。如果此参数包含非 NULL 值，则服务器将忽略 dwOffset 中指定的值，并根据列表的排序顺序搜索其主排序键值大于或等于指定字符串的第一个目标条目。

dwContextIDLength

可选。指示上下文标识符长度的参数。在输入时，如果在 lpContextID 中传递上下文标识符，则必须将其设置为标识符的大小（以字节为单位）。否则，必须将其设置为等于零。在输出时，如果 lpContextID 包含非 NULL 值，则表示服务器返回的上下文 ID 的长度（以字节为单位）。

lpContextID

可选。指示服务器生成的上下文标识符。此参数可以发送到客户端。如果客户端收到此参数，则应在与同一列表相关的后续请求中返回该参数不变。这种交互可以提高服务器的性能和有效性。如果未将上下文标识符传递给服务器，则必须将此成员设置为 NULL 值。在输出时，如果此成员包含非 NULL 值，则它指向服务器返回的上下文 ID。

注解

若要设置 VLV by dwContentCount 和 dwOffset，还必须将 pszTarget 设置为 NULL 值。如果 pszTarget 包含非 NULL 值，则将其用作偏移量，否则 lOffset 用作偏移量。建议将结构初始化为零。

示例

下面的代码示例演示如何检索结果集中的前 30 个条目。

ADS_SEARCHPREF_INFO prefInfo[2];
ADS_VLV vlv;

vlv.dwBeforeCount=0;
vlv.dwAfterCount=30;
vlv.dwOffset=1;
vlv.dwContentCount=0;
vlv.pszTarget = NULL; 
vlv.dwContextIDLength = 0;
vlv.lpContextID = NULL;

// VLV set preferences.
prefInfo[0].dwSearchPref = ADS_SEARCHPREF_VLV;
prefInfo[0].vValue.dwType = ADSTYPE_PROV_SPECIFIC;
prefInfo[0].vValue.ProviderSpecific.dwLength = sizeof(ADS_VLV);
prefInfo[0].vValue.ProviderSpecific.lpValue = (LPBYTE) &vlv;

// Sort key set preferences.
prefInfo[1].dwSearchPref = ADS_SEARCHPREF_SORT_ON;
prefInfo[1].vValue.dwType = ADSTYPE_PROV_SPECIFIC;
prefInfo[1].vValue.ProviderSpecific.dwLength = sizeof(ADS_SORTKEY);
prefInfo[1].vValue.ProviderSpecific.lpValue = (LPBYTE) pSortKey;

hr = m_pSearch->SetSearchPreference(prefInfo, 2);

下面的代码示例演示如何检索结果集中以字母“Ha”开头的前 50 个条目。

ADS_VLV vlv;

vlv.dwBeforeCount=0;
vlv.dwAfterCount=50;
vlv.pszTarget= L"Ha";
vlv.lpContextID = NULL; 
vlv.dwContextIDLength = 0;

// For more information about how to set the preference, see the previous code example.

下面的代码示例演示了如何检索 60% 近似目标处的前 100 个条目，假设服务器先前返回 的 dwContentCount 为 4294。

注意 vlvResp 表示服务器先前返回 的ADS_VLV 结构。

ADS_VLV vlv;

vlv.dwBeforeCount=50;
vlv.dwAfterCount=50;
vlv.dwOffset=2577;  
vlv.dwContentCount=4294;
vlv.pszTarget = NULL;
vlv.dwContextIDLength = vlvResp.dwContextIDLength; 
vlv.lpContextID = vlvResp.lpContextID;