Condividi tramite

Funzione WinBioAsyncOpenSession (winbio.h)

  • Articolo

Si connette in modo asincrono a un provider di servizi biometrici e a una o più unità biometriche. A partire da Windows 10, build 1607, questa funzione è disponibile per l'uso con un'immagine per dispositivi mobili. In caso di esito positivo, la funzione restituisce un handle di sessione biometrico. Ogni operazione eseguita tramite questo handle verrà completata in modo asincrono, incluso WinBioCloseSession, e i risultati verranno restituiti all'applicazione client usando il metodo specificato nel parametro NotificationMethod .

Per una versione sincrona di questa funzione, vedere WinBioOpenSession.

Sintassi

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

Parametri

[in] Factor

Maschera di bit di flag WINBIO_BIOMETRIC_TYPE che specifica i tipi di unità biometrica da enumerare. Attualmente è supportato solo WINBIO_TYPE_FINGERPRINT .

[in] PoolType

Valore ULONG che specifica il tipo di unità biometriche che verranno utilizzate nella sessione. I valori possibili sono i seguenti:

Valore Significato
WINBIO_POOL_SYSTEM
 La sessione si connette a una raccolta condivisa di unità biometriche gestite dal provider di servizi.
WINBIO_POOL_PRIVATE
 La sessione si connette a una raccolta di unità biometriche gestite dal chiamante.

[in] Flags

Valore ULONG che specifica le caratteristiche di configurazione e accesso dell'unità biometrica per la nuova sessione. I flag di configurazione specificano la configurazione generale delle unità nella sessione. I flag di accesso specificano il modo in cui l'applicazione userà le unità biometriche. È necessario specificare un flag di configurazione, ma è possibile combinare tale flag con qualsiasi flag di accesso.

Valore Significato
WINBIO_FLAG_DEFAULT
 Gruppo: configurazione

Le unità biometriche operano nel modo specificato durante l'installazione. È necessario usare questo valore quando il parametro PoolType è WINBIO_POOL_SYSTEM.
WINBIO_FLAG_BASIC
 Gruppo: configurazione

Le unità biometriche funzionano solo come dispositivi di acquisizione di base. Tutte le operazioni di elaborazione, corrispondenza e archiviazione vengono eseguite dai plug-in software.
WINBIO_FLAG_ADVANCED
 Gruppo: configurazione

Le unità biometriche usano funzionalità di elaborazione e archiviazione interne.
WINBIO_FLAG_RAW
 Gruppo: accesso

L'applicazione client acquisisce dati biometrici non elaborati usando WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE
 Gruppo: accesso

Il client esegue operazioni di controllo definite dal fornitore su un'unità biometrica chiamando WinBioControlUnitPrivileged.

[in, optional] UnitArray

Puntatore a una matrice di identificatori di unità biometrica da includere nella sessione. Puoi chiamare WinBioEnumBiometricUnits per enumerare le unità biometriche. Impostare questo valore su NULL se il parametro PoolType è WINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Valore che specifica il numero di elementi nella matrice a cui punta il parametro UnitArray . Impostare questo valore su zero se il parametro PoolType è WINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Valore che specifica i database da utilizzare dalla sessione. Se il parametro PoolType è WINBIO_POOL_PRIVATE, è necessario specificare il GUID di un database installato. Se il parametro PoolType non è WINBIO_POOL_PRIVATE, è possibile specificare uno dei valori comuni seguenti.

Valore Significato
WINBIO_DB_DEFAULT
 Ogni unità biometrica nel pool di sensori usa il database predefinito specificato nella configurazione predefinita dell'unità biometrica. È necessario specificare questo valore se il parametro PoolType è WINBIO_POOL_SYSTEM. Non è possibile usare questo valore se il parametro PoolType è WINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP
 È possibile specificare questo valore da usare per gli scenari prima di avviare Windows. In genere, il database fa parte del chip del sensore o fa parte del BIOS e può essere usato solo per la registrazione e l'eliminazione del modello.
WINBIO_DB_ONCHIP
 Il database si trova nel chip del sensore ed è disponibile per la registrazione e la corrispondenza.

[in] NotificationMethod

Specifica il modo in cui le notifiche di completamento per le operazioni asincrone in questa sessione biometrica devono essere recapitate all'applicazione client. Deve essere uno dei valori seguenti.

Valore Significato
WINBIO_ASYNC_NOTIFY_CALLBACK
 La sessione richiama la funzione di callback definita dall'applicazione.
WINBIO_ASYNC_NOTIFY_MESSAGE
 La sessione invia un messaggio di finestra alla coda dei messaggi dell'applicazione.

[in, optional] TargetWindow

Handle della finestra che riceverà gli avvisi di completamento. Questo valore viene ignorato a meno che il parametro NotificationMethod non sia impostato su WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Il codice del messaggio della finestra deve inviare il framework per indicare gli avvisi di completamento. Questo valore viene ignorato a meno che il parametro NotificationMethod non sia impostato su WINBIO_ASYNC_NOTIFY_MESSAGE. Il valore deve essere compreso nell'intervallo WM_APP(0x8000) per 0xBFFF.

Windows Biometric Framework imposta il valore LPARAM del messaggio sull'indirizzo della struttura WINBIO_ASYNC_RESULT che contiene i risultati dell'operazione. Devi chiamare WinBioFree per rilasciare la struttura dopo aver finito di usarla.

[in, optional] CallbackRoutine

