Fonction WinBioGetProperty (winbio.h)

Article
08/27/2023

Récupère une session, une unité ou une propriété de modèle. À compter de Windows 10 build 1607, cette fonction peut être utilisée avec une image mobile.

Syntaxe

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

Paramètres

[in] SessionHandle

Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte. Ouvrez un handle de session synchrone en appelant WinBioOpenSession. Ouvrez un handle de session asynchrone en appelant WinBioAsyncOpenSession.

[in] PropertyType

Valeur WINBIO_PROPERTY_TYPE qui spécifie la source des informations de propriété. Actuellement, cela doit être WINBIO_PROPERTY_TYPE_UNIT ou WINBIO_PROPERTY_TYPE_ACCOUNT. Pour plus d’informations sur les types de propriétés, consultez constantes WINBIO_PROPERTY_TYPE.

La valeur WINBIO_PROPERTY_TYPE_ACCOUNT est prise en charge à partir de Windows 10.

[in] PropertyId

Valeur WINBIO_PROPERTY_ID qui spécifie la propriété que vous souhaitez interroger. Les valeurs suivantes sont possibles.

Valeur	Signification
WINBIO_PROPERTY_SAMPLE_HINT	Estime le nombre maximal d’exemples biométriques appropriés qui sont nécessaires pour effectuer un modèle d’inscription. Le résultat de la requête de propriété est retourné dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que valeur ULONG qui contient l’indicateur.
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO	Contient des informations étendues sur les fonctionnalités et les attributs du composant de capteur connecté à une unité biométrique spécifique. Le résultat de la requête de propriété est retourné dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que structure WINBIO_EXTENDED_SENSOR_INFO . Cette valeur est prise en charge à partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO	Contient des informations étendues sur les fonctionnalités et les attributs du composant moteur connecté à une unité biométrique spécifique. Le résultat de la requête de propriété est retourné dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que structure WINBIO_EXTENDED_ENGINE_INFO . Cette valeur est prise en charge à partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO	Contient des informations étendues sur les fonctionnalités et les attributs du composant de stockage connecté à une unité biométrique spécifique. Le résultat de la requête de propriété est retourné dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que structure WINBIO_EXTENDED_STORAGE_INFO . Cette valeur est prise en charge à partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS	Contient des informations étendues sur la status d’une inscription en cours sur une unité biométrique spécifique. Le résultat de la requête de propriété est retourné dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que structure WINBIO_EXTENDED_ENROLLMENT_STATUS . Si aucune inscription n’est en cours sur l’unité biométrique, le membre TemplateStatus de la structure retournée a la valeur WINBIO_E_INVALID_OPERATION. Cette valeur est prise en charge à partir de Windows 10.
WINBIO_PROPERTY_ANTI_SPOOF_POLICY	Contient les valeurs de la stratégie d’anti-usurpation pour un compte d’utilisateur spécifique. L’opération de propriété est retournée dans la mémoire tampon vers laquelle le paramètre PropertyBuffer pointe en tant que structure WINBIO_ANTI_SPOOF_POLICY . Cette valeur est prise en charge à partir de Windows 10.

Pour plus d’informations sur ces propriétés, consultez constantes WINBIO_PROPERTY.

[in, optional] UnitId

Valeur WINBIO_UNIT_ID qui identifie l’unité biométrique. Vous pouvez trouver un identificateur d’unité en appelant les fonctions WinBioEnumBiometricUnits ou WinBioLocateSensor .

Si vous spécifiez WINBIO_PROPERTY_ANTI_SPOOF_POLICY comme valeur pour le paramètre PropertyId , spécifiez 0 pour le paramètre UnitId . Si vous spécifiez une autre propriété avec le paramètre PropertyId , vous ne pouvez pas spécifier 0 pour le paramètre UnitId .

[in, optional] Identity

Structure WINBIO_IDENTITY qui fournit le SID du compte pour lequel vous souhaitez obtenir la stratégie d’antispoofing, si vous spécifiez WINBIO_PROPERTY_ANTI_SPOOF_POLICY comme valeur du paramètre PropertyId .

