Функция WinBioCaptureSample (winbio.h)

Статья
03/08/2023

Захватывает биометрическую выборку и заполняет биометрическую информационную запись (BIR) необработанными или обработанными данными.

Синтаксис

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
);

Параметры

[in] SessionHandle

Значение WINBIO_SESSION_HANDLE , определяющее открытый биометрический сеанс. Откройте синхронный дескриптор сеанса, вызвав WinBioOpenSession. Откройте асинхронный дескриптор сеанса, вызвав WinBioAsyncOpenSession.

[in] Purpose

Битовая маска WINBIO_BIR_PURPOSE, указывающая предполагаемое использование образца. Это может быть побитовое ИЛИ следующих значений:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Значение типа , указывающее тип обработки, применяемой к захваченной выборке. Это может быть побитовое ИЛИ следующих флагов уровня безопасности и обработки:

WINBIO_DATA_FLAG_PRIVACY

Зашифруйте пример.

WINBIO_DATA_FLAG_INTEGRITY

Подпишите пример или защитите его с помощью кода проверки подлинности сообщения (MAC)

WINBIO_DATA_FLAG_SIGNED

Если этот флаг и флаг WINBIO_DATA_FLAG_INTEGRITY установлены, подпишите пример. Если этот флаг не задан, но установлен флаг WINBIO_DATA_FLAG_INTEGRITY, вычислить MAC-файл.

WINBIO_DATA_FLAG_RAW

Возвращает образец точно так, как он был захвачен датчиком.

WINBIO_DATA_FLAG_INTERMEDIATE

Верните образец после его очистки и фильтрации.

WINBIO_DATA_FLAG_PROCESSED

Верните образец после того, как он будет готов к использованию для целей, указанных параметром Purpose.

[out, optional] UnitId

Указатель на WINBIO_UNIT_ID значение, содержащее идентификатор биометрической единицы, создающей образец.

Sample

Адрес переменной, получающей указатель на WINBIO_BIR структуру, содержащую образец. После завершения использования структуры необходимо передать указатель на WinBioFree , чтобы освободить память, выделенную для примера.

[out, optional] SampleSize

Указатель на SIZE_T значение, содержащее размер в байтах структуры WINBIO_BIR , возвращаемой в параметре Sample .

[out, optional] RejectDetail

Указатель на значение WINBIO_REJECT_DETAIL , содержащее дополнительные сведения о невозможности захвата биометрической выборки. Если запись выполнена успешно, для этого параметра устанавливается нулевое значение. Для захвата отпечатков пальцев определяются следующие значения:

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

Возвращаемое значение

Если функция завершается успешно, она возвращает S_OK. Если функция завершается сбоем, она возвращает значение HRESULT , указывающее на ошибку. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице. Список распространенных кодов ошибок см. в разделе Общие значения HRESULT.

Код возврата	Описание
E_ACCESSDENIED	Вызывающий объект не имеет разрешения на запись необработанных выборок или сеанс не был открыт с помощью флага WINBIO_FLAG_RAW .
E_HANDLE	Недопустимый дескриптор сеанса.
E_NOTIMPL	Биометрический блок не поддерживает запрошенную операцию.
E_POINTER	Указатели UnitId, Sample, SampleSize и RejectDetail не могут иметь значение NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	Не удалось завершить операцию, так как биометрическая единица в настоящее время используется для транзакции регистрации (только системный пул).
WINBIO_E_INVALID_OPERATION	Не удалось завершить операцию, так как в пуле датчиков присутствует защищенный датчик.

Чтобы успешно вызвать эту функцию, необходимо открыть дескриптор сеанса, указав WINBIO_FLAG_RAW в параметре Flags функций WinBioOpenSession или WinBioAsyncOpenSession . В настоящее время только приложения, работающие под учетными записями "Администраторы" и "Локальная система", имеют необходимые привилегии.

Допустимые сочетания параметров Назначение и Флаги зависят от возможностей используемой биометрической единицы. Обратитесь к документации по датчику поставщика, чтобы определить, какие сочетания допустимых значений назначения и флагов поддерживаются и как они влияют на захваченные данные. После завершения использования примера приложение должно вызвать WinBioFree , чтобы освободить память, выделенную для него функцией WinBioCaptureSample .

Чтобы использовать WinBioCaptureSample синхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioOpenSession. Функция блокируется до тех пор, пока не будет записан пример или не возникнет ошибка. Вызовы WinBioCaptureSample с использованием системного пула будут блокироваться, пока вызывающее приложение не получит фокус окна и пользователь не предоставит пример одному из датчиков в пуле. Если датчик, выбранный пользователем, уже используется для транзакции регистрации, функция завершается сбоем и возвращает WINBIO_E_ENROLLMENT_IN_PROGRESS.

Чтобы использовать WinBioCaptureSample асинхронно, вызовите функцию с дескриптором сеанса, созданным путем вызова WinBioAsyncOpenSession. Платформа выделяет структуру WINBIO_ASYNC_RESULT и использует ее для возврата сведений об успешном или неудачном выполнении операции. Если операция записи выполнена успешно, платформа возвращает сведения о образце во вложенной структуре CaptureSample . Если операция не выполнена, платформа возвращает сведения об ошибке. Структура WINBIO_ASYNC_RESULT возвращается в обратный вызов приложения или в очередь сообщений приложения в зависимости от значения, заданного в параметре NotificationMethod функции WinBioAsyncOpenSession :

Если вы решили получать уведомления о завершении с помощью обратного вызова, необходимо реализовать функцию PWINBIO_ASYNC_COMPLETION_CALLBACK и задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_CALLBACK.
Если вы решили получать уведомления о завершении с помощью очереди сообщений приложения, необходимо задать для параметра NotificationMethodзначение WINBIO_ASYNC_NOTIFY_MESSAGE. Платформа возвращает указатель WINBIO_ASYNC_RESULT на поле LPARAM сообщения окна.

Чтобы предотвратить утечку памяти, необходимо вызвать WinBioFree , чтобы освободить структуру WINBIO_ASYNC_RESULT после завершения ее использования.

Windows 7: Эту операцию можно выполнить асинхронно с помощью функции WinBioCaptureSampleWithCallback . Функция проверяет входные аргументы и возвращает немедленно. Если входные аргументы недопустимы, функция возвращает код ошибки. В противном случае платформа запускает операцию в другом потоке. Когда асинхронная операция завершается или возникает ошибка, платформа отправляет результаты в функцию PWINBIO_CAPTURE_CALLBACK , реализованную приложением.

Примеры

Следующая функция вызывает WinBioCaptureSample для получения биометрической выборки от пользователя. Ссылка на статическую библиотеку Winbio.lib и включение следующих файлов заголовков:

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;
}

Требования


Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	winbio.h (включая Winbio.h)
Библиотека	Winbio.lib
DLL	Winbio.dll

См. также раздел

WinBioCaptureSampleWithCallback

Поделиться через