ホーム › Security.Credentials › CredUIPromptForWindowsCredentialsA

CredUIPromptForWindowsCredentialsA

関数

Windows資格情報の入力ダイアログを表示する。

DLLcredui.dll文字セットANSI (-A)呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// credui.dll  (ANSI / -A)
#include <windows.h>

DWORD CredUIPromptForWindowsCredentialsA(
    CREDUI_INFOA* pUiInfo,   // optional
    DWORD dwAuthError,
    DWORD* pulAuthPackage,
    const void* pvInAuthBuffer,   // optional
    DWORD ulInAuthBufferSize,
    void** ppvOutAuthBuffer,
    DWORD* pulOutAuthBufferSize,
    BOOL* pfSave,   // optional
    CREDUIWIN_FLAGS dwFlags
);

パラメーター

名前

型

方向

説明

pUiInfo

CREDUI_INFOA*

inoptional

この関数が表示するダイアログボックスの外観をカスタマイズするための情報を格納した CREDUI_INFO 構造体へのポインターです。

CREDUI_INFO 構造体の hwndParent メンバーが NULL でない場合、この関数は親ウィンドウの中央に配置されたモーダルダイアログボックスを表示します。

CREDUI_INFO 構造体の hwndParent メンバーが NULL の場合、この関数は画面の中央に配置されたダイアログボックスを表示します。

この関数は CREDUI_INFO 構造体の hbmBanner メンバーを無視します。

dwAuthError

DWORD

ダイアログボックスに表示される、Winerror.h で定義された Windows エラーコードです。以前に収集した資格情報が無効であった場合、呼び出し元はこのパラメーターを使用して、資格情報を収集した API(例: Winlogon)からのエラーメッセージをこの関数に渡します。対応するエラーメッセージが書式設定され、ダイアログボックスに表示されます。エラーメッセージを表示しない場合は、このパラメーターの値を 0 に設定します。

pulAuthPackage

DWORD*

inout

入力時には、このパラメーターの値は、pvInAuthBuffer バッファー内の資格情報がシリアル化される認証パッケージを指定するために使用されます。pvInAuthBuffer の値が NULL で、かつ dwFlags パラメーターに CREDUIWIN_AUTHPACKAGE_ONLY フラグが設定されている場合、指定された認証パッケージ用の資格情報をシリアル化できる資格情報プロバイダーのみが列挙されます。

入力時にこのパラメーターに使用する適切な値を取得するには、LsaLookupAuthenticationPackage 関数を呼び出し、その関数の AuthenticationPackage パラメーターの値を使用します。

出力時には、このパラメーターは ppvOutAuthBuffer バッファー内の資格情報がシリアル化される認証パッケージを指定します。

pvInAuthBuffer

void*

inoptional

ダイアログボックスの資格情報フィールドに値を設定するために使用される資格情報 BLOB へのポインターです。資格情報フィールドを空のままにする場合は、このパラメーターの値を NULL に設定します。

ulInAuthBufferSize

DWORD

pvInAuthBuffer バッファーのサイズ(バイト単位)です。

ppvOutAuthBuffer

void**

out

出力時に資格情報 BLOB を指すポインターのアドレスです。Kerberos、NTLM、または Negotiate の資格情報の場合は、CredUnPackAuthenticationBuffer 関数を呼び出して、この BLOB を資格情報の文字列表現に変換します。

資格情報 BLOB の使用が終了したら、SecureZeroMemory 関数を呼び出してメモリから消去し、CoTaskMemFree 関数を呼び出して解放します。

pulOutAuthBufferSize

DWORD*

out

ppvOutAuthBuffer バッファーのサイズ(バイト単位)です。

pfSave

BOOL*

inoutoptional

入力時には、この関数が表示するダイアログボックスで保存チェックボックスがオンになっているかどうかを指定する Boolean 値へのポインターです。出力時には、ユーザーがダイアログボックスで送信ボタンをクリックしたときに保存チェックボックスがオンになっていたかどうかをこのパラメーターの値が示します。保存チェックボックスを無視する場合は、このパラメーターを NULL に設定します。

dwFlags パラメーターに CREDUIWIN_CHECKBOX フラグが設定されていない場合、このパラメーターは無視されます。

dwFlags

CREDUIWIN_FLAGS

この関数の動作を指定する値です。この値には、次の値のうち 1 つ以上のビット単位の OR 組み合わせを指定できます。

