ホーム › Devices.BiometricFramework › WinBioGetCredentialState

WinBioGetCredentialState

関数

指定IDの生体認証資格情報の状態を取得する。

DLLwinbio.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// winbio.dll
#include <windows.h>

HRESULT WinBioGetCredentialState(
    WINBIO_IDENTITY Identity,
    WINBIO_CREDENTIAL_TYPE Type,
    WINBIO_CREDENTIAL_STATE* CredentialState
);

パラメーター

名前

型

方向

説明

Identity

WINBIO_IDENTITY

資格情報の照会対象となるユーザーアカウントの SID を含む WINBIO_IDENTITY 構造体です。

Type

WINBIO_CREDENTIAL_TYPE

資格情報の種類を指定する WINBIO_CREDENTIAL_TYPE 値です。次のいずれかの値を指定できます。

値	意味
WINBIO_CREDENTIAL_PASSWORD	パスワードベースの資格情報が確認されます。

CredentialState

WINBIO_CREDENTIAL_STATE*

out

ユーザーの資格情報が設定されているかどうかを示す WINBIO_CREDENTIAL_STATE 列挙値へのポインターです。次のいずれかの値になります。

値	意味
WINBIO_CREDENTIAL_NOT_SET	資格情報が指定されていません。
WINBIO_CREDENTIAL_SET	資格情報が指定されています。

戻り値の型: HRESULT

公式ドキュメント

指定したユーザーに対して資格情報が設定されているかどうかを示す値を取得します。Windows 10 ビルド 1607 以降、この関数はモバイルイメージで使用できます。

戻り値

関数が成功すると S_OK を返します。関数が失敗すると、エラーを示す HRESULT 値を返します。返される値には次の表の値が含まれますが、これらに限定されません。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

リターンコード	説明
E_ACCESSDENIED	呼び出し元に資格情報の状態を取得するアクセス許可がありません。
WINBIO_E_UNKNOWN_ID	指定された ID は存在しません。
WINBIO_E_CRED_PROV_DISABLED	現在の管理ポリシーにより、資格情報プロバイダーの使用が禁止されています。

解説(Remarks)

WinBioGetCredentialState は通常、ユーザーインターフェイスで資格情報の状態をフィードバックするために使用します。たとえば、登録アプリケーションがユーザーに資格情報の入力を求める前に、資格情報の状態を照会することがあります。

資格情報をユーザーに関連付けるには、WinBioSetCredential 関数を呼び出します。

昇格された特権を持たないユーザーは、自分自身の資格情報に関する情報のみを取得できます。昇格されたユーザーは、任意の資格情報の情報を取得できます。

例

次の関数は、WinBioGetCredentialState を呼び出してユーザーの資格情報の状態を取得します。Winbio.lib 静的ライブラリにリンクし、次のヘッダーファイルをインクルードしてください。

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT GetCredentialState()
{
    // 変数を宣言します。
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity;
    WINBIO_CREDENTIAL_STATE credState;

    // ユーザーの ID を検索します。
    wprintf_s(L"\n Finding user identity.\n");
    hr = GetCurrentUserIdentity( &identity );
    if (FAILED(hr))
    {
        wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
        return hr;
    }

    // ユーザーの資格情報の状態を取得します。
    wprintf_s(L"\n Calling WinBioGetCredentialState.\n");
    hr = WinBioGetCredentialState(
             identity,                      // ユーザーの GUID または SID
             WINBIO_CREDENTIAL_PASSWORD,    // 資格情報の種類
             &credState                     // [out] 資格情報の状態
             );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioGetCredentialState failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // 資格情報の状態を出力します。
    switch(credState)
    {
        case WINBIO_CREDENTIAL_SET:
            wprintf_s(L"\n Credential set.\n");
            break;
        case WINBIO_CREDENTIAL_NOT_SET:
            wprintf_s(L"\n Credential NOT set.\n");
            break;
        default:
            wprintf_s(L"\n ERROR: Invalid credential state.\n");
            hr = E_FAIL;
    }

e_Exit:

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;

}

//------------------------------------------------------------------------
// 次の関数は、現在のユーザーの ID を取得します。
// これはヘルパー関数であり、Windows Biometric Framework API の
// 一部ではありません。
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // 変数を宣言します。
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // 入力の identity をゼロクリアし、種類を指定します。
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // 現在のプロセスに関連付けられている
    // アクセス トークンを開きます。
    if (!OpenProcessToken(
            GetCurrentProcess(),            // プロセス ハンドル
            TOKEN_READ,                     // 読み取りアクセスのみ
            &tokenHandle))                  // アクセス トークン ハンドル
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // tokenInfoBuffer 構造体をゼロクリアします。
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // アクセス トークンに関する情報を取得します。ここでは
    // SID を取得します。
    if (!GetTokenInformation(
            tokenHandle,                    // アクセス トークン ハンドル
            TokenUser,                      // トークンのユーザー
            &tokenInfoBuffer.tokenUser,     // 格納先のバッファー
            sizeof(tokenInfoBuffer),        // バッファーのサイズ
            &bytesReturned))                // 必要なサイズ
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // tokenInfoBuffer 構造体から WINBIO_IDENTITY 構造体に
    // SID をコピーします。
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // SID のサイズを指定し、WINBIO_IDENTITY 構造体の type メンバーに
    // WINBIO_ID_TYPE_SID を設定します。
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

    if (tokenHandle != NULL)
    {
        CloseHandle(tokenHandle);
    }

    return hr;
}

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

