Funzione WinBioCaptureSampleWithCallback (winbio.h)
Acquisisce un campione biometrico in modo asincrono e restituisce i dati non elaborati in un record di informazioni biometriche (BIR). La funzione restituisce immediatamente al chiamante, acquisisce l'esempio in un thread separato e chiama in una funzione di callback definita dall'applicazione per aggiornare lo stato dell'operazione.
È consigliabile, a partire da Windows 8, non usare più questa funzione per avviare un'operazione asincrona. Eseguire invece le operazioni seguenti:
- Implementare una funzione PWINBIO_ASYNC_COMPLETION_CALLBACK per ricevere un avviso al termine dell'operazione.
- Chiamare la funzione WinBioAsyncOpenSession . Passare l'indirizzo del callback nel parametro CallbackRoutine . Passare WINBIO_ASYNC_NOTIFY_CALLBACK nel parametro NotificationMethod . Recuperare un handle di sessione asincrono.
- Usare l'handle di sessione asincrona per chiamare WinBioCaptureSample. Al termine dell'operazione, Windows Biometric Framework alloca e inizializza una struttura WINBIO_ASYNC_RESULT con i risultati e richiama il callback con un puntatore alla struttura dei risultati.
- Chiamare WinBioFree dall'implementazione del callback per rilasciare la struttura di WINBIO_ASYNC_RESULT al termine dell'uso.
Sintassi
HRESULT WinBioCaptureSampleWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIR_PURPOSE Purpose,
[in] WINBIO_BIR_DATA_FLAGS Flags,
[in] PWINBIO_CAPTURE_CALLBACK CaptureCallback,
[in, optional] PVOID CaptureCallbackContext
);
Parametri
[in] SessionHandle
Valore WINBIO_SESSION_HANDLE che identifica una sessione biometrica aperta.
[in] Purpose
Maschera WINBIO_BIR_PURPOSE bit che specifica l'uso previsto dell'esempio. Questo può essere un OR bit per bit dei valori seguenti:
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[in] Flags
Valore che specifica il tipo di elaborazione da applicare all'esempio acquisito. Questo può essere un OR bit per bit dei flag di sicurezza ed elaborazione seguenti:
- WINBIO_DATA_FLAG_PRIVACY
Crittografare l'esempio.
- WINBIO_DATA_FLAG_INTEGRITY
Firmare l'esempio o proteggerlo usando un codice di autenticazione dei messaggi (MAC).
- WINBIO_DATA_FLAG_SIGNED
Se questo flag e il WINBIO_DATA_FLAG_INTEGRITYflag vengono impostati, firmare l'esempio. Se questo flag non è impostato, ma il flag di WINBIO_DATA_FLAG_INTEGRITY è impostato, calcolare un MAC.
- WINBIO_DATA_FLAG_RAW
Restituisce l'esempio esattamente come è stato acquisito dal sensore.
- WINBIO_DATA_FLAG_INTERMEDIATE
Restituisce l'esempio dopo che è stato pulito e filtrato.
- WINBIO_DATA_FLAG_PROCESSED
Restituire l'esempio dopo che è pronto per essere usato per lo scopo specificato dal parametro Scopo .
[in] CaptureCallback
Indirizzo di una funzione di callback che verrà chiamata dalla funzione WinBioCaptureSampleWithCallback quando l'operazione di acquisizione ha esito positivo o ha esito negativo. È necessario creare il callback.
[in, optional] CaptureCallbackContext
Indirizzo di una struttura di dati definita dall'applicazione passata alla funzione di callback nel parametro CaptureCallbackContext . Questa struttura può contenere tutti i dati che la funzione di callback personalizzata è progettata per gestire.
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 |
|---|---|
|
Il chiamante non dispone dell'autorizzazione per acquisire esempi non elaborati oppure la sessione non è stata aperta usando il flag di WINBIO_FLAG_RAW . |
|
L'handle di sessione non è valido. |
|
L'unità biometrica non supporta l'operazione richiesta. |
|
I puntatori UnitId, Sample, SampleSize e RejectDetail non possono essere NULL. |
|
Impossibile completare l'operazione perché l'unità biometrica è attualmente usata per una transazione di registrazione (solo pool di sistema). |
Commenti
La funzione WinBioCaptureSampleWithCallback acquisisce esempi in modo asincrono. Per chiamare correttamente questa funzione, l'handle di sessione deve essere stato aperto specificando WINBIO_FLAG_RAW. Solo gli account Administrators e Local System dispongono dei privilegi necessari.
Le combinazioni valide dei parametri Scopo e Flag dipendono dalle funzionalità dell'unità biometrica usata. Consultare la documentazione del sensore fornitore per determinare quali combinazioni sono supportate e come influiscono sui dati acquisiti.
I chiamanti sono responsabili del rilascio della struttura WINBIO_BIR restituita dal parametro Sample .
La routine di callback deve avere la firma seguente:
VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);
Esempio
Nell'esempio di codice seguente viene acquisito un esempio in modo asincrono chiamando WinBioCaptureSampleWithCallback e passando un puntatore a una funzione di callback personalizzata. Viene visualizzata anche la funzione callback CaptureSampleCallback. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_RAW, // Raw access
NULL, // Array of biometric unit IDs
0, // Count of biometric unit IDs
WINBIO_DB_DEFAULT, // Default database
&sessionHandle // [out] Session handle
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Capture a biometric sample asynchronously.
wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
hr = WinBioCaptureSampleWithCallback(
sessionHandle, // Open session handle
WINBIO_NO_PURPOSE_AVAILABLE, // Intended use of the sample
WINBIO_DATA_FLAG_RAW, // Sample format
CaptureSampleCallback, // Callback function
NULL // Optional context
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Swipe the sensor ...\n");
// Cancel the capture process if the bCancel flag is set.
if (bCancel)
{
wprintf_s(L"\n Starting CANCEL timer...");
Sleep( 7000 );
wprintf_s(L"\n Calling WinBioCancel\n");
hr = WinBioCancel( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
// Wait for the asynchronous capture process to complete
// or be canceled.
hr = WinBioWait( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
}
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
)
{
UNREFERENCED_PARAMETER(CaptureCallbackContext);
wprintf_s(L"\n CaptureSampleCallback executing");
wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);
if (FAILED(OperationStatus))
{
if (OperationStatus == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
}
else
{
wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
}
goto e_Exit;
}
wprintf_s(L"\n Captured %d bytes.\n", SampleSize);
e_Exit:
if (Sample != NULL)
{
WinBioFree(Sample);
Sample = NULL;
}
}
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 |