ホーム › Networking.Ldap › LDAP_REFERRAL_CALLBACK

LDAP_REFERRAL_CALLBACK

構造体

サイズx64: 32 バイト / x86: 16 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールド	型	サイズ	x64	x86	説明
SizeOfCallbacks	DWORD	4	+0	+0	コールバックに必要なメモリ量です。このフィールドには `sizeof(LDAP_REFERRAL_CALLBACK)` を設定します。
QueryForConnection	QUERYFORCONNECTION	8/4	+8	+4	キャッシュされた接続が利用可能かどうかを判断するコールバック関数へのポインターです。詳細については、「解説」を参照してください。
NotifyRoutine	NOTIFYOFNEWCONNECTION	8/4	+16	+8	操作の完了後に、新しい接続をキャッシュするか破棄するかを決定するコールバック関数へのポインターです。詳細については、「解説」を参照してください。
DereferenceRoutine	DEREFERENCECONNECTION	8/4	+24	+12	使用されていない接続の参照を解除するコールバック関数へのポインターです。詳細については、「解説」を参照してください。

公式ドキュメント

LDAP_REFERRAL_CALLBACK 構造体は、接続の外部キャッシュを実装するために使用されます。この構造体は、リフェラルを追跡する場合にのみ使用されます。

解説(Remarks)

接続をキャッシュするメカニズムを実装するには、LDAP_REFERRAL_CALLBACK 構造体を使用します。この構造体には、クライアントコードで実装する 3 つのコールバック関数が含まれます。

QUERYFORCONNECTION: 接続が利用可能な場合、この関数は使用する接続へのポインターを ConnectionToUse に返す必要があります。利用可能な接続がない場合は、ConnectionToUse を NULL に設定する必要があります。このコールバック関数のシグネチャは次のとおりです。

typedef ULONG (_cdecl QUERYFORCONNECTION)(
    PLDAP       PrimaryConnection,
    PLDAP       ReferralFromConnection,
    PWCHAR      NewDN,
    PCHAR       HostName,
    ULONG       PortNumber,
    PVOID       SecAuthIdentity,    // If NULL, use CurrentUser below
    PVOID       CurrentUserToken,   // pointer to current user LUID.
    PLDAP       *ConnectionToUse
);

NOTIFYOFNEWCONNECTION: リフェラルの追跡中に新しい接続が作成された場合、ランタイムはこの関数を呼び出します。接続をキャッシュする必要がない場合、この関数は FALSE を返す必要があります。FALSE が返された場合、接続は操作の完了時に破棄されます。関数が接続の所有権を取得し、接続がキャッシュされる場合は TRUE を返す必要があります。このようにして作成された新しい接続は、要求が開始されたプライマリ接続から現在のコールバックを継承することに注意してください。この関数のシグネチャは次のとおりです。

typedef BOOLEAN (_cdecl NOTIFYOFNEWCONNECTION) 
    (
    PLDAP       PrimaryConnection,
    PLDAP       ReferralFromConnection,
    PWCHAR      NewDN,
    PCHAR       HostName,
    PLDAP       NewConnection,
    ULONG       PortNumber,
    PVOID       SecAuthIdentity,    // If null, use CurrentUser below.
    PVOID       CurrentUser,        // Pointer to current user LUID.
    ULONG       ErrorCodeFromBind   // If nonzero, bind to server failed.
    );

DEREFERENCECONNECTION: LDAP ランタイムは、不要になった接続の参照を解除するためにこの関数を呼び出します。この接続は、QueryForConnection の呼び出しの成功によって得られたもの、または NotifyOfNewConnection から得られたものである可能性があります。呼び出しが成功した場合、この関数は LDAP_SUCCESS を返す必要があります。ただし、現時点ではランタイムは戻り値を無視します。この関数のシグネチャは次のとおりです。

typedef ULONG (_cdecl DEREFERENCECONNECTION)
    (
    PLDAP       PrimaryConnection,
    PLDAP       ConnectionToDereference
    );

キャッシュされた接続を取得するためにコールバックを使用するようにセッションを構成するには、ldap_set_option (conn, LDAP_OPT_REFERRAL_CALLBACK, &referralRoutines) を呼び出します。ここで referralRoutines は、実装したルーチンを格納した LDAP_REFERRAL_CALLBACK 構造体のアドレスです。各アドレスは NULL でもかまいません。その場合、LDAP ランタイムはその呼び出しを行いません。

前述の 3 つの関数のパラメーターの説明は次のとおりです。

