CredUIPromptForCredentialsA 関数 (wincred.h)
CredUIPromptForCredentials 関数は、ユーザーからの資格情報を受け入れる構成可能なダイアログ ボックスを作成して表示します。
Windows Vista または Windows Server 2008 を対象とするアプリケーションでは、次の理由により、この関数の代わりに CredUIPromptForWindowsCredentials
- CredUIPromptForWindowsCredentials は、現在の Windows ユーザー インターフェイスと一貫性があります。
-
CredUIPromptForWindowsCredentials
は拡張性が高く、生体認証やスマート カードなどの追加の認証メカニズムを統合できます。 -
credUIPromptForWindowsCredentials
は、共通基準仕様に準拠しています。
構文
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
パラメーター
[in, optional] pUiInfo
ダイアログ ボックスの外観をカスタマイズするための情報を含む CREDUI_INFO 構造体へのポインター。
[in] pszTargetName
資格情報のターゲットの名前 (通常はサーバー名) を含む null で終わる文字列へのポインター。 分散ファイル システム (DFS) 接続の場合、この文字列は ServerName
[in] pContext
このパラメーターは、将来使用するために予約されています。 これは NULL
[in, optional] dwAuthError
資格情報ダイアログ ボックスが必要な理由を指定します。 呼び出し元は、別の認証呼び出しによって返されるこの Windows エラー パラメーターを渡して、ダイアログ ボックスが特定のエラーに対応できるようにします。 たとえば、パスワードの有効期限が切れた状態コードが渡された場合、ダイアログ ボックスでユーザーにアカウントのパスワードの変更を求めるメッセージが表示される場合があります。
[in, out] pszUserName
資格情報のユーザー名を含む null で終わる文字列へのポインター。 0 以外の長さの文字列を渡すと、ダイアログ ボックスの UserName オプションに文字列が事前に入力されます。
UserName/Password以外の資格情報の場合は、資格情報のマーシャリング形式を渡すことができます。 この文字列は、credMarshalCredential
この関数は、ユーザー指定の名前をこのバッファーにコピーし、最大 ulUserNameMaxChars 文字をコピーします。 この形式は、CredUIParseUsernameを使用して、UserName/Password 形式に変換できます。 マーシャリングされた形式は、セキュリティ サポート プロバイダー (SSP) に直接渡すことができます。
CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、credUIParseUsername に渡す以外に検査、印刷、または永続化を行う必要のない形式になります。 CredUIParseUsername の後続の結果は、WNetAddConnection や SSP 関数などのクライアント側認証関数にのみ渡すことができます。
このパラメーターの一部としてドメインまたはサーバーが指定されていない場合は、pszTargetName パラメーターの値がドメインとして使用され、DomainName\UserName ペアが形成されます。 出力時に、このパラメーターは、DomainName\UserName ペアを含む文字列を受け取ります。
[in] ulUserNameBufferSize
pszUserName にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] pszPassword
資格情報のパスワードを含む null で終わる文字列へのポインター。 pszPasswordに長さ 0 以外の文字列
この関数は、ユーザーが指定したパスワードをこのバッファーにコピーし、最大 ulPasswordMaxChars 文字をコピーします。 CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、WNetAddConnection や SSP 関数などのクライアント側認証関数に渡す以外に、検査、印刷、または永続化を行わないフォームになります。
パスワードの使用が完了したら、SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。 パスワードの保護の詳細については、「パスワードの処理」を参照してください。
[in] ulPasswordBufferSize
pszPassword にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] save
[保存] チェック ボックスの初期状態を指定し、ユーザーがダイアログ ボックスに応答した後に [保存] チェック ボックスの状態を受け取る、BOOL へのポインター。 この値が NULL
CREDUI_FLAGS_PERSIST フラグを指定した場合、[ 保存] チェック ボックスは表示されませんが、選択されていると見なされます。
CREDUI_FLAGS_DO_NOT_PERSIST フラグを指定し、CREDUI_FLAGS_SHOW_SAVE_CHECK_BOXを指定しない場合は、[保存] チェック ボックスは表示されませんが、オフと見なされます。
CredUI を使用してユーザーに資格情報の入力を求める必要があるが、資格情報マネージャーによって提供される資格情報管理サービスは必要ないアプリケーションでは、pfSave を使用して、ユーザーがダイアログ ボックスを閉じた後に 保存 チェック ボックスの状態を受け取ることができます。 これを行うには、呼び出し元が dwFlagsでCREDUI_FLAGS_DO_NOT_PERSISTとCREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
[in] dwFlags
この関数の特殊な動作を指定する DWORD 値。 この値は、次の値の 0 個以上のビットごとのまたは の組み合わせにすることができます。
戻り値
戻り値は DWORD
| 価値 | 形容 |
|---|---|
|
ユーザーが [キャンセル] |
|
無効なフラグ構成の場合、この状態が返されます。 |
|
pszTargetName
|
|
資格情報マネージャーを使用できません。 通常、このエラーは、CredUIPromptForCredentials を呼び出し、CREDUI_FLAGS_DO_NOT_PERSIST フラグを渡すことによって処理されます。 |
|
ユーザーが [OK] |
備考
CredUIPromptForCredentials 関数は、アプリケーション モーダル ダイアログ ボックスを作成して表示します。 ダイアログ ボックスが表示され、ユーザーまたはアプリケーションによってダイアログ ボックスが閉じられるまで、アプリケーション内の他のウィンドウをアクティブにすることはできません。
フラグCREDUI_FLAGS_REQUIRE_SMARTCARD、CREDUI_FLAGS_REQUIRE_CERTIFICATE、およびCREDUI_FLAGS_EXCLUDE_CERTIFICATEは相互に排他的です。
CREDUI_FLAGS_DO_NOT_PERSISTを指定する場合は、pszTargetName を指定するか、または uiInfo->pszMessageText と uiInfo->pszCaption を指定する必要があります。
フラグCREDUI_FLAG_USERNAME_TARGET_CREDENTIALSとCREDUI_FLAGS_GENERIC_CREDENTIALSは相互に排他的です。 どちらも指定されていない場合、資格情報はドメイン資格情報です。
X509 証明書には、szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.20.2.2) の 拡張キー使用法 (EKU) 値が表示されている必要があります。
Windows XP: X509 証明書を表示するためにこの EKU 値は必要ありません。
CREDUI_FLAGS_GENERIC_CREDENTIALSが指定されていない場合、またはCREDUI_FLAGS_COMPLETE_USERNAMEが指定されている場合、型指定された名前 構文がチェックされます。 構文チェックでは、CredUIParseUserNameによって適用
CREDUI_FLAGS_GENERIC_CREDENTIALSが指定され、CREDUI_FLAGS_VALIDATE_USERNAMEも指定されている場合は、型指定された名前が構文チェックされます。 型指定された名前が無効な場合、ユーザーは有効な名前の入力を求められます。
CREDUI_FLAGS_GENERIC_CREDENTIALSが指定されていて、CREDUI_FLAGS_COMPLETE_USERNAMEもCREDUI_FLAGS_VALIDATE_USERNAMEも指定されていない場合、型指定された名前は構文チェックされません。
CREDUI_FLAGS_PERSISTもCREDUI_FLAGS_DO_NOT_PERSISTも設定されていない場合は、[保存] チェック ボックスが表示され、資格情報を保存するかどうかを制御します。
呼び出しモード
- 呼び出し元は、ターゲット リソースへのアクセス、credui の呼び出し (ターゲット リソースとエラー状態の説明を渡す)、CredUIParseUserName
呼び出し、ターゲット リソースに再度アクセスしてから、CredUIConfirmCredentials 呼び出そうとします。 - 呼び出し元は、CREDUI_FLAGS_DO_NOT_PERSISTを渡すことによって、リソースにアクセスせずに資格情報の入力を求めることができます。
- 汎用資格情報の場合、認証パッケージはありません。 そのため、認証を行うには、アプリケーションが資格情報にアクセスする必要があります。 最初の認証の前にCREDUI_FLAGS_ALWAYS_SHOW_UIを渡さないで、資格情報の入力を求めます。 ユーザー インターフェイスは、資格情報マネージャーに資格情報がない場合にのみ表示されます。 アプリケーション内からの後続のすべてのメッセージで、資格情報マネージャーの資格情報がそのリソースに対して明確に無効であるため、CREDUI_FLAGS_ALWAYS_SHOW_UIが渡されます。
ターゲット情報は、アクセスするリソースの場所に関する情報です。 リソースのすべての潜在的なターゲット名の一覧については、CredGetTargetInfo
- コンピューターの NetBIOS サーバー名
- コンピューターの DNS サーバー名
- コンピューターが属しているドメインの NetBIOS ドメイン名
- コンピューターが属しているドメインの DNS ドメイン名
- コンピューターが属しているツリーの DNS ツリー名
- 情報を収集したパッケージの名前
資格情報は、ターゲット名に基づいて資格情報マネージャーに格納されます。 各ターゲット名は、資格情報マネージャーに既に格納されている資格情報と照合することなく、可能な限り一般的に格納されます。 資格情報はターゲット名によって格納されるため、特定のユーザーは、資格情報マネージャーに格納されているターゲットごとに 1 つの資格情報のみを持つことができます。
手記
wincred.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいてこの関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CredUIPromptForCredentials を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリのみ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | wincred.h |
| ライブラリ | Credui.lib |
| DLL | Credui.dll |
関連項目
CredGetTargetInfo の
CredUIConfirmCredentials の
CredUIPromptForWindowsCredentials の
WNetAddConnection の