Fonction WinBioControlUnit (winbio.h)
Permet à l’appelant d’effectuer des opérations de contrôle définies par le fournisseur sur une unité biométrique. À compter de Windows 10 build 1607, cette fonction peut être utilisée avec une image mobile. Cette fonction est fournie pour l’accès aux opérations de fournisseur étendues pour lesquelles des privilèges élevés ne sont pas requis. Si des droits d’accès sont requis, appelez la fonction WinBioControlUnitPrivileged .
Syntaxe
HRESULT WinBioControlUnit(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_UNIT_ID UnitId,
[in] WINBIO_COMPONENT Component,
[in] ULONG ControlCode,
PUCHAR SendBuffer,
[in] SIZE_T SendBufferSize,
PUCHAR ReceiveBuffer,
[in] SIZE_T ReceiveBufferSize,
SIZE_T *ReceiveDataSize,
[out, optional] ULONG *OperationStatus
);
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] UnitId
Valeur WINBIO_UNIT_ID qui identifie l’unité biométrique. Cette valeur doit correspondre à l’ID d’unité utilisé précédemment dans la fonction WinBioLockUnit .
[in] Component
Valeur WINBIO_COMPONENT qui spécifie le composant dans l’unité biométrique qui doit effectuer l’opération. Il peut s’agir de l’une des valeurs suivantes.
[in] ControlCode
Code défini par le fournisseur reconnu par l’unité biométrique spécifiée par le paramètre UnitId et l’adaptateur spécifié par le paramètre Component .
SendBuffer
Adresse de la mémoire tampon qui contient les informations de contrôle à envoyer à l’adaptateur spécifié par le paramètre Component . Le format et le contenu de la mémoire tampon sont définis par le fournisseur.
[in] SendBufferSize
Taille, en octets, de la mémoire tampon spécifiée par le paramètre SendBuffer .
ReceiveBuffer
Adresse de la mémoire tampon qui reçoit les informations envoyées par l’adaptateur spécifié par le paramètre Component . Le format et le contenu de la mémoire tampon sont définis par le fournisseur.
[in] ReceiveBufferSize
Taille, en octets, de la mémoire tampon spécifiée par le paramètre ReceiveBuffer .
ReceiveDataSize
Pointeur vers une valeur SIZE_T qui contient la taille, en octets, des données écrites dans la mémoire tampon spécifiée par le paramètre ReceiveBuffer .
[out, optional] OperationStatus
Pointeur vers un entier qui contient un code status défini par le fournisseur qui spécifie le résultat de l’opération de contrôle.
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 |
|---|---|
|
Le handle de session n’est pas valide. |
|
La valeur spécifiée dans le paramètre ControlCode n’est pas reconnue. |
|
Les paramètres SendBuffer, ReceiveBuffer, ReceiveDataSize et OperationStatus ne peuvent pas être NULL. |
|
La valeur spécifiée dans le paramètre ControlCode n’est pas reconnue. |
|
L’unité biométrique spécifiée par le paramètre UnitId doit être verrouillée avant que des opérations de contrôle puissent être effectuées. |
Remarques
Vous devez appeler WinBioLockUnit avant d’appeler WinBioControlUnit. La fonction WinBioLockUnit crée une région verrouillée dans laquelle les opérations définies par le fournisseur peuvent être effectuées en toute sécurité.
Les fournisseurs qui créent des plug-ins doivent décider quelles opérations étendues sont privilégiées et lesquelles sont disponibles pour tous les clients. Pour effectuer une opération privilégiée, l’application cliente doit appeler la fonction WinBioControlUnitPrivileged . Le Framework biométrique Windows autorise uniquement les clients disposant des droits d’accès appropriés à appeler WinBioControlUnitPrivileged.
Pour utiliser WinBioControlUnit 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 utiliser WinBioControlUnit 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. 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 avez définie 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.
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 |