ホーム › Networking.ActiveDirectory › DsBindByInstanceA

DsBindByInstanceA

関数

インスタンスGUIDを指定してディレクトリサービスへ接続する(ANSI版)。

DLLNTDSAPI.dll文字セットANSI (-A)呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// NTDSAPI.dll  (ANSI / -A)
#include <windows.h>

DWORD DsBindByInstanceA(
    LPCSTR ServerName,   // optional
    LPCSTR Annotation,   // optional
    GUID* InstanceGuid,   // optional
    LPCSTR DnsDomainName,   // optional
    void* AuthIdentity,   // optional
    LPCSTR ServicePrincipalName,   // optional
    DWORD BindFlags,   // optional
    HANDLE* phDS
);

パラメーター

名前	型	方向	説明
ServerName	LPCSTR	inoptional	インスタンスの名前を指定する、null で終わる文字列へのポインター。AD LDS インスタンスにバインドする場合、このパラメーターは必須です。Active Directory インスタンスにバインドするときにこのパラメーターが NULL の場合は、DnsDomainName パラメーターに値を指定する必要があります。このパラメーターと DnsDomainName パラメーターの両方が NULL の場合、この関数は戻り値 ERROR_INVALID_PARAMETER (87) で失敗します。
Annotation	LPCSTR	inoptional	AD LDS インスタンスのポート番号を指定する、null で終わる文字列へのポインター。Active Directory インスタンスにバインドする場合は NULL を指定します。たとえば "389" のように指定します。ドメイン指定で Active Directory インスタンスにバインドするときにこのパラメーターが NULL の場合は、DnsDomainName パラメーターを指定する必要があります。AD LDS インスタンスにバインドするときにこのパラメーターが NULL の場合は、InstanceGuid パラメーターを指定する必要があります。
InstanceGuid	GUID*	inoptional	AD LDS インスタンスの GUID を格納する GUID 値へのポインター。この GUID 値は、インスタンスの nTDSDSA オブジェクトの objectGUID プロパティです。AD LDS インスタンスにバインドするときにこのパラメーターが NULL の場合は、Annotation パラメーターを指定する必要があります。
DnsDomainName	LPCSTR	inoptional	ドメイン指定で Active Directory インスタンスにバインドする場合に、ドメインの DNS 名を指定する、null で終わる文字列へのポインター。サーバー指定で Active Directory インスタンスにバインドする場合、または AD LDS インスタンスにバインドする場合は、このパラメーターに NULL を設定します。
AuthIdentity	void*	inoptional	RPC セッションの開始に使用する資格情報へのハンドル。AuthIdentity に適した構造体を作成するには、DsMakePasswordCredentials 関数を使用します。
ServicePrincipalName	LPCSTR	inoptional	クライアントに割り当てるサービスプリンシパル名 (Service Principal Name) を指定する、null で終わる文字列へのポインター。ServicePrincipalName に NULL を渡すことは、DsBindWithCred 関数を呼び出すことと同等です。
BindFlags	DWORD	inoptional	この関数の動作を定義するフラグのセットを格納します。このパラメーターには、ゼロ、または次の値のうち 1 つ以上の組み合わせを指定できます。 NTDSAPI_BIND_ALLOW_DELEGATION (1) バインドで委任 (delegate) 偽装レベルを使用します。これにより、DsAddSidHistory など、委任を必要とする操作が成功するようになります。また、このフラグを指定すると、DsBindWithSpnEx は DsBindWithSpn と同様に動作します。このフラグを指定しない場合、バインドでは偽装 (impersonate) 偽装レベルが使用されます。偽装レベルの詳細については、Impersonation Levels を参照してください。ほとんどの操作では委任偽装レベルは必要ありません。このフラグは必要な場合にのみ指定してください。委任偽装レベルで不正なサーバーにバインドすると、その不正なサーバーが自分の資格情報を使用して正規のサーバーに接続し、意図しない操作を実行できるようになります。 NTDSAPI_BIND_FORCE_KERBEROS (4) Active Directory Lightweight Directory Services: このフラグを指定すると、DsBindWithSpnEx は Kerberos 認証の使用を必須とします。Kerberos 認証を確立できない場合、DsBindWithSpnEx は他のメカニズムでの認証を試みません。
phDS	HANDLE*	out	バインドハンドルを受け取る HANDLE 値のアドレス。このハンドルを閉じるには、DsUnBind を呼び出します。

戻り値の型: DWORD

公式ドキュメント