値	意味
CREDUIWIN_GENERIC 0x1	呼び出し元は、資格情報プロバイダーがユーザー名とパスワードをプレーンテキストで返すことを要求します。この値は SECURE_PROMPT と組み合わせることはできません。
CREDUIWIN_CHECKBOX 0x2	ダイアログボックスに保存チェックボックスが表示されます。
CREDUIWIN_AUTHPACKAGE_ONLY 0x10	pulAuthPackage パラメーターで指定された認証パッケージをサポートする資格情報プロバイダーのみが列挙されます。この値は CREDUIWIN_IN_CRED_ONLY と組み合わせることはできません。
CREDUIWIN_IN_CRED_ONLY 0x20	pulAuthPackage パラメーターで指定された認証パッケージについて、pvInAuthBuffer パラメーターで指定された資格情報のみが列挙されます。このフラグが設定されていて、pvInAuthBuffer パラメーターが NULL の場合、この関数は失敗します。この値は CREDUIWIN_AUTHPACKAGE_ONLY と組み合わせることはできません。
CREDUIWIN_ENUMERATE_ADMINS 0x100	資格情報プロバイダーは管理者のみを列挙します。この値はユーザーアカウント制御(UAC)の目的のみを意図したものです。外部の呼び出し元はこのフラグを設定しないことをお勧めします。
CREDUIWIN_ENUMERATE_CURRENT_USER 0x200	pulAuthPackage パラメーターで指定された認証パッケージについて、受信した資格情報のみが列挙されます。
CREDUIWIN_SECURE_PROMPT 0x1000	資格情報ダイアログボックスはセキュアデスクトップに表示されます。この値は CREDUIWIN_GENERIC と組み合わせることはできません。 Windows Vista: この値は Windows Vista with SP1 以降でサポートされます。
CREDUIWIN_PREPROMPTING 0x2000	資格情報ダイアログボックスは SspiPromptForCredentials 関数によって呼び出され、事前のハンドシェイクの前にクライアントにプロンプトが表示されます。pvInAuthBuffer パラメーターに SSPIPFC_NO_CHECKBOX が渡された場合、資格情報プロバイダーはチェックボックスを表示しません。 Windows Vista: この値は Windows Vista with SP1 以降でサポートされます。
0x40000	資格情報プロバイダーは AAD 機関名をパックしません。これは Azure AD 参加済みデバイスにのみ適用されます。 Windows 10, version 1607: この値は Windows 10, version 1607 以降でサポートされます。
CREDUIWIN_PACK_32_WOW 0x10000000	資格情報プロバイダーは、64 ビットシステム上で実行されている場合でも、ppvOutAuthBuffer パラメーターが指す資格情報 BLOB を 32 ビット境界に整列させます。
0x80000000	Windows Hello の資格情報がスマートカード認証バッファーにパックされます。これは顔、指紋、および PIN の資格情報プロバイダーにのみ適用されます。 Windows 10, version 1809: この値は Windows 10, version 1809 以降でサポートされます。

戻り値の型: DWORD

公式ドキュメント

ローカルコンピューターにインストールされている任意の資格情報プロバイダーを使用して、ユーザーが資格情報を入力できる、構成可能なダイアログボックスを作成して表示します。(ANSI)

戻り値

関数が成功した場合、この関数は ERROR_SUCCESS を返します。ユーザーによって関数がキャンセルされた場合は ERROR_CANCELLED を返します。その他の戻り値は、関数の読み込みに失敗したことを示します。

解説(Remarks)

この関数は資格情報を保存しません。

SSPI を使用してユーザーを認証するアプリケーションは、この関数を呼び出さないでください。代わりに SspiPromptForCredentials を呼び出してください。

メモ

wincred.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして CredUIPromptForWindowsCredentials を定義しています。エンコーディング非依存のエイリアスの使用と、エンコーディング非依存でないコードを混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致が発生する可能性があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

// credui.dll  (ANSI / -A)
#include <windows.h>

DWORD CredUIPromptForWindowsCredentialsA(
    CREDUI_INFOA* pUiInfo,   // optional
    DWORD dwAuthError,
    DWORD* pulAuthPackage,
    const void* pvInAuthBuffer,   // optional
    DWORD ulInAuthBufferSize,
    void** ppvOutAuthBuffer,
    DWORD* pulOutAuthBufferSize,
    BOOL* pfSave,   // optional
    CREDUIWIN_FLAGS dwFlags
);

