LDAPVLVInfo
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 |
|---|---|---|---|---|---|
| ldvlv_version | INT | 4 | +0 | +0 | LDAPVLVInfo 構造体のバージョンを識別します。常に LDAP_VLVINFO_VERSION (1) の値に設定する必要があります。 |
| ldvlv_before_count | DWORD | 4 | +4 | +4 | クライアントがリスト結果としてサーバーに返させたい、ターゲット エントリより前のエントリ数を識別します。このフィールドは、BER エンコードされた LDAP_CONTROL_VLVREQUEST コントロールの beforeCount 要素に対応します。 |
| ldvlv_after_count | DWORD | 4 | +8 | +8 | クライアントがリスト結果として返すようサーバーに指示する、ターゲット エントリより後のエントリ数を示します。このフィールドは、BER エンコードされた LDAP_CONTROL_VLVREQUEST コントロールの afterCount 要素に対応します。 |
| ldvlv_offset | DWORD | 4 | +12 | +12 | オフセット値とコンテンツ数の比率を示します。たとえば、ユーザーがスクロール バーをドラッグして、リストの中央にあるエントリを表示する場合を考えます。クライアントがリスト全体に 100 個のエントリが含まれると推定している場合、リストの中央を表示するにはオフセットを 50 と計算し、クライアントはこのオフセット値を、ldvlv_count メンバーで送信するコンテンツ数 100 とともにサーバーへ送信します。サーバーがこのデータを受信した時点で、サーバー側ではコンテンツ数を実際には 500 と計算している場合があるため、次の式を使用して、クライアントが要求したターゲットを見つけるためのオフセットを計算します。 Si = Sc * (Ci / Cc) ここで Si はサーバーが使用する実際のリスト オフセット Sc はサーバーによるコンテンツ数の推定値 Ci はクライアントが送信したオフセット Cc はクライアントが送信したコンテンツ数です。 クライアントがオフセット値 1 を使用した場合、ターゲットがリストの最初のエントリであることを示します。クライアントが ldvlv_count と等しいオフセット値を使用した場合、その項目はリストの最後のエントリです。ldvlv_count が 0 のときはオフセットも 0 になり、これはリストの最後のエントリを表します。 オフセットは、検索が属性値に基づかない場合にのみ使用されるため、ldvlv_attrvalue は NULL でなければなりません。このフィールドは、BER エンコードされた LDAP_CONTROL_VLVREQUEST コントロール内の offset 要素に対応します。 |
| ldvlv_count | DWORD | 4 | +16 | +16 | リストのコンテンツ数を示します。サーバーがオフセット値を計算できるようにするため、クライアントは検索要求を送信する際にコンテンツ数の推定値をサーバーへ送信します。サーバーは応答の中で、自身が計算したコンテンツ数をクライアントに返します。クライアントがコンテンツ数の推定値を持っていない場合は 0 を送信します。これは、サーバーが自身の推定値を使用すべきであることを示します。このメンバーは ldvlv_offset とともに使用されます。コンテンツ数は検索が属性値に基づかない場合にのみ必要となるため、ldvlv_attrvalue メンバーは NULL でなければなりません。このフィールドは、BER エンコードされた LDAP_CONTROL_VLVREQUEST コントロール内の contentCount 要素、および BER エンコードされた LDAP_CONTROL_VLVRESPONSE コントロール内の contentCount 要素に対応します。 |
| ldvlv_attrvalue | LDAP_BERVAL* | 8/4 | +24 | +20 | 検索のターゲット エントリとして属性値を指定します。サーバーはこのメンバーを、LDAPSortKey 構造体の sk_attrtype メンバーで指定された、同じ属性型を持つ値と比較します。オフセットを使用する場合、このメンバーは NULL でなければなりません。このメンバーは、BER エンコードされた LDAP_CONTROL_VLVREQUEST コントロールの assertionValue 要素に対応します。 |
| ldvlv_context | LDAP_BERVAL* | 8/4 | +32 | +24 | この検索操作を識別するためにサーバーによって割り当てられるコンテキスト ID を提供します。これは、サーバーが現在の VLV 操作を内部的に追跡するために使用する不透明な「クッキー」です。VLV コントロールを使用した検索操作の最初の呼び出しでは、このパラメーターを NULL に設定する必要があります。サーバーは LDAP_CONTROL_VLVRESPONSE メッセージで値を返すことがあります。この「クッキー」値は、特定の VLV リストに対して実行される検索関数の次回の呼び出し時に、サーバーへ返す必要があります。 |
| ldvlv_extradata | void* | 8/4 | +40 | +28 | このフィールドはアプリケーション固有の用途のために予約されており、ldap_create_vlv_control 関数では使用されません。作成されるコントロールには影響しません。 |
公式ドキュメント
LDAPVLVInfo 構造体は、仮想リスト ビュー (VLV) 要求コントロール (LDAP_CONTROL_VLVREQUEST) の検索パラメーターを設定するために使用されます。
LDAPVLVInfo 構造体は、一連の VLV クライアント/サーバー間のやり取りに関連付けられた状態データを管理するために、アプリケーションで使用することもできます。
解説(Remarks)
VLV 検索のターゲットを計算する方法には、属性値を使用する方法とオフセットを使用する方法の 2 つがあります。選択する検索の種類に応じて、この構造体の異なる要素が使用されます。どちらの方法でも、ldvlv_before_count メンバーと ldvlv_after_count メンバーに値を設定する必要があります。ldvlv_count にはリストのコンテンツ数を指定します。この値が不明な場合は 0 を指定し、サーバーに計算させます。
-
属性値による検索
値に基づく検索を実行する場合、たとえば Jeff Smith を検索したいときに、その値の属性型が分かっているなら、LDAPSortKey 構造体の sk_attrtype メンバーに属性型を設定し、ldvlv_attrvalue に属性値を設定します。この種類の検索では ldvlv_offset メンバーは無視されるため、設定する必要はありません。
たとえば、文字 J を使用して検索を実行するとします。20 件の結果を取得するには、ldvlv_before_count を 9、ldvlv_after_count を 10、ldvlv_attrvalue を J に設定します。サーバーは、リスト内で J を下回らない最初のエントリ (Jeff Smith など) を見つけ、その前の 9 エントリ、ターゲット エントリ、および後続の 10 エントリを返します。Jeff Smith がリストの 4053 番目のエントリであると仮定すると、サーバーは LDAP_CONTROL_VLVRESPONSE コントロールで ldvlv_count として 30000、ldvlv_offset として 4053 を返します。リスト内に要求を満たすだけのエントリがない場合、サーバーはターゲット エントリの前および/または後に、要求より少ないエントリを返すことがあります。たとえば、最初の「J」のエントリより前に合計 2 つのエントリしかない場合、サーバーは前の 9 エントリを返すことができません。
-
オフセットによる検索
検索にオフセットを使用するには、ldvlv_offset にオフセットを設定し、ldvlv_attrvalue を NULL に設定します。また、LDAPSortKey の sk_attrtype メンバーにも属性型を設定しますが、この場合のターゲットは、特定の属性値ではなく、その属性型のエントリ リスト内のオフセットになります。
たとえば、検索結果リストの 68 パーセントの位置を検索のターゲットにするとします。ldvlv_count が 30000 の場合、30000 の 68 パーセントは 20400 です。20 件の結果を取得するには、ldvlv_before_count を 9、ldvlv_after_count を 10、ldvlv_count を 30000、ldvlv_offset を 20400 に設定して、要求をサーバーへ送信します。サーバーはリスト内の該当する前後 20 エントリに加えて、ldvlv_count の 30000 と ldvlv_offset の 20400 を返します。クライアントがエントリ数を推定した時点とサーバーが検索を処理する時点との間で、リスト内のエントリ数が変化する可能性があり、それがオフセットに影響することに注意してください。この場合、返されるターゲット エントリは、クライアントが期待していたターゲット エントリと正確には一致しないことがあります。アプリケーションは、この不確実性に対処できるように準備しておく必要があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
各言語での定義
#include <windows.h>
// LDAPVLVInfo (x64 48 / x86 32 バイト)
typedef struct LDAPVLVInfo {
INT ldvlv_version;
DWORD ldvlv_before_count;
DWORD ldvlv_after_count;
DWORD ldvlv_offset;
DWORD ldvlv_count;
LDAP_BERVAL* ldvlv_attrvalue;
LDAP_BERVAL* ldvlv_context;
void* ldvlv_extradata;
} LDAPVLVInfo;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct LDAPVLVInfo
{
public int ldvlv_version;
public uint ldvlv_before_count;
public uint ldvlv_after_count;
public uint ldvlv_offset;
public uint ldvlv_count;
public IntPtr ldvlv_attrvalue;
public IntPtr ldvlv_context;
public IntPtr ldvlv_extradata;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure LDAPVLVInfo
Public ldvlv_version As Integer
Public ldvlv_before_count As UInteger
Public ldvlv_after_count As UInteger
Public ldvlv_offset As UInteger
Public ldvlv_count As UInteger
Public ldvlv_attrvalue As IntPtr
Public ldvlv_context As IntPtr
Public ldvlv_extradata As IntPtr
End Structureimport ctypes
from ctypes import wintypes
class LDAPVLVInfo(ctypes.Structure):
_fields_ = [
("ldvlv_version", ctypes.c_int),
("ldvlv_before_count", wintypes.DWORD),
("ldvlv_after_count", wintypes.DWORD),
("ldvlv_offset", wintypes.DWORD),
("ldvlv_count", wintypes.DWORD),
("ldvlv_attrvalue", ctypes.c_void_p),
("ldvlv_context", ctypes.c_void_p),
("ldvlv_extradata", ctypes.c_void_p),
]#[repr(C)]
pub struct LDAPVLVInfo {
pub ldvlv_version: i32,
pub ldvlv_before_count: u32,
pub ldvlv_after_count: u32,
pub ldvlv_offset: u32,
pub ldvlv_count: u32,
pub ldvlv_attrvalue: *mut core::ffi::c_void,
pub ldvlv_context: *mut core::ffi::c_void,
pub ldvlv_extradata: *mut core::ffi::c_void,
}import "golang.org/x/sys/windows"
type LDAPVLVInfo struct {
ldvlv_version int32
ldvlv_before_count uint32
ldvlv_after_count uint32
ldvlv_offset uint32
ldvlv_count uint32
ldvlv_attrvalue uintptr
ldvlv_context uintptr
ldvlv_extradata uintptr
}type
LDAPVLVInfo = record
ldvlv_version: Integer;
ldvlv_before_count: DWORD;
ldvlv_after_count: DWORD;
ldvlv_offset: DWORD;
ldvlv_count: DWORD;
ldvlv_attrvalue: Pointer;
ldvlv_context: Pointer;
ldvlv_extradata: Pointer;
end;const LDAPVLVInfo = extern struct {
ldvlv_version: i32,
ldvlv_before_count: u32,
ldvlv_after_count: u32,
ldvlv_offset: u32,
ldvlv_count: u32,
ldvlv_attrvalue: ?*anyopaque,
ldvlv_context: ?*anyopaque,
ldvlv_extradata: ?*anyopaque,
};type
LDAPVLVInfo {.bycopy.} = object
ldvlv_version: int32
ldvlv_before_count: uint32
ldvlv_after_count: uint32
ldvlv_offset: uint32
ldvlv_count: uint32
ldvlv_attrvalue: pointer
ldvlv_context: pointer
ldvlv_extradata: pointerstruct LDAPVLVInfo
{
int ldvlv_version;
uint ldvlv_before_count;
uint ldvlv_after_count;
uint ldvlv_offset;
uint ldvlv_count;
void* ldvlv_attrvalue;
void* ldvlv_context;
void* ldvlv_extradata;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; LDAPVLVInfo サイズ: 32 バイト(x86)
dim st, 8 ; 4byte整数×8(構造体サイズ 32 / 4 切り上げ)
; ldvlv_version : INT (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; ldvlv_before_count : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; ldvlv_after_count : DWORD (+8, 4byte) st.2 = 値 / 値 = st.2 (lpoke/lpeek も可)
; ldvlv_offset : DWORD (+12, 4byte) st.3 = 値 / 値 = st.3 (lpoke/lpeek も可)
; ldvlv_count : DWORD (+16, 4byte) st.4 = 値 / 値 = st.4 (lpoke/lpeek も可)
; ldvlv_attrvalue : LDAP_BERVAL* (+20, 4byte) varptr(st)+20 を基点に操作(4byte:入れ子/配列)
; ldvlv_context : LDAP_BERVAL* (+24, 4byte) varptr(st)+24 を基点に操作(4byte:入れ子/配列)
; ldvlv_extradata : void* (+28, 4byte) st.7 = 値 / 値 = st.7 (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; LDAPVLVInfo サイズ: 48 バイト(x64)
dim st, 12 ; 4byte整数×12(構造体サイズ 48 / 4 切り上げ)
; ldvlv_version : INT (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; ldvlv_before_count : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; ldvlv_after_count : DWORD (+8, 4byte) st.2 = 値 / 値 = st.2 (lpoke/lpeek も可)
; ldvlv_offset : DWORD (+12, 4byte) st.3 = 値 / 値 = st.3 (lpoke/lpeek も可)
; ldvlv_count : DWORD (+16, 4byte) st.4 = 値 / 値 = st.4 (lpoke/lpeek も可)
; ldvlv_attrvalue : LDAP_BERVAL* (+24, 8byte) varptr(st)+24 を基点に操作(8byte:入れ子/配列)
; ldvlv_context : LDAP_BERVAL* (+32, 8byte) varptr(st)+32 を基点に操作(8byte:入れ子/配列)
; ldvlv_extradata : void* (+40, 8byte) qpoke st,40,値 / qpeek(st,40) ※IronHSPのみ。3.7/3.8は lpoke st,40,下位 : lpoke st,44,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global LDAPVLVInfo
#field int ldvlv_version
#field int ldvlv_before_count
#field int ldvlv_after_count
#field int ldvlv_offset
#field int ldvlv_count
#field intptr ldvlv_attrvalue
#field intptr ldvlv_context
#field intptr ldvlv_extradata
#endstruct
stdim st, LDAPVLVInfo ; NSTRUCT 変数を確保
st->ldvlv_version = 100
mes "ldvlv_version=" + st->ldvlv_version