DsGetDcNameW 関数 (dsgetdc.h)
DsGetDcName 関数は、指定されたドメイン内のドメイン コントローラーの名前を返します。 この関数は、特定の特性を持つドメイン コントローラーの優先設定を示すために、追加のドメイン コントローラー選択条件を受け入れます。
構文
DSGETDCAPI DWORD DsGetDcNameW(
[in] LPCWSTR ComputerName,
[in] LPCWSTR DomainName,
[in] GUID *DomainGuid,
[in] LPCWSTR SiteName,
[in] ULONG Flags,
[out] PDOMAIN_CONTROLLER_INFOW *DomainControllerInfo
);
パラメーター
[in] ComputerName
この関数を処理するサーバーの名前を指定する null で終わる文字列へのポインター。 通常、このパラメーターは NULL で、ローカル コンピューターが使用されていることを示します。
[in] DomainName
クエリを実行するドメインまたはアプリケーション パーティションの名前を指定する null で終わる文字列へのポインター。 この名前には、DNS スタイル名 (fabrikam.com など) またはフラット スタイル名 (Fabrikam など) を指定できます。 DNS スタイル名を指定した場合、名前は末尾のピリオドの有無にかかわらず指定できます。
Flags パラメーターに DS_GC_SERVER_REQUIRED フラグが含まれている場合、DomainName はフォレストの名前である必要があります。 この場合、DomainName でフォレスト ルートではない名前が指定されている場合、DsGetDcName は失敗します。
Flags パラメーターに DS_GC_SERVER_REQUIRED フラグが含まれており、DomainName が NULL の場合、DsGetDcName は ComputerName で識別されるコンピューターのフォレスト内でグローバル カタログを検索しようとします。これは、ComputerName が NULL の場合はローカル コンピューターです。
DomainName が NULL で、Flags パラメーターにDS_GC_SERVER_REQUIRED フラグが含まれていない場合、ComputerName は ComputerName で識別されるコンピューターのプライマリ ドメインの既定のドメイン名に設定されます。
[in] DomainGuid
クエリ対象のドメインの GUID を指定する GUID 構造体へのポインター。 DomainGuid が NULL ではなく、DomainName または ComputerName で指定されたドメインが見つからない場合、DsGetDcName は DomainGuid で指定された GUID を持つドメイン内のドメイン コントローラーの検索を試みます。
[in] SiteName
返されるドメイン コントローラーが物理的に存在するサイトの名前を指定する null で終わる文字列へのポインター。 このパラメーターが NULL の場合、 DsGetDcName は ComputerName で指定されたコンピューターのサイトに最も近いサイト内のドメイン コントローラーを返そうと します。 このパラメーターは、既定では NULL である必要があります。
[in] Flags
要求の処理に使用される追加のデータを提供するフラグのセットが含まれています。 このパラメーターは、次の値と組み合わせて使用できます。
DS_AVOID_SELF
ドメイン コントローラーから呼び出された場合、返されるドメイン コントローラー名を現在のコンピューターにしないことを指定します。 現在のコンピューターがドメイン コントローラーでない場合、このフラグは無視されます。 このフラグを使用して、ドメイン内の別のドメイン コントローラーの名前を取得できます。
DS_BACKGROUND_ONLY
DS_FORCE_REDISCOVERY フラグが指定されていない場合、この関数はキャッシュされたドメイン コントローラー データを使用します。 キャッシュされたデータが 15 分を超える場合は、ドメイン コントローラーに ping を実行してキャッシュが更新されます。 このフラグを指定すると、キャッシュされたデータの有効期限が切れた場合でも、この更新は回避されます。 DsGetDcName 関数が定期的に呼び出される場合は、このフラグを使用する必要があります。
DS_DIRECTORY_SERVICE_PREFERRED
DsGetDcName は 、ディレクトリ サービス関数をサポートするドメイン コントローラーの検索を試みます。 ディレクトリ サービスをサポートするドメイン コントローラーが使用できない場合、 DsGetDcName はディレクトリ以外のサービス ドメイン コントローラーの名前を返します。 ただし、 DsGetDcName は、ディレクトリ サービス ドメイン コントローラーの検索がタイムアウトした後にのみ、ディレクトリ 以外のサービス ドメイン コントローラーを返します。
DS_DIRECTORY_SERVICE_REQUIRED
返されたドメイン コントローラーがディレクトリ サービスをサポートしている必要があります。
DS_DIRECTORY_SERVICE_6_REQUIRED
返されたドメイン コントローラーが Windows Server 2008 以降を実行している必要があります。
DS_DIRECTORY_SERVICE_8_REQUIRED
返されたドメイン コントローラーがWindows Server 2012以降実行されている必要があります。
DS_FORCE_REDISCOVERY
キャッシュされたドメイン コントローラー データを強制的に無視します。 DS_FORCE_REDISCOVERY フラグが指定されていない場合、DsGetDcName はキャッシュされたドメイン コントローラー データを返す場合があります。 このフラグを指定すると、 DsGetDcName はキャッシュされた情報 (存在する場合) を使用せず、代わりに新しいドメイン コントローラーの検出を実行します。
キャッシュされたドメイン コントローラー情報を使用するとパフォーマンス特性が向上し、すべてのアプリケーションで同じドメイン コントローラーが一貫して使用されるようにするため、このフラグは通常の条件下では使用しないでください。 このフラグは、 アプリケーションが DsGetDcName によって返されたドメイン コントローラー (このフラグなしで呼び出された場合) にアクセスできないと判断した後にのみ使用する必要があります。 その場合、アプリケーションでは、このフラグを使用して DsGetDcName 呼び出しを繰り返して、未使用のキャッシュ情報 (存在する場合) が無視され、到達可能なドメイン コントローラーが検出されるようにする必要があります。
DS_GC_SERVER_REQUIRED
返されるドメイン コントローラーは、このドメインをルートとする複数のドメインのフォレストのグローバル カタログ サーバーである必要があります。 このフラグが設定され、 DomainName パラメーターが NULL でない場合、 DomainName はフォレスト名を指定する必要があります。 このフラグを DS_PDC_REQUIRED フラグまたは DS_KDC_REQUIRED フラグと組み合わせることはできません。
DS_GOOD_TIMESERV_PREFERRED
DsGetDcName は、信頼できるタイム サーバーであるドメイン コントローラーの検索を試みます。 Windows タイム サービスは、1 つ以上のドメイン コントローラーを信頼できるタイム サーバーとして宣言するように構成できます。 詳細については、 Windows タイム サービス のドキュメントを参照してください。 このフラグは、Windows タイム サービスでのみ使用することを目的としています。
DS_IP_REQUIRED
このパラメーターは、ドメイン コントローラーに IP アドレスが必要であることを示します。 その場合、DsGetDcName はドメイン コントローラーのインターネット プロトコル アドレスを DomainControllerInfo の DomainControllerAddress メンバーに配置します。
DS_IS_DNS_NAME
DomainName パラメーターが DNS 名であることを指定します。 このフラグを DS_IS_FLAT_NAME フラグと組み合わせることはできません。
DS_IS_DNS_NAMEまたはDS_IS_FLAT_NAMEを指定します。 どちらのフラグも指定しない場合、Dns スタイルとフラット名の両方を検索する必要があるため、 DsGetDcName がドメイン コントローラーを見つけるのに時間がかかる場合があります。
DS_IS_FLAT_NAME
DomainName パラメーターがフラット名であることを指定します。 このフラグを DS_IS_DNS_NAME フラグと組み合わせることはできません。
DS_KDC_REQUIRED
返されるドメイン コントローラーは、現在 Kerberos キー配布センター サービスを実行中である必要があります。 このフラグは、 DS_PDC_REQUIRED または DS_GC_SERVER_REQUIRED フラグと組み合わせることはできません。
DS_ONLY_LDAP_NEEDED
返されるサーバーが LDAP サーバーであることを指定します。 返されるサーバーは、必ずしもドメイン コントローラーであるとは限りません。 サーバーに他のサービスが存在することは暗黙的に示されていません。 返されるサーバーには、必ずしも書き込み可能な 構成 コンテナーも書き込み可能な スキーマ コンテナーもありません。 返されるサーバーは、必ずしもセキュリティ原則を作成または変更するために使用されるとは限りません。 このフラグは 、グローバル カタログ サーバーもホストする LDAP サーバーを返すために、DS_GC_SERVER_REQUIRED フラグと共に使用できます。 返されるグローバル カタログ サーバーは、必ずしもドメイン コントローラーであるとは限りません。 サーバーに他のサービスが存在することは暗黙的に示されていません。 このフラグを指定すると、 DS_PDC_REQUIRED、 DS_TIMESERV_REQUIRED、 DS_GOOD_TIMESERV_PREFERRED、 DS_DIRECTORY_SERVICES_PREFERED、 DS_DIRECTORY_SERVICES_REQUIRED、 およびDS_KDC_REQUIRED フラグは無視されます。
DS_PDC_REQUIRED
返されるドメイン コントローラーは、ドメインのプライマリ ドメイン コントローラーである必要があります。 このフラグを DS_KDC_REQUIRED フラグまたは DS_GC_SERVER_REQUIRED フラグと組み合わせることはできません。
DS_RETURN_DNS_NAME
DomainControllerInfo の DomainControllerName メンバーと DomainName メンバーで返される名前を DNS 名にすることを指定します。 DNS 名を使用できない場合は、エラーが返されます。 このフラグは 、DS_RETURN_FLAT_NAME フラグでは指定できません。 このフラグは、 DS_IP_REQUIRED フラグを意味します。
DS_RETURN_FLAT_NAME
DomainControllerInfo の DomainControllerName メンバーと DomainName メンバーで返される名前をフラット名にすることを指定します。 フラット名を使用できない場合は、エラーが返されます。 このフラグは 、DS_RETURN_DNS_NAME フラグでは指定できません。
DS_TIMESERV_REQUIRED
返されるドメイン コントローラーは、現在 Windows タイム サービスを実行中である必要があります。
DS_TRY_NEXTCLOSEST_SITE
このフラグを指定すると、 DsGetDcName は呼び出し元と同じサイト内のドメイン コントローラーの検索を試みます。 このようなドメイン コントローラーが見つからない場合は、トポロジ情報を提供し、 DsBindToISTG を呼び出してバインド ハンドルを取得できるドメイン コントローラーを見つけ、UDP 経由 で DsQuerySitesByCost を呼び出して "次に最も近いサイト" を特定し、最後に見つかったサイトの名前をキャッシュします。 そのサイトにドメイン コントローラーが見つからない場合、 DsGetDcName はドメイン コントローラーを検索する既定の方法にフォールバックします。
このフラグを入力パラメーター SiteName の NULL 以外の値と組み合わせて使用すると、 ERROR_INVALID_FLAGS がスローされます。
また、 DS_TRY_NEXT_CLOSEST_SITE で使用される検索の種類はサイト固有であるため、 DS_PDC_REQUIREDと組み合わせて使用する場合、このフラグは無視されます。 最後に、 netBIOS を 使用して名前を解決するため、 DS_RETURN_FLAT_NAME と組み合わせて使用すると、DS_TRY_NEXTCLOSEST_SITEは無視されますが、見つかったドメイン コントローラーのドメインは、クライアントが参加しているドメインと必ずしも一致しません。
DS_WRITABLE_REQUIRED
返されたドメイン コントローラーを書き込み可能にする必要があります。つまり、ディレクトリ サービスの書き込み可能なコピーをホストします。
DS_WEB_SERVICE_REQUIRED
返されたドメイン コントローラーが現在 Active Directory Web サービスを実行している必要があります。
[out] DomainControllerInfo
選択したドメイン コントローラーに関するデータを含むDOMAIN_CONTROLLER_INFO構造体へのポインターを受け取るPDOMAIN_CONTROLLER_INFO値へのポインター。 この構造体は、 DsGetDcName によって割り当てられます。 呼び出し元は、 不要になった場合に NetApiBufferFree 関数を使用して構造体を解放する必要があります。
戻り値
関数がドメイン コントローラー データを返す場合、戻り値は ERROR_SUCCESS。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
注釈
DsGetDcName 関数は、ComputerName で指定されたリモート コンピューター上の Netlogon サービスに送信されます。 ComputerName が NULL の場合、関数はローカル コンピューターで処理されます。
DsGetDcName は、返されるドメイン コントローラー名が実際のドメイン コントローラーまたはグローバル カタログの名前であることを確認しません。 相互認証が必要な場合、呼び出し元は認証を実行する必要があります。
DsGetDcName では、指定されたドメインへの特定のアクセスは必要ありません。 既定では、この関数は、返されたドメイン コントローラーが現在使用できることを保証しません。 代わりに、呼び出し元は、返されたドメイン コントローラーの使用を試みる必要があります。 ドメイン コントローラーが使用できない場合、呼び出し元は dsGetDcName 関数を再度呼び出し、 DS_FORCE_REDISCOVERY フラグを指定する必要があります。
応答時間
DsGetDcName を使用する場合は、次のタイミングの詳細に注意してください。- DsGetDcName はネットワーク呼び出しを行い、ネットワーク トラフィック、トポロジ、DC 負荷などによっては、数秒から 1 分かかる場合があります。
- UI またはその他のタイミング クリティカルスレッドから DsGetDcName を 呼び出すのはお勧めしません。
- DC ロケーターでは、最適化されたロジックを使用して、DC 情報を可能な限り迅速に提供します。 また、サイトのキャッシュされた情報を使用して、最も近い DC に接続します。
ドメイン コントローラーの持続性に関する注意事項
Active Directory Domain Servicesでは、ドメイン コントローラー ロケーター関数は、クライアントが優先ドメイン コントローラーを見つけたら、そのドメイン コントローラーが応答を停止するか、クライアントが再起動されない限り、別のドメイン コントローラーを検索しないように設計されています。 これは"ドメイン コントローラーの持続性" と呼ばれます。 ワークステーションは通常、何か月も問題なく動作したり再起動したりするので、この動作の意図しない結果の 1 つは、特定のドメイン コントローラーがメンテナンスのために停止した場合、それに接続されたすべてのクライアントが別のドメイン コントローラーに接続をシフトすることです。 ただし、ドメイン コントローラーがバックアップされると、クライアントは頻繁に再起動しないため、クライアントは再接続しません。 これにより、負荷分散の問題が発生する可能性があります。以前は、この問題の最も一般的な解決策は、 フラグを使用して DS_FORCE_REDISCOVERYDsGetDcName を定期的に呼び出すスクリプトを各クライアント コンピューターにデプロイすることです。 これはやや面倒なソリューションであるため、Windows Server 2008 と Windows Vista では、ドメイン コントローラーの持続性に関する問題を引き起こした新しいメカニズムが導入されました。
DsGetDcName がキャッシュからドメイン コントローラー名を取得するたびに、キャッシュされたエントリの有効期限が切れているかどうかを確認し、有効期限が切れている場合は、そのドメイン コントローラー名を破棄し、ドメイン コントローラー名の再検出を試みます。 キャッシュされたエントリの有効期間は、次のレジストリ キーの値によって制御されます
Hkey_local_machine\システム\CurrentControlSet\サービス\Netlogon\パラメーター\ForceRediscoveryInterval
および
Hkey_local_machine\ソフトウェア\ポリシー\マイクロソフト\Netlogon\パラメーター\ForceRediscoveryInterval
これらのレジストリ キーの値は 、REG_DWORD型です。 DsGetDcName がドメイン コントローラー名の再検出を試みるまでの長さを秒単位で指定します。 既定値は 43200 秒 (12 時間) です。 ForceRediscoveryInterval レジストリ エントリの値が 0 に設定されている場合、クライアントは常に再情報開示を実行します。 値が 4294967295 に設定されている場合、キャッシュの有効期限は切れず、キャッシュされたドメイン コントローラーは引き続き使用されます。 ForceRediscoveryInterval レジストリ エントリを 3600 秒 (60 分) 未満の値に設定しないことをお勧めします。
DsGetDcName での ETW トレース
ETW Tracing for DsGetDcName を有効にするには、次のレジストリ キーを作成します。Hkey_local_machine\システム\CurrentControlSet\サービス\DCLocator\トレース
キーの構造は次のとおりです。
String ProcessName
DWORD PID <optional>
ProcessName は、トレース情報を取得するプロセスの拡張子を含む完全な名前である必要があります。 PID は、同じ名前の複数のプロセスが存在する場合にのみ必要です。 定義されている場合は、その PID を持つプロセスのみがトレースに対して有効になります。 同じ名前の 3 つ (またはそれ以上) のプロセスのうち 2 つだけをトレースすることはできません。 1 つのインスタンスまたはすべてのインスタンスを有効にすることができます (同じプロセス名を持つ複数のインスタンスが存在し、PID が指定されていない場合、すべてのインスタンスがトレースに対して有効になります)。
たとえば、これにより、App1.exe と App2.exe のすべてのインスタンスがトレースされますが、PID が 999 の App3.exe のインスタンスのみがトレースされます。
App1.exe
App2.exe
App3.exe
PID 999
次のコマンドを実行して、トレース セッションを開始します。
tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>
sessionname は、トレース セッションに指定された名前です。 DCLocator トレース プロバイダーの guid は"cfaa5446-c6c4-4f5c-866f-31c9b55b962d" です。 filename は、イベントが書き込まれるログ ファイルの名前です。 traceFlags は、トレースする領域を示す次のフラグの 1 つ以上です。
| フラグ | 16 進値 | 説明 |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | その他のデバッグ |
| DCLOCATOR_MAILSLOT | 0x00000010 | Mailslot メッセージ |
| DCLOCATOR_SITE | 0x00000020 | サイト |
| DCLOCATOR_CRITICAL | 0x00000100 | 重要なエラー |
| DCLOCATOR_SESSION_SETUP | 0x00000200 | 信頼されたドメインのメンテナンス |
| DCLOCATOR_DNS | 0x00004000 | 名前の登録 |
| DCLOCATOR_DNS_MORE | 0x00020000 | 詳細な名前の登録 |
| DCLOCATOR_MAILBOX_TEXT | 0x02000000 | 詳細なメールボックス メッセージ |
| DCLOCATOR_SITE_MORE | 0x08000000 | 詳細サイト |
次のコマンドを実行して、トレース セッションを停止します。
tracelog.exe -stop <sessionname>
sessionname は、セッションの開始時に使用した名前と同じ名前です。
注意
dsgetdc.h ヘッダーは、DSGetDcName をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista |
| サポートされている最小のサーバー | Windows Server 2008 |
| 対象プラットフォーム | Windows |
| ヘッダー | dsgetdc.h |
| Library | NetApi32.lib |
| [DLL] | NetApi32.dll |