ホーム › NetworkManagement.NetManagement › NetRequestOfflineDomainJoin

NetRequestOfflineDomainJoin

関数

オフラインドメイン参加要求を実行しドメイン参加を完了する。

DLLNETAPI32.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// NETAPI32.dll
#include <windows.h>

DWORD NetRequestOfflineDomainJoin(
    BYTE* pProvisionBinData,
    DWORD cbProvisionBinDataSize,
    NET_REQUEST_PROVISION_OPTIONS dwOptions,
    LPCWSTR lpWindowsPath
);

パラメーター

名前

型

方向

説明

pProvisionBinData

BYTE*

オフラインドメイン参加操作の完了フェーズで最終的なローカル状態の変更を処理するために、Windows オペレーティングシステムイメージのレジストリを初期化するのに必要なバッファーへのポインターです。

pProvisionBinData パラメーターで渡されるシリアル化されたメタデータの不透明なバイナリ BLOB は、NetProvisionComputerAccount 関数から返されます。

cbProvisionBinDataSize

DWORD

pProvisionBinData パラメーターが指すバッファーのサイズ（バイト単位）です。

このパラメーターを NULL にすることはできません。

dwOptions

NET_REQUEST_PROVISION_OPTIONS

この関数のオプションを定義するビットフラグのセットです。このパラメーターには、Lmjoin.h ヘッダーファイルで定義されている次の値のうち 1 つ以上を指定できます。

値

意味

NETSETUP_PROVISION_ONLINE_CALLER
0x40000000

このフラグは、lpWindowsPath パラメーターが、アクセス可能なボリュームにマウントされたオフラインの Windows オペレーティングシステムイメージではなく、現在実行中の Windows オペレーティングシステムディレクトリを参照する場合に必要です。このフラグを指定した場合、NetRequestOfflineDomainJoin 関数はローカルの Administrators グループのメンバーが呼び出す必要があります。

lpWindowsPath

LPCWSTR

レジストリハイブが配置されている Windows オペレーティングシステムイメージへのパスを指定する、NULL で終端する定数文字列へのポインターです。このイメージはオフラインであり、現在起動されていない必要があります。ただし、dwOptions パラメーターに NETSETUP_PROVISION_ONLINE_CALLER が含まれている場合は、ローカルで実行中のオペレーティングシステムディレクトリを指定できます。

このパスは、リモートサーバー上の UNC パスでもかまいません。

戻り値の型: DWORD

公式ドキュメント

ボリュームにマウントされた Windows オペレーティングシステムイメージを変更するために、マシン上でローカルに実行します。(NetRequestOfflineDomainJoin)

戻り値

関数が成功した場合、戻り値は NERR_Success です。

関数が失敗した場合、戻り値は次のいずれかのエラーコード、またはシステムエラーコードのいずれかになります。

戻り値	説明
ERROR_ACCESS_DENIED	アクセスが拒否されました。このエラーは、呼び出し元が操作を完了するための十分な権限を持っていない場合に返されます。
ERROR_ELEVATION_REQUIRED	要求された操作には昇格が必要です。
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。このエラーは、pProvisionBinData、cbProvisionBinDataSize、または lpWindowsPath の各パラメーターが NULL である場合に返されます。また、pProvisionBinData パラメーターが指すバッファーの BLOB に、ドメイン、マシンアカウント名、またはマシンアカウントパスワードの有効なデータが含まれていない場合にも返されます。さらに、lpWindowsPath パラメーターが指す文字列が Windows オペレーティングシステムイメージへのパスを指定していない場合にも返されます。
ERROR_NOT_SUPPORTED	要求はサポートされていません。このエラーは、指定されたサーバーがこの操作をサポートしていない場合に返されます。たとえば、lpWindowsPath パラメーターがドメインコントローラーとして構成された Windows インストールを参照している場合などです。
NERR_WkstaNotStarted	Workstation サービスが開始されていません。

解説(Remarks)

NetRequestOfflineDomainJoin 関数は、オフラインドメイン参加操作のために Windows 7 でサポートされています。

