CredUICmdLinePromptForCredentialsA 関数 (wincred.h)
CredUICmdLinePromptForCredentials 関数は、コマンド ライン (コンソール) アプリケーションで作業しているユーザーの資格情報を要求し、受け入れます。 ユーザーが入力した名前とパスワードは、検証のために呼び出し元のアプリケーションに渡されます。
構文
CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR UserName,
[in] ULONG ulUserBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] PBOOL pfSave,
[in] DWORD dwFlags
);
パラメーター
[in] pszTargetName
資格情報のターゲットの名前 (通常はサーバー名) を含む null で終わる文字列へのポインター。 DFS 接続の場合、この文字列は ServerName ShareName\ という形式です。 pszTargetName パラメーターは、ターゲット情報を識別するために使用され、資格情報の格納と取得に使用されます。
[in] pContext
現在予約されており、 NULL である必要があります。
[in, optional] dwAuthError
資格情報の入力を求めるメッセージが必要な理由を指定します。 呼び出し元は、別の認証呼び出しによって返されるこの Windows エラー パラメーターを渡して、ダイアログ ボックスが特定のエラーに対応できるようにします。 たとえば、パスワードの有効期限が切れた状態コードが渡された場合、ダイアログ ボックスはユーザーにアカウントのパスワードの変更を求めるメッセージを表示します。
[in, out] UserName
資格情報ユーザー名を含む null で終わる文字列へのポインター。 pszUserName に 0 以外の長さの文字列が指定されている場合、ユーザーはパスワードの入力のみを求められます。 ユーザー名/パスワード以外の資格情報の場合は、資格情報のマーシャリング形式を渡すことができます。 この文字列は、 CredMarshalCredential を呼び出すことによって作成されます。
この関数は、ユーザー指定の名前をこのバッファーに書き込み、最大 ulUserNameMaxChars 文字をコピーします。 この形式の文字列は、 CredUIParseUsername 関数を呼び出すことによって、ユーザー名/パスワード形式に変換できます。 マーシャリングされた形式の文字列は、 セキュリティ サポート プロバイダー (SSP) に直接渡すことができます。
CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、 CredUIParseUsername に渡す以外の検査、印刷、または永続化を行わないフォームです。 CredUIParseUsername の後続の結果は、WNetAddConnection や SSP API などのクライアント側認証 API にのみ渡すことができます。
[in] ulUserBufferSize
pszUserName にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] pszPassword
資格情報のパスワードを含む null で終わる文字列へのポインター。 pszPassword に 0 以外の長さの文字列が指定されている場合、password パラメーターは文字列で事前に入力されます。
この関数は、ユーザー指定のパスワードをこのバッファーに書き込み、最大 ulPasswordMaxChars 文字を コピーします。 CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定されていない場合、このパラメーターで返される値は、 WNetAddConnection や SSP 関数などのクライアント側認証関数に渡す以外に検査、印刷、または永続化しないフォームです。
パスワードの使用が完了したら、 SecureZeroMemory 関数を呼び出して、メモリからパスワードをクリアします。 パスワードの保護の詳細については、「パスワードの 処理」を参照してください。
[in] ulPasswordBufferSize
pszPassword にコピーできる最大文字数 (終端の null 文字を含む)。
[in, out] pfSave
SAVE メッセージの初期状態を指定し、ユーザーがコマンド プロンプトに応答した後に保存メッセージの状態を受け取る BOOL へのポインター。 pfSave が NULL ではなく、CredUIPromptForCredentials がNO_ERRORを返す場合、pfSave は Save メッセージの状態を返します。 CREDUI_FLAGS_PERSIST フラグを指定すると、 Save メッセージは表示されませんが、"y" と見なされます。 CREDUI_FLAGS_DO_NOT_PERSIST フラグが指定され、CREDUI_FLAGS_SHOW_SAVE_CHECK_BOXが指定されていない場合、 Save メッセージは表示されませんが、"n" と見なされます。
[in] dwFlags
この関数の特別な動作を指定する DWORD 値。 この値は、次の値の 0 個以上のビットごとの OR の組み合わせにすることができます。
| 値 | 意味 |
|---|---|
|
資格情報マネージャーで既存の資格情報から資格情報を返すことができる場合は、ユーザー インターフェイスを表示します。 このフラグは、CREDUI_FLAGS_GENERIC_CREDENTIALSも指定され、CREDUI_FLAGS_GENERIC_CREDENTIALSと組み合わせてのみ使用される場合にのみ許可されます。 |
|
保存メッセージを表示したり、資格情報を保存したりしないでください。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOXを渡して保存メッセージのみを表示し、結果を pfSave に返すこともできます。 |
|
ユーザー名/パスワードの入力を求めるメッセージが表示されます。 pszUserName パラメーターを指定した場合、ユーザー名は省略されます。 資格情報が永続化されている場合は、渡されたユーザー名を資格情報と共に格納します。 |
|
呼び出し元が CredUIConfirmCredentials を呼び出して、返された資格情報が実際に有効かどうかを判断することを指定します。 これにより、無効な資格情報が資格情報マネージャーに保存されません。 CREDUI_FLAGS_DO_NOT_PERSISTを指定しない限り、このフラグを指定します。 |
|
ユーザーが入力した資格情報を汎用資格情報と考えてください。 |
|
このフラグは自動的に無視されます。 |
|
保存メッセージは表示しませんが、ユーザーが "y" と答えたかのように資格情報を保存します。 |
|
このフラグは自動的に無視されます。 |
|
将来の使用のために予約されています。このフラグを渡さないでください。 |
|
スマート カードを使用し、PIN の入力を求めるメッセージを表示します。 複数のスマート カードが使用可能な場合は、そのうちの 1 つを選択します。 pszUserName パラメーターが空ではない文字列を渡す場合、文字列は、いずれかのスマート カードの証明書に関連付けられている UPN と一致する必要があります。 UPN は、文字列が証明書の UPN 全体と一致する場合、または文字列が証明書の UPN のアット マーク (@) の左側の部分と一致する場合に一致します。 一致するスマート カードが選択されます。 |
|
このフラグは、認証が失敗した場合に、ダイアログ ボックスを事前入力するために一致する資格情報を見つける場合にのみ意味があります。 このフラグを指定すると、ワイルドカード資格情報は一致しません。 資格情報を書き込む場合は影響しません。 CredUI では、ワイルドカード文字を含む資格情報は作成されません。 見つかったものはすべて、RAS 接続が確立されたときに発生するように、ユーザーによって明示的に作成されたか、プログラムによって作成されました。 |
|
保存メッセージを表示し、ユーザーが "y" と答える場合は pfSave out パラメーターに TRUE を返し、ユーザーが "n" と答える場合は FALSE を返します。 このフラグを使用するには、CREDUI_FLAGS_DO_NOT_PERSISTを指定する必要があります。 |
|
資格情報は、実行資格情報です。 pszTargetName パラメーターは、実行するコマンドまたはプログラムの名前を指定します。 プロンプトを表示する目的でのみ使用されます。 |
戻り値
戻り値は DWORD で、次のいずれかの値を指定できます。
| 値 | 説明 |
|---|---|
|
この状態は、無効なフラグの組み合わせに対して返されます。 |
|
pszTargetName が NULL であるか、空の文字列であるか、CREDUI_MAX_DOMAIN_LENGTHより長いか、pUiInfo が NULL ではなく、指すCredUI_INFO構造体が次のいずれかの要件を満たしていません。
|
|
資格情報マネージャーは使用できません。 通常、このエラーは CredUICmdLinePromptForCredentials を呼び出し、CREDUI_FLAGS_DO_NOT_PERSIST フラグを渡すことによって処理されます。 |
|
ユーザーが [OK] を選択しました。 pszUserName、pszPassword、および pfSave 変数は、前に説明した値を返します。 |
注釈
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 フラグは相互に排他的です。 どちらも指定しない場合、資格情報はドメイン資格情報です。
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_FLAGS_PROMPT_FOR_SAVEを指定した場合、 pfSave パラメーターは NULL にすることはできません。
CREDUI_FLAGS_REQUIRE_SMARTCARDフラグとCREDUI_FLAGS_EXCLUDE_CERTIFICATES フラグは相互に排他的です。 CredUICmdLinePromptForCredentials では、スマート カード証明書またはパスワードベースの資格情報の入力を求めるメッセージがサポートされています。 スマート カード証明書ではない証明書や、1 回の呼び出しで両方を要求する証明書はサポートされていません。
呼び出しモード
- 呼び出し元は、ターゲット リソースへのアクセス、credui の呼び出し (ターゲット リソースとエラー状態の説明を渡す)、 CredUIParseUserName の呼び出し、ターゲット リソースへの再度アクセス、 CredUIConfirmCredentials の呼び出しを試みます。
- 呼び出し元は、CREDUI_FLAGS_DO_NOT_PERSISTを渡すことによって、リソースにアクセスせずに資格情報の入力を求めることができます。
ターゲット情報は、アクセスするリソースの場所に関する情報です。 リソースのすべての潜在的なターゲット名の一覧については、 CredGetTargetInfo を呼び出します。 CredGetTargetInfo は、これらのパッケージの 1 つが名前付きターゲットに対する認証に使用されたときに、ネゴシエート、NTLM、または Kerberos 認証パッケージによってキャッシュされた情報を返します。 CredGetTargetInfo は 、ターゲットの次の名前の一部またはすべてを返します。
- コンピューターの NetBIOS サーバー名
- コンピューターの DNS サーバー名
- コンピューターが属しているドメインの NetBIOS ドメイン名
- コンピューターが属しているドメインの DNS ドメイン名
- コンピューターが属しているツリーの DNS ツリー名
- 情報を収集したパッケージの名前
資格情報は、ターゲット名に基づいて資格情報マネージャーに格納されます。 各ターゲット名は、資格情報マネージャーに既に格納されている資格情報と照合することなく、可能な限り一般的に格納されます。 ターゲット名で資格情報を格納する重要な効果は、特定のユーザーが資格情報マネージャーに格納されているターゲットごとに資格情報を 1 つだけ持つことです。
注意
wincred.h ヘッダーは CredUICmdLinePromptForCredentials をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | wincred.h |
| Library | Credui.lib |
| [DLL] | Credui.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示