Fonction WinBioGetCredentialState (winbio.h)

Article
08/27/2023

Récupère une valeur qui spécifie si des informations d’identification ont été définies pour l’utilisateur spécifié. À compter de Windows 10 build 1607, cette fonction peut être utilisée avec une image mobile.

Syntaxe

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

Paramètres

[in] Identity

Une structure WINBIO_IDENTITY qui contient le SID du compte d’utilisateur pour lequel les informations d’identification sont interrogées.

[in] Type

Valeur WINBIO_CREDENTIAL_TYPE qui spécifie le type d’informations d’identification. Il peut s’agir de l’une des valeurs suivantes :

Valeur	Signification
WINBIO_CREDENTIAL_PASSWORD	Les informations d’identification basées sur le mot de passe sont vérifiées.

[out] CredentialState

Pointeur vers une valeur d’énumération WINBIO_CREDENTIAL_STATE qui spécifie si les informations d’identification de l’utilisateur ont été définies. Il peut s’agir de l’une des valeurs suivantes :

Valeur	Signification
WINBIO_CREDENTIAL_NOT_SET	Aucune information d’identification n’a été spécifiée.
WINBIO_CREDENTIAL_SET	Des informations d’identification ont été spécifiées.

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles sont notamment celles figurant dans le tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Code de retour	Description
E_ACCESSDENIED	L’appelant n’a pas l’autorisation de récupérer l’état des informations d’identification.
WINBIO_E_UNKNOWN_ID	L’identité spécifiée n’existe pas.
WINBIO_E_CRED_PROV_DISABLED	La stratégie d’administration actuelle interdit l’utilisation du fournisseur d’informations d’identification.

Remarques

WinBioGetCredentialState est généralement utilisé pour fournir des commentaires sur l’état des informations d’identification dans une interface utilisateur. Par exemple, une application d’inscription peut interroger l’état des informations d’identification avant d’inviter un utilisateur à entrer des informations d’identification.

Appelez la fonction WinBioSetCredential pour associer des informations d’identification à un utilisateur.

Les utilisateurs qui ne disposent pas de privilèges élevés peuvent récupérer des informations uniquement sur leurs propres informations d’identification. Les utilisateurs avec élévation de privilèges peuvent récupérer des informations pour toutes les informations d’identification.

Exemples

La fonction suivante appelle WinBioGetCredentialState pour récupérer l’état des informations d’identification d’un utilisateur. Créez un lien vers la bibliothèque statique Winbio.lib et incluez les fichiers d’en-tête suivants :

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;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbio.h (inclure Winbio.h)
Bibliothèque	Winbio.lib
DLL	Winbio.dll

Voir aussi

WinBioSetCredential

Partager via