Funzione WinBioControlUnitPrivileged (winbio.h)
Consente al chiamante di eseguire operazioni di controllo definite dal fornitore con privilegi in un'unità biometrica. A partire da Windows 10, build 1607, questa funzione è disponibile per l'uso con un'immagine per dispositivi mobili. Il client deve chiamare questa funzione per eseguire operazioni del fornitore estese che richiedono diritti di accesso elevati. Se non sono necessari privilegi, il client può chiamare la funzione WinBioControlUnit .
Sintassi
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
);
Parametri
[in] SessionHandle
Valore WINBIO_SESSION_HANDLE che identifica una sessione biometrica aperta. Aprire un handle di sessione sincrono chiamando WinBioOpenSession. Aprire un handle di sessione asincrono chiamando WinBioAsyncOpenSession.
[in] UnitId
Valore WINBIO_UNIT_ID che identifica l'unità biometrica. Questo valore deve corrispondere all'ID unità usato in precedenza nella funzione WinBioLockUnit .
[in] Component
Valore WINBIO_COMPONENT che specifica il componente all'interno dell'unità biometrica che deve eseguire l'operazione. Questo può essere uno dei valori seguenti.
[in] ControlCode
Codice definito dal fornitore riconosciuto dall'unità biometrica specificata dal parametro UnitId e dall'adattatore specificato dal parametro Component .
SendBuffer
Indirizzo del buffer che contiene le informazioni di controllo da inviare all'adattatore specificato dal parametro Component . Il formato e il contenuto del buffer sono definiti dal fornitore.
[in] SendBufferSize
Dimensioni, in byte, del buffer specificato dal parametro SendBuffer .
ReceiveBuffer
Indirizzo del buffer che riceve informazioni inviate dall'adattatore specificato dal parametro Component . Il formato e il contenuto del buffer sono definiti dal fornitore.
[in] ReceiveBufferSize
Dimensioni, in byte, del buffer specificato dal parametro ReceiveBuffer .
ReceiveDataSize
Puntatore a un valore SIZE_T contenente le dimensioni, in byte, dei dati scritti nel buffer specificato dal parametro ReceiveBuffer .
[out, optional] OperationStatus
Puntatore a un intero contenente un codice di stato definito dal fornitore che specifica il risultato dell'operazione di controllo.
Valore restituito
Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, restituisce un valore HRESULT che indica l'errore. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.
| Codice restituito | Descrizione |
|---|---|
|
L'handle di sessione non è valido. |
|
Il valore specificato nel parametro ControlCode non viene riconosciuto. |
|
I parametri SendBuffer, ReceiveBuffer, ReceiveDataSize, OperationStatus non possono essere NULL. |
|
Il chiamante non dispone dell'autorizzazione per eseguire l'operazione oppure la sessione non è stata aperta usando WINBIO_FLAG_MAINTENANCE. |
|
Il valore specificato nel parametro ControlCode non viene riconosciuto. |
|
L'unità biometrica specificata dal parametro UnitId deve essere bloccata prima di eseguire qualsiasi operazione di controllo. |
Commenti
I fornitori che creano plug-in devono decidere quali operazioni estese sono privilegiate e quali sono disponibili per tutti i client. Per eseguire un'operazione con privilegi, l'applicazione client deve chiamare la funzione WinBioControlUnitPrivileged . Windows Biometric Framework consente solo ai client che dispongono dei diritti di accesso appropriati per chiamare questa funzione. Per eseguire un'operazione che non richiede privilegi, il client deve chiamare la funzione WinBioControlUnit .
È necessario chiamare WinBioLockUnit prima di chiamare WinBioControlUnitPrivileged. La funzione WinBioLockUnit crea un'area bloccata in cui è possibile eseguire in modo sicuro le operazioni definite dal fornitore.
Per chiamare correttamente questa funzione, l'handle di sessione deve essere stato aperto specificando WINBIO_FLAG_MAINTENANCE. Solo gli account Administrators e Local System dispongono dei privilegi necessari.
Per usare WinBioControlUnitPrivileged in modo sincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioOpenSession. La funzione blocca finché l'operazione non viene completata o viene rilevato un errore.
Per usare WinBioControlUnitPrivileged in modo asincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioAsyncOpenSession. Il framework alloca una struttura WINBIO_ASYNC_RESULT e la usa per restituire informazioni sull'esito positivo o negativo dell'operazione. La struttura WINBIO_ASYNC_RESULT viene restituita al callback dell'applicazione o alla coda di messaggi dell'applicazione, a seconda del valore impostato nel parametro NotificationMethod della funzione WinBioAsyncOpenSession .
- Se si sceglie di ricevere avvisi di completamento usando un callback, è necessario implementare una funzione PWINBIO_ASYNC_COMPLETION_CALLBACK e impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_CALLBACK.
- Se si sceglie di ricevere avvisi di completamento usando la coda di messaggi dell'applicazione, è necessario impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_MESSAGE. Il framework restituisce un puntatore WINBIO_ASYNC_RESULT al campo LPARAM del messaggio della finestra.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbio.h (include Winbio.h) |
| Libreria | Winbio.lib |
| DLL | Winbio.dll |