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 フォレストの名前にする必要があります。 この場合、ドメイン名 フォレスト ルートではない名前 指定した場合、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 サーバーであることを指定します。 返されるサーバーが必ずしもドメイン コントローラーであるとは限りません。 他のサービスはサーバーに存在しません。 返されるサーバーには、コンテナー 書き込み可能な 構成も、コンテナー 書き込み可能な スキーマもありません。 返されるサーバーは、必ずしもセキュリティ原則の作成または変更に使用されるとは限りません。 このフラグを DS_GC_SERVER_REQUIRED フラグと共に使用して、グローバル カタログ サーバーもホストする LDAP サーバーを返すこともできます。 返されるグローバル カタログ サーバーは、必ずしもドメイン コントローラーであるとは限りません。 他のサービスはサーバーに存在しません。 このフラグを指定すると、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

DomainControllerName および DomainName メンバーで返される名前 DomainControllerInfo 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 では、指定されたドメインへの特定のアクセスは必要ありません。 既定では、この関数では、返されたドメイン コントローラーが現在使用できることを保証しません。 代わりに、呼び出し元は、返されたドメイン コントローラーの使用を試みる必要があります。 ドメイン コントローラーが使用できない場合、呼び出し元は、DS_FORCE_REDISCOVERY フラグを指定して、DsGetDcName 関数を再度呼び出す必要があります。

応答時間

• DsGetDcName はネットワーク呼び出しを行い、ネットワーク トラフィック、トポロジ、DC 負荷などによっては、数秒から 1 分かかる場合があります。
• UI またはその他のタイミング クリティカル スレッドから dsGetDcName 呼び出すのはお勧めしません。
• DC ロケーターでは、最適化されたロジックを使用して、DC 情報を可能な限り迅速に提供します。 また、サイトのキャッシュされた情報を使用して、最も近い DC に接続します。

ドメイン コントローラーの持続性に関する ノート

以前は、この問題の最も一般的な解決策は、DS_FORCE_REDISCOVERY フラグを使用して、DsGetDcName を定期的に呼び出すスクリプトを各クライアント コンピューターにデプロイすることです。 これはやや面倒なソリューションであるため、Windows Server 2008 と Windows Vista では、ドメイン コントローラーの持続性に関する問題を引き起こした新しいメカニズムが導入されました。

DsGetDcName がキャッシュからドメイン コントローラー名を取得するたびに、このキャッシュされたエントリの有効期限が切れているかどうかを確認し、有効期限が切れている場合は、そのドメイン コントローラー名を破棄し、ドメイン コントローラー名の再検出を試みます。 キャッシュされたエントリの有効期間は、次のレジストリ キーの値によって制御されます

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters\ForceRediscoveryInterval

そして

HKEY_LOCAL_MACHINE\ソフトウェア\ポリシー\Microsoft\Netlogon\Parameters\ForceRediscoveryInterval

これらのレジストリ キーの値は、REG_DWORD型です。 DsGetDcName ドメイン コントローラー名の再検出を試行するまでの長さを秒単位で指定します。 既定値は 43200 秒 (12 時間) です。 ForceRediscoveryInterval レジストリ エントリの値が 0 に設定されている場合、クライアントは常に再情報開示を実行します。 値が 4294967295 に設定されている場合、キャッシュの有効期限が切れることはなく、キャッシュされたドメイン コントローラーは引き続き使用されます。 ForceRediscoveryInterval レジストリ エントリを 3,600 秒 (60 分) 未満の値に設定しないことをお勧めします。

String ProcessName
  DWORD  PID <optional>

App1.exe 
App2.exe
App3.exe
     PID 999