PrimaryConnection
操作が最初に実行された LDAP 接続ハンドルです。たとえば、ldap_search、ldap_result、ldap_add などの呼び出しに渡されたハンドルです。
ReferralFromConnection
現在追跡中のリフェラルを送信した接続です。リフェラルは複数の「ホップ」にわたって追跡できます。たとえば、元のサーバーから 2 番目のサーバーへのリフェラルがあり、次に 2 番目のサーバーが操作を 3 番目のサーバーへリフェラルする、というように続く場合があります。ReferralFromConnection が PrimaryConnection と等しい場合は、最初の「ホップ」(元のサーバーから送信されたリフェラル) を追跡していることになります。
NewDN
リフェラル先のオブジェクトの DN を含む、null で終わるワイド文字列へのポインターです。
HostName
リフェラル先のサーバー、つまり接続を確立する必要があるサーバーの名前を含む、null で終わる文字列へのポインターです。
PortNumber リフェラル先のサーバー上の、接続を確立する必要があるポートです。
SecAuthIdentity
リフェラルの追跡時に使用される資格情報の SEC_WINNT_AUTH_IDENTITY または SEC_WINNT_AUTH_IDENTITY_EX です。ユーザーの既定の資格情報を使用する場合は NULL です。
CurrentUserToken/CurrentUser
接続を必要とするユーザーの AuthenticationID LUID です。SecAuthIdentity が NULL の場合は、このパラメーターを使用してユーザーを識別します。
NewConnection
新しい接続の存在を通知するために使用されます。
ErrorCodeFromBind
新しく作成された接続 (NewConnection) へのバインドを試行したときに ldap_bind_s から返されるエラーコードです。
ConnectionToDereference
参照を解除する接続です。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// LDAP_REFERRAL_CALLBACK  (x64 32 / x86 16 バイト)
typedef struct LDAP_REFERRAL_CALLBACK {
    DWORD SizeOfCallbacks;
    QUERYFORCONNECTION QueryForConnection;
    NOTIFYOFNEWCONNECTION NotifyRoutine;
    DEREFERENCECONNECTION DereferenceRoutine;
} LDAP_REFERRAL_CALLBACK;

using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct LDAP_REFERRAL_CALLBACK
{
    public uint SizeOfCallbacks;
    public IntPtr QueryForConnection;
    public IntPtr NotifyRoutine;
    public IntPtr DereferenceRoutine;
}

Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure LDAP_REFERRAL_CALLBACK
    Public SizeOfCallbacks As UInteger
    Public QueryForConnection As IntPtr
    Public NotifyRoutine As IntPtr
    Public DereferenceRoutine As IntPtr
End Structure

import ctypes
from ctypes import wintypes

class LDAP_REFERRAL_CALLBACK(ctypes.Structure):
    _fields_ = [
        ("SizeOfCallbacks", wintypes.DWORD),
        ("QueryForConnection", ctypes.c_void_p),
        ("NotifyRoutine", ctypes.c_void_p),
        ("DereferenceRoutine", ctypes.c_void_p),
    ]

#[repr(C)]
pub struct LDAP_REFERRAL_CALLBACK {
    pub SizeOfCallbacks: u32,
    pub QueryForConnection: *mut core::ffi::c_void,
    pub NotifyRoutine: *mut core::ffi::c_void,
    pub DereferenceRoutine: *mut core::ffi::c_void,
}

import "golang.org/x/sys/windows"

type LDAP_REFERRAL_CALLBACK struct {
	SizeOfCallbacks uint32
	QueryForConnection uintptr
	NotifyRoutine uintptr
	DereferenceRoutine uintptr
}

type
  LDAP_REFERRAL_CALLBACK = record
    SizeOfCallbacks: DWORD;
    QueryForConnection: Pointer;
    NotifyRoutine: Pointer;
    DereferenceRoutine: Pointer;
  end;

const LDAP_REFERRAL_CALLBACK = extern struct {
    SizeOfCallbacks: u32,
    QueryForConnection: ?*anyopaque,
    NotifyRoutine: ?*anyopaque,
    DereferenceRoutine: ?*anyopaque,
};

type
  LDAP_REFERRAL_CALLBACK {.bycopy.} = object
    SizeOfCallbacks: uint32
    QueryForConnection: pointer
    NotifyRoutine: pointer
    DereferenceRoutine: pointer

struct LDAP_REFERRAL_CALLBACK
{
    uint SizeOfCallbacks;
    void* QueryForConnection;
    void* NotifyRoutine;
    void* DereferenceRoutine;
}

HSP用定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; LDAP_REFERRAL_CALLBACK サイズ: 16 バイト(x86)
dim st, 4    ; 4byte整数×4(構造体サイズ 16 / 4 切り上げ)
; SizeOfCallbacks : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; QueryForConnection : QUERYFORCONNECTION (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; NotifyRoutine : NOTIFYOFNEWCONNECTION (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; DereferenceRoutine : DEREFERENCECONNECTION (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; LDAP_REFERRAL_CALLBACK サイズ: 32 バイト(x64)
dim st, 8    ; 4byte整数×8(構造体サイズ 32 / 4 切り上げ)
; SizeOfCallbacks : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; QueryForConnection : QUERYFORCONNECTION (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; NotifyRoutine : NOTIFYOFNEWCONNECTION (+16, 8byte)  qpoke st,16,値 / qpeek(st,16)  ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; DereferenceRoutine : DEREFERENCECONNECTION (+24, 8byte)  qpoke st,24,値 / qpeek(st,24)  ※IronHSPのみ。3.7/3.8は lpoke st,24,下位 : lpoke st,28,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。

; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global LDAP_REFERRAL_CALLBACK
    #field int SizeOfCallbacks
    #field intptr QueryForConnection
    #field intptr NotifyRoutine
    #field intptr DereferenceRoutine
#endstruct

stdim st, LDAP_REFERRAL_CALLBACK        ; NSTRUCT 変数を確保
st->SizeOfCallbacks = 100
mes "SizeOfCallbacks=" + st->SizeOfCallbacks