NetRequestOfflineDomainJoin 関数は、ボリュームにマウントされた Windows オペレーティングシステムイメージを変更するために、マシン上でローカルに使用されます。イメージのレジストリが読み込まれ、オフラインドメイン参加操作の完了フェーズで取得できる場所にプロビジョニング BLOB データが書き込まれます。オフラインドメイン参加のシナリオでは、これらの関数を次のように使用します。

NetProvisionComputerAccount は、Active Directory 内でコンピューターオブジェクトを作成および構成するために必要なネットワーク操作を実行する目的で最初に呼び出されるプロビジョニング関数です。NetProvisionComputerAccount の出力は、次のステップで使用される、シリアル化されたメタデータの不透明なバイナリ BLOB です。
NetRequestOfflineDomainJoin は、イメージ初期化関数であり、次に呼び出されて、NetProvisionComputerAccount プロビジョニング関数の出力を、インストール時に使用される Windows オペレーティングシステムイメージに挿入します。Windows 初期化コードへの変更によってこの保存された状態が検出され、ドメイン参加のローカルのみの部分に影響を与えます。

NetProvisionComputerAccount 関数は、ドメイン内のマシンアカウントを作成または再利用し、必要なすべてのメタデータを収集して、不透明でバージョン管理されたバイナリ BLOB として、または無人セットアップ応答ファイルに埋め込むためのテキストとして返します。この不透明なバイナリ BLOB は、オフラインドメイン参加要求操作で使用でき、初回起動時にネットワーク操作なし（ローカル状態の更新のみ）でドメイン参加を完了するために必要なすべての入力を提供します。なお、この BLOB には、本質的に平文のマシンアカウントパスワード情報が含まれています。設計上、このデータを保護する仕組みは用意されていません。この問題は、ドメインユーザーパスワードを含む多数のシークレットを保持できる無人セットアップ応答ファイルにも今日存在しています。呼び出し元は、BLOB および無人セットアップファイルを保護する必要があります。この問題への解決策はさまざまです。一例として、事前に交換した鍵を使用して、コンシューマーとプロビジョニングエンティティの間のセッションを暗号化し、不透明な BLOB の安全な転送を可能にする方法があります。

NetProvisionComputerAccount 関数が pProvisionBinData パラメーターで返す不透明な BLOB は、異なるバージョンの Windows（参加するクライアント、プロビジョニングマシン、ドメインコントローラー）間での相互運用性と保守性のシナリオを可能にするためにバージョン管理されています。オフライン参加のシナリオでは、現在のところ NetProvisionComputerAccount 関数が返す BLOB の有効期間に制限はありません。

オフラインドメイン参加操作の詳細については、オフラインドメイン参加ステップバイステップガイドを参照してください。

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

各言語での呼び出し定義

// NETAPI32.dll
#include <windows.h>

DWORD NetRequestOfflineDomainJoin(
    BYTE* pProvisionBinData,
    DWORD cbProvisionBinDataSize,
    NET_REQUEST_PROVISION_OPTIONS dwOptions,
    LPCWSTR lpWindowsPath
);

[DllImport("NETAPI32.dll", ExactSpelling = true)]
static extern uint NetRequestOfflineDomainJoin(
    IntPtr pProvisionBinData,   // BYTE*
    uint cbProvisionBinDataSize,   // DWORD
    uint dwOptions,   // NET_REQUEST_PROVISION_OPTIONS
    [MarshalAs(UnmanagedType.LPWStr)] string lpWindowsPath   // LPCWSTR
);

<DllImport("NETAPI32.dll", ExactSpelling:=True)>
Public Shared Function NetRequestOfflineDomainJoin(
    pProvisionBinData As IntPtr,   ' BYTE*
    cbProvisionBinDataSize As UInteger,   ' DWORD
    dwOptions As UInteger,   ' NET_REQUEST_PROVISION_OPTIONS
    <MarshalAs(UnmanagedType.LPWStr)> lpWindowsPath As String   ' LPCWSTR
) As UInteger
End Function