Indirizzo della routine di callback da richiamare al termine dell'operazione tramite l'handle di sessione. Questo valore viene ignorato a meno che il parametro NotificationMethod non sia impostato su WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Indirizzo di un buffer fornito dal chiamante. Il buffer non viene modificato dal framework o dall'unità biometrica. Viene restituito nella struttura WINBIO_ASYNC_RESULT . L'applicazione può usare i dati per determinare quali azioni eseguire al ricevimento dell'avviso di completamento o per mantenere informazioni aggiuntive sull'operazione richiesta.

[in] AsynchronousOpen

Specifica se bloccare fino all'apertura della sessione del framework. Se si specifica FALSE , il processo viene bloccato. Se si specifica TRUE , la sessione viene aperta in modo asincrono.

Se si specifica FALSE per aprire la sessione del framework in modo sincrono, l'esito positivo o negativo viene restituito al chiamante direttamente da questa funzione nel valore restituito HRESULT . Se la sessione viene aperta correttamente, il primo evento di completamento asincrono ricevuto dall'applicazione sarà per un'operazione asincrona richiesta dopo l'apertura del framework.

Se si specifica TRUE per aprire la sessione del framework in modo asincrono, il primo avviso di completamento asincrono ricevuto sarà per l'apertura del framework. Se il parametro NotificationMethod è impostato su WINBIO_ASYNC_NOTIFY_CALLBACK, i risultati dell'operazione vengono recapitati alla struttura WINBIO_ASYNC_RESULT nella funzione di callback specificata dal parametro CallbackRoutine . Se il parametro NotificationMethod è impostato su WINBIO_ASYNC_NOTIFY_MESSAGE, i risultati dell'operazione vengono recapitati alla struttura WINBIO_ASYNC_RESULT a cui punta il campo LPARAM del messaggio della finestra.

[out, optional] SessionHandle

Se la funzione non riesce, questo parametro sarà NULL.

Se la sessione viene aperta in modo sincrono e completata, questo parametro conterrà un puntatore all'handle di sessione.

Se si specifica che la sessione viene aperta in modo asincrono, questo metodo restituisce immediatamente, l'handle di sessione sarà NULL ed è necessario esaminare la struttura WINBIO_ASYNC_RESULT per determinare se la sessione è stata aperta correttamente.

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 dei codici di errore comuni, vedere Valori HRESULT comuni.

Codice restituito Descrizione
E_OUTOFMEMORY
 Memoria insufficiente per creare la sessione biometrica.
E_INVALIDARG
 Se si imposta il metodo di notifica su WINBIO_ASYNC_NOTIFY_MESSAGE, il parametro TargetWindow non può essere NULL o HWND_BROADCAST e il parametro MessageCode non può essere zero (0).
E_POINTER
 È necessario impostare il parametro SessionHandle e il parametro AsynchronousOpen .

Se si imposta il metodo di notifica su WINBIO_ASYNC_NOTIFY_CALLBACK, è necessario specificare anche l'indirizzo di una funzione di callback nel parametro CallbackRoutine .
E_ACCESSDENIED
 Il parametro Flags contiene il WINBIO_FLAG_RAW o il flag di WINBIO_FLAG_MAINTENANCE e al chiamante non è stata concessa alcuna autorizzazione di accesso.
WINBIO_E_INVALID_UNIT
 Uno o più numeri di unità biometrica specificati nel parametro UnitArray non sono validi.
WINBIO_E_NOT_ACTIVE_CONSOLE
 L'applicazione client è in esecuzione in un client desktop remoto e tenta di aprire una sessione del pool di sistema.
WINBIO_E_SENSOR_UNAVAILABLE
 Il parametro PoolType è impostato su WINBIO_POOL_PRIVATE e uno o più sensori richiesti in tale pool non sono disponibili.
WINBIO_E_DISABLED
 I criteri amministrativi correnti impediscono l'uso dell'API Di Windows Biometric Framework.

Commenti

L'handle di sessione restituito dalla funzione WinBioAsyncOpenSession può essere usato per generare notifiche di completamento asincrone per una delle funzioni seguenti:

L'handle di sessione restituito da WinBioAsyncOpenSession non può essere usato con le funzioni seguenti: Queste funzioni, disponibili per la prima volta in Windows 7, hanno una firma di callback incompatibile e il loro uso nelle nuove applicazioni è sconsigliato. Gli sviluppatori che desiderano callback asincroni devono usare invece WinBioAsyncOpenSession con notificationMethod di WINBIO_ASYNC_NOTIFY_CALLBACK.

Il parametro AsynchronousOpen determina solo se l'operazione di apertura verrà bloccata. Questo parametro non ha alcun effetto sul comportamento di completamento delle chiamate successive che usano l'handle di sessione.

Se si imposta il parametro AsynchronousOpen su TRUE, questa funzione restituirà S_OK non appena ha eseguito una convalida iniziale degli argomenti. Eventuali errori rilevati oltre tale punto verranno segnalati al chiamante usando il metodo specificato dal parametro NotificationMethod . Ovvero, un valore restituito con esito positivo indica solo che i parametri WinBioAsyncOpenSession sono stati eseguiti correttamente e non che l'operazione di apertura è riuscita. Per determinare se l'operazione di apertura è riuscita, è necessario esaminare la struttura WINBIO_ASYNC_RESULT .

Requisiti

   
Client minimo supportato Windows 8 [solo app desktop]
Server minimo supportato Windows Server 2012 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione winbio.h (include Winbio.h)
Libreria Winbio.lib
DLL Winbio.dll

Vedi anche

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession