WinBioGetCredentialState-Funktion (winbio.h)

Artikel
03/06/2024

Ruft einen Wert ab, der angibt, ob Anmeldeinformationen für den angegebenen Benutzer festgelegt wurden. Ab Windows 10 Build 1607 ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.

Syntax

HRESULT WinBioGetCredentialState(
  [in]  WINBIO_IDENTITY         Identity,
  [in]  WINBIO_CREDENTIAL_TYPE  Type,
  [out] WINBIO_CREDENTIAL_STATE *CredentialState
);

Parameter

[in] Identity

Eine WINBIO_IDENTITY Struktur, die die SID des Benutzerkontos enthält, für das die Anmeldeinformationen abgefragt werden.

[in] Type

Ein WINBIO_CREDENTIAL_TYPE Wert, der den Anmeldeinformationstyp angibt. Mögliche Werte:

Wert	Bedeutung
WINBIO_CREDENTIAL_PASSWORD	Die kennwortbasierten Anmeldeinformationen werden überprüft.

[out] CredentialState

Zeiger auf einen WINBIO_CREDENTIAL_STATE Enumerationswert, der angibt, ob Benutzeranmeldeinformationen festgelegt wurden. Mögliche Werte:

Wert	Bedeutung
WINBIO_CREDENTIAL_NOT_SET	Es wurden keine Anmeldeinformationen angegeben.
WINBIO_CREDENTIAL_SET	Es wurden Anmeldeinformationen angegeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, wird ein HRESULT-Wert zurückgegeben, der den Fehler angibt. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle. Eine Liste allgemeiner Fehlercodes finden Sie unter Allgemeine HRESULT-Werte.

Rückgabecode	Beschreibung
E_ACCESSDENIED	Der Aufrufer verfügt nicht über die Berechtigung zum Abrufen des Anmeldeinformationsstatus.
WINBIO_E_UNKNOWN_ID	Die angegebene Identität ist nicht vorhanden.
WINBIO_E_CRED_PROV_DISABLED	Die aktuelle Verwaltungsrichtlinie verbietet die Verwendung des Anmeldeinformationsanbieters.

Hinweise

WinBioGetCredentialState wird in der Regel verwendet, um Feedback zum Status von Anmeldeinformationen auf einer Benutzeroberfläche zu geben. Beispielsweise kann eine Registrierungsanwendung den Anmeldeinformationsstatus abfragen, bevor sie einen Benutzer zur Eingabe von Anmeldeinformationen auffordert.

Rufen Sie die WinBioSetCredential-Funktion auf, um Anmeldeinformationen einem Benutzer zuzuordnen.

Benutzer, die nicht über erhöhte Berechtigungen verfügen, können nur Informationen zu ihren eigenen Anmeldeinformationen abrufen. Benutzer mit erhöhten Rechten können Informationen für alle Anmeldeinformationen abrufen.

Beispiele

Die folgende Funktion ruft WinBioGetCredentialState auf, um den Anmeldeinformationsstatus für einen Benutzer abzurufen. Verknüpfen Sie die statische Winbio.lib-Bibliothek, und schließen Sie die folgenden Headerdateien ein:

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

HRESULT GetCredentialState()
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity;
    WINBIO_CREDENTIAL_STATE credState;

    // Find the identity of the user.
    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;
    }

    // Find the credential state for the user.
    wprintf_s(L"\n Calling WinBioGetCredentialState.\n");
    hr = WinBioGetCredentialState(
             identity,                      // User GUID or SID
             WINBIO_CREDENTIAL_PASSWORD,    // Credential type
             &credState                     // [out] Credential state
             );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioGetCredentialState failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the credential state.
    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;

}

//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // Declare variables.
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // Zero the input identity and specify the type.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // Open the access token associated with the
    // current process
    if (!OpenProcessToken(
            GetCurrentProcess(),            // Process handle
            TOKEN_READ,                     // Read access only
            &tokenHandle))                  // Access token handle
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Zero the tokenInfoBuffer structure.
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // Retrieve information about the access token. In this case,
    // retrieve a SID.
    if (!GetTokenInformation(
            tokenHandle,                    // Access token handle
            TokenUser,                      // User for the token
            &tokenInfoBuffer.tokenUser,     // Buffer to fill
            sizeof(tokenInfoBuffer),        // Size of the buffer
            &bytesReturned))                // Size needed
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Copy the SID from the tokenInfoBuffer structure to the
    // WINBIO_IDENTITY structure. 
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // Specify the size of the SID and assign WINBIO_ID_TYPE_SID
    // to the type member of the WINBIO_IDENTITY structure.
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

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

    return hr;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio.h (winbio.h einschließen)
Bibliothek	Winbio.lib
DLL	Winbio.dll

Weitere Informationen

WinBioSetCredential

Freigeben über