各言語での呼び出し定義

// winbio.dll
#include <windows.h>

HRESULT WinBioGetCredentialState(
    WINBIO_IDENTITY Identity,
    WINBIO_CREDENTIAL_TYPE Type,
    WINBIO_CREDENTIAL_STATE* CredentialState
);

[DllImport("winbio.dll", ExactSpelling = true)]
static extern int WinBioGetCredentialState(
    WINBIO_IDENTITY Identity,   // WINBIO_IDENTITY
    int Type,   // WINBIO_CREDENTIAL_TYPE
    out int CredentialState   // WINBIO_CREDENTIAL_STATE* out
);

<DllImport("winbio.dll", ExactSpelling:=True)>
Public Shared Function WinBioGetCredentialState(
    Identity As WINBIO_IDENTITY,   ' WINBIO_IDENTITY
    Type As Integer,   ' WINBIO_CREDENTIAL_TYPE
    <Out> ByRef CredentialState As Integer   ' WINBIO_CREDENTIAL_STATE* out
) As Integer
End Function

' Identity : WINBIO_IDENTITY
' Type : WINBIO_CREDENTIAL_TYPE
' CredentialState : WINBIO_CREDENTIAL_STATE* out
Declare PtrSafe Function WinBioGetCredentialState Lib "winbio" ( _
    ByVal Identity As LongPtr, _
    ByVal Type As Long, _
    ByRef CredentialState As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinBioGetCredentialState = ctypes.windll.winbio.WinBioGetCredentialState
WinBioGetCredentialState.restype = ctypes.c_int
WinBioGetCredentialState.argtypes = [
    WINBIO_IDENTITY,  # Identity : WINBIO_IDENTITY
    ctypes.c_int,  # Type : WINBIO_CREDENTIAL_TYPE
    ctypes.c_void_p,  # CredentialState : WINBIO_CREDENTIAL_STATE* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('winbio.dll')
WinBioGetCredentialState = Fiddle::Function.new(
  lib['WinBioGetCredentialState'],
  [
    Fiddle::TYPE_VOIDP,  # Identity : WINBIO_IDENTITY
    Fiddle::TYPE_INT,  # Type : WINBIO_CREDENTIAL_TYPE
    Fiddle::TYPE_VOIDP,  # CredentialState : WINBIO_CREDENTIAL_STATE* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winbio")]
extern "system" {
    fn WinBioGetCredentialState(
        Identity: WINBIO_IDENTITY,  // WINBIO_IDENTITY
        Type: i32,  // WINBIO_CREDENTIAL_TYPE
        CredentialState: *mut i32  // WINBIO_CREDENTIAL_STATE* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("winbio.dll")]
public static extern int WinBioGetCredentialState(WINBIO_IDENTITY Identity, int Type, out int CredentialState);
"@
$api = Add-Type -MemberDefinition $sig -Name 'winbio_WinBioGetCredentialState' -Namespace Win32 -PassThru
# $api::WinBioGetCredentialState(Identity, Type, CredentialState)

#uselib "winbio.dll"
#func global WinBioGetCredentialState "WinBioGetCredentialState" sptr, sptr, sptr
; WinBioGetCredentialState Identity, Type, varptr(CredentialState)   ; 戻り値は stat
; Identity : WINBIO_IDENTITY -> "sptr"
; Type : WINBIO_CREDENTIAL_TYPE -> "sptr"
; CredentialState : WINBIO_CREDENTIAL_STATE* out -> "sptr"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "winbio.dll"
#cfunc global WinBioGetCredentialState "WinBioGetCredentialState" int, int, var
; res = WinBioGetCredentialState(Identity, Type, CredentialState)
; Identity : WINBIO_IDENTITY -> "int"
; Type : WINBIO_CREDENTIAL_TYPE -> "int"
; CredentialState : WINBIO_CREDENTIAL_STATE* out -> "var"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "winbio.dll"
#cfunc global WinBioGetCredentialState "WinBioGetCredentialState" int, int, sptr
; res = WinBioGetCredentialState(Identity, Type, varptr(CredentialState))
; Identity : WINBIO_IDENTITY -> "int"
; Type : WINBIO_CREDENTIAL_TYPE -> "int"
; CredentialState : WINBIO_CREDENTIAL_STATE* out -> "sptr"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。