' pProvisionBinData : BYTE*
' cbProvisionBinDataSize : DWORD
' dwOptions : NET_REQUEST_PROVISION_OPTIONS
' lpWindowsPath : LPCWSTR
Declare PtrSafe Function NetRequestOfflineDomainJoin Lib "netapi32" ( _
    ByVal pProvisionBinData As LongPtr, _
    ByVal cbProvisionBinDataSize As Long, _
    ByVal dwOptions As Long, _
    ByVal lpWindowsPath As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

NetRequestOfflineDomainJoin = ctypes.windll.netapi32.NetRequestOfflineDomainJoin
NetRequestOfflineDomainJoin.restype = wintypes.DWORD
NetRequestOfflineDomainJoin.argtypes = [
    ctypes.POINTER(ctypes.c_ubyte),  # pProvisionBinData : BYTE*
    wintypes.DWORD,  # cbProvisionBinDataSize : DWORD
    wintypes.DWORD,  # dwOptions : NET_REQUEST_PROVISION_OPTIONS
    wintypes.LPCWSTR,  # lpWindowsPath : LPCWSTR
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('NETAPI32.dll')
NetRequestOfflineDomainJoin = Fiddle::Function.new(
  lib['NetRequestOfflineDomainJoin'],
  [
    Fiddle::TYPE_VOIDP,  # pProvisionBinData : BYTE*
    -Fiddle::TYPE_INT,  # cbProvisionBinDataSize : DWORD
    -Fiddle::TYPE_INT,  # dwOptions : NET_REQUEST_PROVISION_OPTIONS
    Fiddle::TYPE_VOIDP,  # lpWindowsPath : LPCWSTR
  ],
  -Fiddle::TYPE_INT)

#[link(name = "netapi32")]
extern "system" {
    fn NetRequestOfflineDomainJoin(
        pProvisionBinData: *mut u8,  // BYTE*
        cbProvisionBinDataSize: u32,  // DWORD
        dwOptions: u32,  // NET_REQUEST_PROVISION_OPTIONS
        lpWindowsPath: *const u16  // LPCWSTR
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("NETAPI32.dll")]
public static extern uint NetRequestOfflineDomainJoin(IntPtr pProvisionBinData, uint cbProvisionBinDataSize, uint dwOptions, [MarshalAs(UnmanagedType.LPWStr)] string lpWindowsPath);
"@
$api = Add-Type -MemberDefinition $sig -Name 'NETAPI32_NetRequestOfflineDomainJoin' -Namespace Win32 -PassThru
# $api::NetRequestOfflineDomainJoin(pProvisionBinData, cbProvisionBinDataSize, dwOptions, lpWindowsPath)

#uselib "NETAPI32.dll"
#func global NetRequestOfflineDomainJoin "NetRequestOfflineDomainJoin" sptr, sptr, sptr, sptr
; NetRequestOfflineDomainJoin varptr(pProvisionBinData), cbProvisionBinDataSize, dwOptions, lpWindowsPath   ; 戻り値は stat
; pProvisionBinData : BYTE* -> "sptr"
; cbProvisionBinDataSize : DWORD -> "sptr"
; dwOptions : NET_REQUEST_PROVISION_OPTIONS -> "sptr"
; lpWindowsPath : LPCWSTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "NETAPI32.dll"
#cfunc global NetRequestOfflineDomainJoin "NetRequestOfflineDomainJoin" var, int, int, wstr
; res = NetRequestOfflineDomainJoin(pProvisionBinData, cbProvisionBinDataSize, dwOptions, lpWindowsPath)
; pProvisionBinData : BYTE* -> "var"
; cbProvisionBinDataSize : DWORD -> "int"
; dwOptions : NET_REQUEST_PROVISION_OPTIONS -> "int"
; lpWindowsPath : LPCWSTR -> "wstr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "NETAPI32.dll"
#cfunc global NetRequestOfflineDomainJoin "NetRequestOfflineDomainJoin" sptr, int, int, wstr
; res = NetRequestOfflineDomainJoin(varptr(pProvisionBinData), cbProvisionBinDataSize, dwOptions, lpWindowsPath)
; pProvisionBinData : BYTE* -> "sptr"
; cbProvisionBinDataSize : DWORD -> "int"
; dwOptions : NET_REQUEST_PROVISION_OPTIONS -> "int"
; lpWindowsPath : LPCWSTR -> "wstr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。