Funzione WinBioCaptureSample (winbio.h)
Acquisisce un campione biometrico e riempie un record di informazioni biometriche (BIR) con i dati non elaborati o elaborati.
Sintassi
HRESULT WinBioCaptureSample(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIR_PURPOSE Purpose,
[in] WINBIO_BIR_DATA_FLAGS Flags,
[out, optional] WINBIO_UNIT_ID *UnitId,
PWINBIO_BIR *Sample,
[out, optional] SIZE_T *SampleSize,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
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] 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 flag di WINBIO_DATA_FLAG_INTEGRITY 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.
[out, optional] UnitId
Puntatore a un valore WINBIO_UNIT_ID contenente l'ID dell'unità biometrica che ha generato l'esempio.
Sample
Indirizzo di una variabile che riceve un puntatore a una struttura WINBIO_BIR contenente l'esempio. Al termine dell'uso della struttura, è necessario passare il puntatore a WinBioFree per rilasciare la memoria allocata per l'esempio.
[out, optional] SampleSize
Puntatore a un valore SIZE_T che contiene le dimensioni, in byte , della struttura WINBIO_BIR restituita nel parametro Sample .
[out, optional] RejectDetail
Puntatore a un valore WINBIO_REJECT_DETAIL contenente informazioni aggiuntive sull'errore di acquisizione di un campione biometrico. Se l'acquisizione ha avuto esito positivo, questo parametro è impostato su zero. I valori seguenti sono definiti per l'acquisizione delle impronte digitali:
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
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). |
|
Impossibile completare l'operazione perché un sensore sicuro è presente nel pool di sensori. |
Commenti
Per chiamare correttamente questa funzione, è necessario aprire l'handle di sessione specificando WINBIO_FLAG_RAW nel parametro Flags delle funzioni WinBioOpenSession o WinBioAsyncOpenSession. Attualmente, solo le applicazioni in esecuzione negli account Administrators e Local System hanno i privilegi necessari.
Le combinazioni valide dei parametri Scopo e Flag dipendono dalle funzionalità dell'unità biometrica usata. Consultare la documentazione del sensore del fornitore per determinare quali combinazioni di valori di scopo e flag validi sono supportati e come influiscono sui dati acquisiti. Al termine dell'uso dell'esempio, l'applicazione deve chiamare WinBioFree per rilasciare la memoria allocata dalla funzione WinBioCaptureSample .
Per usare WinBioCaptureSample in modo sincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioOpenSession. La funzione blocca fino a quando non viene acquisito un esempio o viene rilevato un errore. Le chiamate a WinBioCaptureSample usando il pool di sistema bloccano fino a quando l'applicazione chiamante ha lo stato attivo della finestra e l'utente fornisce un esempio a uno dei sensori nel pool. Se il sensore scelto dall'utente viene già usato per una transazione di registrazione, la funzione ha esito negativo e restituisce WINBIO_E_ENROLLMENT_IN_PROGRESS.
Per usare WinBioCaptureSample 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. Se l'operazione di acquisizione ha esito positivo, il framework restituisce informazioni sull'esempio in una struttura CaptureSample annidata. Se l'operazione ha esito negativo, il framework restituisce informazioni sull'errore. La struttura WINBIO_ASYNC_RESULT viene restituita al callback dell'applicazione o alla coda dei 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.
Windows 7: È possibile eseguire questa operazione in modo asincrono usando la funzione WinBioCaptureSampleWithCallback . La funzione verifica gli argomenti di input e restituisce immediatamente. Se gli argomenti di input non sono validi, la funzione restituisce un codice di errore. In caso contrario, il framework avvia l'operazione in un altro thread. Al termine dell'operazione asincrona o si verifica un errore, il framework invia i risultati alla funzione PWINBIO_CAPTURE_CALLBACK implementata dall'applicazione.
Esempio
La funzione seguente chiama WinBioCaptureSample per acquisire un campione biometrico da un utente. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT CaptureSample()
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
PWINBIO_BIR sample = NULL;
SIZE_T sampleSize = 0;
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_RAW, // Access: Capture raw data
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.
wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
hr = WinBioCaptureSample(
sessionHandle,
WINBIO_NO_PURPOSE_AVAILABLE,
WINBIO_DATA_FLAG_RAW,
&unitId,
&sample,
&sampleSize,
&rejectDetail
);
if (FAILED(hr))
{
if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
}
else
{
wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
wprintf_s(L"\n Captured %d bytes.\n", sampleSize);
e_Exit:
if (sample != NULL)
{
WinBioFree(sample);
sample = NULL;
}
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
Requisiti
| 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 |