任意の AD LDS または Active Directory インスタンスに明示的にバインドします。(ANSI)

戻り値

成功した場合は NO_ERROR を返し、それ以外の場合は RPC エラーまたは Win32 エラーを返します。発生し得るエラーコードには、次の一覧に示すものが含まれます。

解説(Remarks)

インスタンスにバインドする際に必要なパラメーター値を次の一覧に示します。

インスタンス	ServerName	Annotation	InstanceGuid	DnsDomainName
サーバー指定の Active Directory	サーバー名	NULL	NULL	NULL
ドメイン指定の Active Directory	NULL	NULL	NULL	DNS ドメイン名
ポート指定の AD LDS	AD LDS がインストールされているコンピューターの DNS 名。	ポート番号	NULL	NULL
GUID 指定の AD LDS	AD LDS がインストールされているコンピューターの DNS 名。	NULL	インスタンスの GUID	NULL

注意複数の AD LDS インスタンスが存在するコンピューター上で AD LDS インスタンスにバインドする場合、パフォーマンスを向上させるには、ポート番号ではなくインスタンスの GUID でバインドしてください。

メモ

ntdsapi.h ヘッダーは、UNICODE プリプロセッサー定数の定義に応じてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして DsBindByInstance を定義しています。エンコードに依存しないエイリアスの使用と、エンコードに依存するコードを混在させると、不整合が生じてコンパイルエラーまたは実行時エラーの原因となることがあります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

// NTDSAPI.dll  (ANSI / -A)
#include <windows.h>

DWORD DsBindByInstanceA(
    LPCSTR ServerName,   // optional
    LPCSTR Annotation,   // optional
    GUID* InstanceGuid,   // optional
    LPCSTR DnsDomainName,   // optional
    void* AuthIdentity,   // optional
    LPCSTR ServicePrincipalName,   // optional
    DWORD BindFlags,   // optional
    HANDLE* phDS
);

