WinBioControlUnitPrivileged, fonction (winbio.h)
Permet à l’appelant d’effectuer des opérations de contrôle privilégiées 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. Le client doit appeler cette fonction pour effectuer des opérations de fournisseur étendues qui nécessitent des droits d’accès élevés. Si aucun privilège n’est requis, le client peut appeler la fonction WinBioControlUnit .
Syntaxe
HRESULT WinBioControlUnitPrivileged(
[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. |
|
L’appelant n’est pas autorisé à effectuer l’opération ou la session n’a pas été ouverte à l’aide de WINBIO_FLAG_MAINTENANCE. |
|
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
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 . L’infrastructure biométrique Windows autorise uniquement les clients disposant des droits d’accès appropriés à appeler cette fonction. Pour effectuer une opération qui ne nécessite pas de privilèges, le client doit appeler la fonction WinBioControlUnit .
Vous devez appeler WinBioLockUnit avant d’appeler WinBioControlUnitPrivileged. 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é.
Pour appeler correctement cette fonction, le handle de session doit avoir été ouvert en spécifiant WINBIO_FLAG_MAINTENANCE. Seuls les comptes Administrateurs et Système local disposent des privilèges nécessaires.
Pour utiliser WinBioControlUnitPrivileged de manière synchrone, appelez la fonction avec un handle de session créé en appelant WinBioOpenSession. La fonction se bloque jusqu’à ce que l’opération se termine ou qu’une erreur se produise.
Pour utiliser WinBioControlUnitPrivileged de manière asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. L’infrastructure alloue une structure 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 d’application ou à la file d’attente des messages d’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 |