PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN回呼函式 (winbio_adapter.h)

發行項
03/03/2024

由感測器配接器實作的 SensorAdapterPushDataToEngine 函式呼叫，以通知引擎配接器接受原始生物特徵辨識範例並擷取功能集。功能集可用於比對或註冊。

語法

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

參數

[in, out] Pipeline

與執行作業之生物特徵辨識單位相關聯的 WINBIO_PIPELINE 結構的指標。

[in] SampleBuffer

包含要處理之生物特徵辨識樣本的WINBIO_BIR 結構的指標。

[in] SampleSize

包含 SampleBuffer 參數中傳回之WINBIO_BIR結構大小的SIZE_T值。

[in] Purpose

指定樣本用途的 WINBIO_BIR_PURPOSE 位掩碼。 WINBIO_BIR_PURPOSE 結構會指定要使用擷取數據的用途，並 () 應如何優化。這可以是下列值的位 OR ：

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] 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 值，以指出錯誤。

傳回碼	Description
E_INVALIDARG	SampleSize 自變數不可為零。 Purpose 自變數必須是參數描述中所列值的位 OR。
E_POINTER	Pipeline、SampleBuffer 和 RejectDetail 自變數不可為 NULL。
E_OUTOFMEMORY	因為記憶體不足，所以無法完成作業。
WINBIO_E_BAD_CAPTURE	無法處理數據以建立必要的功能集。 RejectDetail 包含有關失敗的其他資訊。

備註

呼叫此函式所建立的功能集會在函式傳回之後保留在生物特徵辨識單位管線中。它會取代任何先前的功能集。

SensorAdapterPushDataToEngine 函式的感測器配接器實作應該使用 Winbio_adapter.h) 中定義的下列包裝函式函式 (來呼叫 EngineAdapterAcceptSampleData：

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

在 SampleBuffer 參數中傳遞的WINBIO_BIR結構是感測器配接器的屬性。因為感測器配接器控制 WINBIO_BIR 物件的存留期， 所以 EngineAdapterAcceptSampleData 函式不得嘗試解除分配結構或儲存其指標。藉由不儲存指標，您可以防止引擎配接器的其他部分在 EngineAdapterAcceptSampleData 函式傳回之後嘗試使用WINBIO_BIR結構。

如果WINBIO_BIR結構之 StandardDataBlock 成員的 Offset 字段大於零 (表示 BIR 包含標準數據格式) 生物特徵辨識範例，則 HeaderBlock 成員的 BiometricDataFormat 字段必須設定如下：

[ 擁有者] 欄位必須 WINBIO_ ANSI_381_FORMAT_OWNER。
[ 類型] 欄位必須 WINBIO_ANSI_381_FORMAT_TYPE。

這是 Windows 生物特徵辨識架構唯一支援的標準數據格式。

Windows 生物特徵辨識架構也假設 HeaderBlock 成員 (WINBIO_BIR_HEADER 結構) 包含感測器配接器用來擷取樣本的 DataFlags 和 Purpose 值。

指紋感測器會處理指紋樣本，並拒絕引擎配接器中的錯誤撥動，也應該針對 WINBIO_BIR_PURPOSE使用有效的值。

範例

下列虛擬程式代碼顯示此函式的一個可能實作。此範例不會編譯。您必須調整它以符合您的用途。

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline)     ||
        !ARGUMENT_PRESENT(SampleBuffer) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    return hr;
}

規格需求

需求	值
最低支援的用戶端	Windows 7 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 R2 [僅限桌面應用程式]
目標平台	Windows
標頭	winbio_adapter.h (包含 Winbio_adapter.h)

另請參閱

EngineAdapterExportEngineData

外掛程式函式

共用方式為

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN回呼函式 (winbio_adapter.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源