[DllImport("NTDSAPI.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint DsBindByInstanceA(
    [MarshalAs(UnmanagedType.LPStr)] string ServerName,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string Annotation,   // LPCSTR optional
    IntPtr InstanceGuid,   // GUID* optional
    [MarshalAs(UnmanagedType.LPStr)] string DnsDomainName,   // LPCSTR optional
    IntPtr AuthIdentity,   // void* optional
    [MarshalAs(UnmanagedType.LPStr)] string ServicePrincipalName,   // LPCSTR optional
    uint BindFlags,   // DWORD optional
    IntPtr phDS   // HANDLE* out
);

<DllImport("NTDSAPI.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function DsBindByInstanceA(
    <MarshalAs(UnmanagedType.LPStr)> ServerName As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> Annotation As String,   ' LPCSTR optional
    InstanceGuid As IntPtr,   ' GUID* optional
    <MarshalAs(UnmanagedType.LPStr)> DnsDomainName As String,   ' LPCSTR optional
    AuthIdentity As IntPtr,   ' void* optional
    <MarshalAs(UnmanagedType.LPStr)> ServicePrincipalName As String,   ' LPCSTR optional
    BindFlags As UInteger,   ' DWORD optional
    phDS As IntPtr   ' HANDLE* out
) As UInteger
End Function

' ServerName : LPCSTR optional
' Annotation : LPCSTR optional
' InstanceGuid : GUID* optional
' DnsDomainName : LPCSTR optional
' AuthIdentity : void* optional
' ServicePrincipalName : LPCSTR optional
' BindFlags : DWORD optional
' phDS : HANDLE* out
Declare PtrSafe Function DsBindByInstanceA Lib "ntdsapi" ( _
    ByVal ServerName As String, _
    ByVal Annotation As String, _
    ByVal InstanceGuid As LongPtr, _
    ByVal DnsDomainName As String, _
    ByVal AuthIdentity As LongPtr, _
    ByVal ServicePrincipalName As String, _
    ByVal BindFlags As Long, _
    ByVal phDS As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

DsBindByInstanceA = ctypes.windll.ntdsapi.DsBindByInstanceA
DsBindByInstanceA.restype = wintypes.DWORD
DsBindByInstanceA.argtypes = [
    wintypes.LPCSTR,  # ServerName : LPCSTR optional
    wintypes.LPCSTR,  # Annotation : LPCSTR optional
    ctypes.c_void_p,  # InstanceGuid : GUID* optional
    wintypes.LPCSTR,  # DnsDomainName : LPCSTR optional
    ctypes.POINTER(None),  # AuthIdentity : void* optional
    wintypes.LPCSTR,  # ServicePrincipalName : LPCSTR optional
    wintypes.DWORD,  # BindFlags : DWORD optional
    ctypes.c_void_p,  # phDS : HANDLE* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('NTDSAPI.dll')
DsBindByInstanceA = Fiddle::Function.new(
  lib['DsBindByInstanceA'],
  [
    Fiddle::TYPE_VOIDP,  # ServerName : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # Annotation : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # InstanceGuid : GUID* optional
    Fiddle::TYPE_VOIDP,  # DnsDomainName : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # AuthIdentity : void* optional
    Fiddle::TYPE_VOIDP,  # ServicePrincipalName : LPCSTR optional
    -Fiddle::TYPE_INT,  # BindFlags : DWORD optional
    Fiddle::TYPE_VOIDP,  # phDS : HANDLE* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "ntdsapi")]
extern "system" {
    fn DsBindByInstanceA(
        ServerName: *const u8,  // LPCSTR optional
        Annotation: *const u8,  // LPCSTR optional
        InstanceGuid: *mut GUID,  // GUID* optional
        DnsDomainName: *const u8,  // LPCSTR optional
        AuthIdentity: *mut (),  // void* optional
        ServicePrincipalName: *const u8,  // LPCSTR optional
        BindFlags: u32,  // DWORD optional
        phDS: *mut *mut core::ffi::c_void  // HANDLE* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("NTDSAPI.dll", CharSet = CharSet.Ansi)]
public static extern uint DsBindByInstanceA([MarshalAs(UnmanagedType.LPStr)] string ServerName, [MarshalAs(UnmanagedType.LPStr)] string Annotation, IntPtr InstanceGuid, [MarshalAs(UnmanagedType.LPStr)] string DnsDomainName, IntPtr AuthIdentity, [MarshalAs(UnmanagedType.LPStr)] string ServicePrincipalName, uint BindFlags, IntPtr phDS);
"@
$api = Add-Type -MemberDefinition $sig -Name 'NTDSAPI_DsBindByInstanceA' -Namespace Win32 -PassThru
# $api::DsBindByInstanceA(ServerName, Annotation, InstanceGuid, DnsDomainName, AuthIdentity, ServicePrincipalName, BindFlags, phDS)

#uselib "NTDSAPI.dll"
#func global DsBindByInstanceA "DsBindByInstanceA" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; DsBindByInstanceA ServerName, Annotation, varptr(InstanceGuid), DnsDomainName, AuthIdentity, ServicePrincipalName, BindFlags, phDS   ; 戻り値は stat
; ServerName : LPCSTR optional -> "sptr"
; Annotation : LPCSTR optional -> "sptr"
; InstanceGuid : GUID* optional -> "sptr"
; DnsDomainName : LPCSTR optional -> "sptr"
; AuthIdentity : void* optional -> "sptr"
; ServicePrincipalName : LPCSTR optional -> "sptr"
; BindFlags : DWORD optional -> "sptr"
; phDS : HANDLE* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "NTDSAPI.dll"
#cfunc global DsBindByInstanceA "DsBindByInstanceA" str, str, var, str, sptr, str, int, sptr
; res = DsBindByInstanceA(ServerName, Annotation, InstanceGuid, DnsDomainName, AuthIdentity, ServicePrincipalName, BindFlags, phDS)
; ServerName : LPCSTR optional -> "str"
; Annotation : LPCSTR optional -> "str"
; InstanceGuid : GUID* optional -> "var"
; DnsDomainName : LPCSTR optional -> "str"
; AuthIdentity : void* optional -> "sptr"
; ServicePrincipalName : LPCSTR optional -> "str"
; BindFlags : DWORD optional -> "int"
; phDS : HANDLE* out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "NTDSAPI.dll"
#cfunc global DsBindByInstanceA "DsBindByInstanceA" str, str, sptr, str, sptr, str, int, sptr
; res = DsBindByInstanceA(ServerName, Annotation, varptr(InstanceGuid), DnsDomainName, AuthIdentity, ServicePrincipalName, BindFlags, phDS)
; ServerName : LPCSTR optional -> "str"
; Annotation : LPCSTR optional -> "str"
; InstanceGuid : GUID* optional -> "sptr"
; DnsDomainName : LPCSTR optional -> "str"
; AuthIdentity : void* optional -> "sptr"
; ServicePrincipalName : LPCSTR optional -> "str"
; BindFlags : DWORD optional -> "int"
; phDS : HANDLE* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。