Si vous spécifiez une autre valeur pour le paramètre PropertyId , le paramètre Identity doit avoir la valeur NULL.

[in, optional] SubFactor

Réservé. Cela doit être WINBIO_SUBTYPE_NO_INFORMATION.

PropertyBuffer

Adresse d’un pointeur vers une mémoire tampon qui reçoit la valeur de la propriété. Pour plus d’informations sur le contenu de cette mémoire tampon pour les différentes propriétés, consultez les descriptions des valeurs de propriété pour le paramètre PropertyId .

[out, optional] PropertyBufferSize

Pointeur vers une variable qui reçoit la taille, en octets, de la mémoire tampon pointée par le paramètre PropertyBuffer .

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_HANDLE	Le handle de session spécifié par le paramètre SessionHandle n’est pas valide.
E_POINTER	Les arguments Identity, PropertyBuffer ou PropertyBufferSize ne peuvent pas être NULL.
E_INVALIDARG	Les arguments UnitId, Identity ou SubFactor sont incorrects.
WINBIO_E_INVALID_PROPERTY_TYPE	La valeur de l’argument PropertyType est incorrecte.
WINBIO_E_INVALID_PROPERTY_ID	La valeur de l’argument PropertyId est incorrecte.
WINBIO_E_LOCK_VIOLATION	L’appelant a tenté d’interroger une propriété qui se trouve à l’intérieur d’une région verrouillée.
WINBIO_E_UNSUPPORTED_PROPERTY	L’objet interrogé ne prend pas en charge la propriété spécifiée.
WINBIO_E_ENROLLMENT_IN_PROGRESS	L’opération n’a pas pu être effectuée, car l’unité biométrique spécifiée est actuellement utilisée pour une transaction d’inscription (pool système uniquement).

Remarques

Pour utiliser WinBioGetProperty de manière synchrone, appelez la fonction avec un handle de session créé en appelant WinBioOpenSession. La fonction est bloquée jusqu’à ce que l’opération se termine ou qu’une erreur soit rencontrée. Pour éviter les fuites de mémoire lorsque vous utilisez WinBioGetProperty de manière synchrone, vous devez appeler WinBioFree pour libérer la mémoire vers laquelle pointe le paramètre PropertyBuffer lorsque vous avez terminé d’utiliser les données contenues dans la mémoire tampon.

Pour utiliser WinBioGetProperty de manière asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. L’infrastructure alloue une structure de WINBIO_ASYNC_RESULT et l’utilise pour retourner des informations sur la réussite ou l’échec de l’opération. Si l’opération réussit, l’infrastructure retourne des informations dans une structure GetProperty imbriquée. La structure WINBIO_ASYNC_RESULT est retournée au rappel de l’application ou à la file d’attente des messages de l’application, en fonction de la valeur que vous définissez dans le paramètre NotificationMethod de la fonction WinBioAsyncOpenSession :

Si vous choisissez de recevoir des notifications d’achèvement à l’aide d’un rappel, vous devez implémenter une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK et définir le paramètre NotificationMethod sur WINBIO_ASYNC_NOTIFY_CALLBACK.
Si vous choisissez de recevoir des notifications d’achèvement à l’aide de la file d’attente de messages d’application, vous devez définir le paramètre NotificationMethodsur WINBIO_ASYNC_NOTIFY_MESSAGE. L’infrastructure retourne un pointeur WINBIO_ASYNC_RESULT vers le champ LPARAM du message de fenêtre.

Pour éviter les fuites de mémoire lorsque vous utilisez WinBioGetProperty de manière asynchrone, vous devez appeler WinBioFree pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser. La structure WINBIO_ASYNC_RESULT et la mémoire tampon de propriété occupent un seul bloc de mémoire. Votre application n’a donc qu’à passer l’adresse de la structure WINBIO_ASYNC_RESULT à WinBioFree. Lorsque vous appelez WinBioFree de cette façon, WinBioFree libère automatiquement la structure WINBIO_ASYNC_RESULT et la mémoire tampon de propriété. Si vous essayez de libérer la mémoire tampon de propriété séparément dans ce cas, l’application cesse de répondre.

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

WinBioFree

WinBioSetProperty

Partager via