WinBioControlUnitPrivileged, fonction (winbio.h)

Article
08/27/2023

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.

Valeur	Signification
WINBIO_COMPONENT_SENSOR	Envoyez la commande à l’adaptateur de capteur.
WINBIO_COMPONENT_ENGINE	Envoyez la commande à l’adaptateur du moteur.
WINBIO_COMPONENT_STORAGE	Envoyez la commande à l’adaptateur de stockage.

[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
E_HANDLE	Le handle de session n’est pas valide.
E_INVALIDARG	La valeur spécifiée dans le paramètre ControlCode n’est pas reconnue.
E_POINTER	Les paramètres SendBuffer, ReceiveBuffer, ReceiveDataSize et OperationStatus ne peuvent pas être NULL.
E_ACCESSDENIED	L’appelant n’est pas autorisé à effectuer l’opération ou la session n’a pas été ouverte à l’aide de WINBIO_FLAG_MAINTENANCE.
E_INVALIDARG	La valeur spécifiée dans le paramètre ControlCode n’est pas reconnue.
WINBIO_E_LOCK_VIOLATION	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.

Pour éviter les fuites de mémoire, vous devez appeler WinBioFree pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.

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

WinBioControlUnit

WinBioLockUnit

Partager via