[DllImport("credui.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint CredUIPromptForWindowsCredentialsA(
    IntPtr pUiInfo,   // CREDUI_INFOA* optional
    uint dwAuthError,   // DWORD
    ref uint pulAuthPackage,   // DWORD* in/out
    IntPtr pvInAuthBuffer,   // void* optional
    uint ulInAuthBufferSize,   // DWORD
    IntPtr ppvOutAuthBuffer,   // void** out
    out uint pulOutAuthBufferSize,   // DWORD* out
    IntPtr pfSave,   // BOOL* optional, in/out
    uint dwFlags   // CREDUIWIN_FLAGS
);

<DllImport("credui.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function CredUIPromptForWindowsCredentialsA(
    pUiInfo As IntPtr,   ' CREDUI_INFOA* optional
    dwAuthError As UInteger,   ' DWORD
    ByRef pulAuthPackage As UInteger,   ' DWORD* in/out
    pvInAuthBuffer As IntPtr,   ' void* optional
    ulInAuthBufferSize As UInteger,   ' DWORD
    ppvOutAuthBuffer As IntPtr,   ' void** out
    <Out> ByRef pulOutAuthBufferSize As UInteger,   ' DWORD* out
    pfSave As IntPtr,   ' BOOL* optional, in/out
    dwFlags As UInteger   ' CREDUIWIN_FLAGS
) As UInteger
End Function

' pUiInfo : CREDUI_INFOA* optional
' dwAuthError : DWORD
' pulAuthPackage : DWORD* in/out
' pvInAuthBuffer : void* optional
' ulInAuthBufferSize : DWORD
' ppvOutAuthBuffer : void** out
' pulOutAuthBufferSize : DWORD* out
' pfSave : BOOL* optional, in/out
' dwFlags : CREDUIWIN_FLAGS
Declare PtrSafe Function CredUIPromptForWindowsCredentialsA Lib "credui" ( _
    ByVal pUiInfo As LongPtr, _
    ByVal dwAuthError As Long, _
    ByRef pulAuthPackage As Long, _
    ByVal pvInAuthBuffer As LongPtr, _
    ByVal ulInAuthBufferSize As Long, _
    ByVal ppvOutAuthBuffer As LongPtr, _
    ByRef pulOutAuthBufferSize As Long, _
    ByVal pfSave As LongPtr, _
    ByVal dwFlags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CredUIPromptForWindowsCredentialsA = ctypes.windll.credui.CredUIPromptForWindowsCredentialsA
CredUIPromptForWindowsCredentialsA.restype = wintypes.DWORD
CredUIPromptForWindowsCredentialsA.argtypes = [
    ctypes.c_void_p,  # pUiInfo : CREDUI_INFOA* optional
    wintypes.DWORD,  # dwAuthError : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pulAuthPackage : DWORD* in/out
    ctypes.POINTER(None),  # pvInAuthBuffer : void* optional
    wintypes.DWORD,  # ulInAuthBufferSize : DWORD
    ctypes.c_void_p,  # ppvOutAuthBuffer : void** out
    ctypes.POINTER(wintypes.DWORD),  # pulOutAuthBufferSize : DWORD* out
    ctypes.c_void_p,  # pfSave : BOOL* optional, in/out
    wintypes.DWORD,  # dwFlags : CREDUIWIN_FLAGS
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('credui.dll')
CredUIPromptForWindowsCredentialsA = Fiddle::Function.new(
  lib['CredUIPromptForWindowsCredentialsA'],
  [
    Fiddle::TYPE_VOIDP,  # pUiInfo : CREDUI_INFOA* optional
    -Fiddle::TYPE_INT,  # dwAuthError : DWORD
    Fiddle::TYPE_VOIDP,  # pulAuthPackage : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # pvInAuthBuffer : void* optional
    -Fiddle::TYPE_INT,  # ulInAuthBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # ppvOutAuthBuffer : void** out
    Fiddle::TYPE_VOIDP,  # pulOutAuthBufferSize : DWORD* out
    Fiddle::TYPE_VOIDP,  # pfSave : BOOL* optional, in/out
    -Fiddle::TYPE_INT,  # dwFlags : CREDUIWIN_FLAGS
  ],
  -Fiddle::TYPE_INT)

#[link(name = "credui")]
extern "system" {
    fn CredUIPromptForWindowsCredentialsA(
        pUiInfo: *mut CREDUI_INFOA,  // CREDUI_INFOA* optional
        dwAuthError: u32,  // DWORD
        pulAuthPackage: *mut u32,  // DWORD* in/out
        pvInAuthBuffer: *const (),  // void* optional
        ulInAuthBufferSize: u32,  // DWORD
        ppvOutAuthBuffer: *mut *mut (),  // void** out
        pulOutAuthBufferSize: *mut u32,  // DWORD* out
        pfSave: *mut i32,  // BOOL* optional, in/out
        dwFlags: u32  // CREDUIWIN_FLAGS
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("credui.dll", CharSet = CharSet.Ansi)]
public static extern uint CredUIPromptForWindowsCredentialsA(IntPtr pUiInfo, uint dwAuthError, ref uint pulAuthPackage, IntPtr pvInAuthBuffer, uint ulInAuthBufferSize, IntPtr ppvOutAuthBuffer, out uint pulOutAuthBufferSize, IntPtr pfSave, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'credui_CredUIPromptForWindowsCredentialsA' -Namespace Win32 -PassThru
# $api::CredUIPromptForWindowsCredentialsA(pUiInfo, dwAuthError, pulAuthPackage, pvInAuthBuffer, ulInAuthBufferSize, ppvOutAuthBuffer, pulOutAuthBufferSize, pfSave, dwFlags)

#uselib "credui.dll"
#func global CredUIPromptForWindowsCredentialsA "CredUIPromptForWindowsCredentialsA" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; CredUIPromptForWindowsCredentialsA varptr(pUiInfo), dwAuthError, varptr(pulAuthPackage), pvInAuthBuffer, ulInAuthBufferSize, ppvOutAuthBuffer, varptr(pulOutAuthBufferSize), varptr(pfSave), dwFlags   ; 戻り値は stat
; pUiInfo : CREDUI_INFOA* optional -> "sptr"
; dwAuthError : DWORD -> "sptr"
; pulAuthPackage : DWORD* in/out -> "sptr"
; pvInAuthBuffer : void* optional -> "sptr"
; ulInAuthBufferSize : DWORD -> "sptr"
; ppvOutAuthBuffer : void** out -> "sptr"
; pulOutAuthBufferSize : DWORD* out -> "sptr"
; pfSave : BOOL* optional, in/out -> "sptr"
; dwFlags : CREDUIWIN_FLAGS -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "credui.dll"
#cfunc global CredUIPromptForWindowsCredentialsA "CredUIPromptForWindowsCredentialsA" var, int, var, sptr, int, sptr, var, var, int
; res = CredUIPromptForWindowsCredentialsA(pUiInfo, dwAuthError, pulAuthPackage, pvInAuthBuffer, ulInAuthBufferSize, ppvOutAuthBuffer, pulOutAuthBufferSize, pfSave, dwFlags)
; pUiInfo : CREDUI_INFOA* optional -> "var"
; dwAuthError : DWORD -> "int"
; pulAuthPackage : DWORD* in/out -> "var"
; pvInAuthBuffer : void* optional -> "sptr"
; ulInAuthBufferSize : DWORD -> "int"
; ppvOutAuthBuffer : void** out -> "sptr"
; pulOutAuthBufferSize : DWORD* out -> "var"
; pfSave : BOOL* optional, in/out -> "var"
; dwFlags : CREDUIWIN_FLAGS -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "credui.dll"
#cfunc global CredUIPromptForWindowsCredentialsA "CredUIPromptForWindowsCredentialsA" sptr, int, sptr, sptr, int, sptr, sptr, sptr, int
; res = CredUIPromptForWindowsCredentialsA(varptr(pUiInfo), dwAuthError, varptr(pulAuthPackage), pvInAuthBuffer, ulInAuthBufferSize, ppvOutAuthBuffer, varptr(pulOutAuthBufferSize), varptr(pfSave), dwFlags)
; pUiInfo : CREDUI_INFOA* optional -> "sptr"
; dwAuthError : DWORD -> "int"
; pulAuthPackage : DWORD* in/out -> "sptr"
; pvInAuthBuffer : void* optional -> "sptr"
; ulInAuthBufferSize : DWORD -> "int"
; ppvOutAuthBuffer : void** out -> "sptr"
; pulOutAuthBufferSize : DWORD* out -> "sptr"
; pfSave : BOOL* optional, in/out -> "sptr"
; dwFlags : CREDUIWIN_FLAGS -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。