Funzione WinBioCaptureSample (winbio.h)

Articolo
03/08/2023

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
E_ACCESSDENIED	Il chiamante non dispone dell'autorizzazione per acquisire esempi non elaborati oppure la sessione non è stata aperta usando il flag di WINBIO_FLAG_RAW .
E_HANDLE	L'handle di sessione non è valido.
E_NOTIMPL	L'unità biometrica non supporta l'operazione richiesta.
E_POINTER	I puntatori UnitId, Sample, SampleSize e RejectDetail non possono essere NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	Impossibile completare l'operazione perché l'unità biometrica è attualmente usata per una transazione di registrazione (solo pool di sistema).
WINBIO_E_INVALID_OPERATION	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.

Per evitare perdite di memoria, è necessario chiamare WinBioFree per rilasciare la struttura WINBIO_ASYNC_RESULT dopo aver completato l'uso.

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

Vedi anche

WinBioCaptureSampleWithCallback

Condividi tramite