PIBIO_SENSOR_FINISH_CAPTURE_FNコールバック関数 (winbio_adapter.h)

[アーティクル]
03/03/2024

SensorAdapterStartCapture 関数によって開始されたキャプチャ操作の完了を待機するために、Windows 生体認証フレームワークによって呼び出されます。

構文

PIBIO_SENSOR_FINISH_CAPTURE_FN PibioSensorFinishCaptureFn;

HRESULT PibioSensorFinishCaptureFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

パラメーター

[in, out] Pipeline

操作を実行する生体認証ユニットに関連付けられている WINBIO_PIPELINE 構造体へのポインター。

[out] RejectDetail

生体認証 サンプルのキャプチャ 失敗に関する追加情報を受け取るWINBIO_REJECT_DETAIL値へのポインター。操作が成功した場合、このパラメーターは 0 に設定されます。指紋サンプルには、次の値が定義されています。

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 値を返します。次の値は、Windows 生体認証フレームワークによって認識されます。

リターンコード	説明
WINBIO_E_BAD_CAPTURE	サンプルをキャプチャできませんでした。このエラーコードを返す場合は、問題の性質を示す RejectDetail パラメーターの値も指定する必要があります。
WINBIO_E_CAPTURE_CANCELED	センサードライバーは、ERROR_CANCELLED または ERROR_OPERATION_ABORTEDを返しました。
WINBIO_E_DEVICE_FAILURE	デバイスエラーが発生しました。
WINBIO_E_INVALID_DEVICE_STATE	Pipeline 引数が指すWINBIO_PIPELINE構造体の SensorContext メンバーが NULL であるか、SensorHandle メンバーが INVALID_HANDLE_VALUE に設定されています。

注釈

Windows 生体認証フレームワークは、 SensorAdapterStartCapture を正常に呼び出すか、 SensorAdapterCancel を呼び出した後にこの関数を呼び出します。 SensorAdapterStartCapture の呼び出しが失敗した場合、この関数は呼び出されません。

この関数の実装が返されると、パイプライン内のデータは、 SensorAdapterPushDataToEngine や SensorAdapterExportSensorData などの関数に対する後続の呼び出しの準備が整う必要があります。

これは、センサーの I/O 操作が成功、失敗、または取り消された後にのみを返すブロック関数です。通常は、センサーアダプターコンテキストの OVERLAPPED 構造体を GetOverlappedResult 関数に渡すことによって、この関数ブロックを作成します。 SensorAdapterFinishCapture が返されるときに、OVERLAPPED 構造体の hEvent ハンドルを通知する必要があります。 GetOverlappedResult 関数は、センサー I/O 操作の終了を検出すると、このハンドルを自動的に設定します。アダプターが他のメカニズムを使用して I/O 完了を検出する場合は、イベントを自分で通知する必要があります。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterFinishCapture
//
// Purpose:
//      Waits for the completion of a capture operation initiated by the 
//      SensorAdapterStartCapture function.
//      
// Parameters:
//      Pipeline     -  Pointer to a WINBIO_PIPELINE structure associated with 
//                      the biometric unit.
//      RejectDetail -  Pointer to a WINBIO_REJECT_DETAIL value that receives 
//                      additional information about the failure to capture a 
//                      biometric sample.
//
static HRESULT
WINAPI
SensorAdapterFinishCapture(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    WINBIO_SENSOR_STATUS sensorStatus = WINBIO_SENSOR_FAILURE;
    WINBIO_CAPTURE_PARAMETERS captureParameters = {0};
    BOOL result = TRUE;
    DWORD bytesReturned = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_SENSOR_CONTEXT sensorContext = 
             (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // Verify the state of the pipeline.
    if (sensorContext == NULL || 
        Pipeline->SensorHandle == INVALID_HANDLE_VALUE)
    {
        return WINBIO_E_INVALID_DEVICE_STATE;
    }

    // Initialize the RejectDetail argument.
    *RejectDetail = 0;

    // Wait for I/O completion. This sample assumes that the I/O operation was 
    // started using the code example shown in the SensorAdapterStartCapture
    // documentation.
    SetLastError(ERROR_SUCCESS);

    result = GetOverlappedResult(
                Pipeline->SensorHandle,
                &sensorContext->Overlapped,
                &bytesReturned,
                TRUE
                );
    if (!result)
    {
        // There was an I/O error.
        return _AdapterGetHresultFromWin32(GetLastError());
    }

    if (bytesReturned == sizeof (DWORD))
    {
        // The buffer is not large enough.  This can happen if a device needs a 
        // bigger buffer depending on the purpose. Allocate a larger buffer and 
        // force the caller to reissue their I/O request.
        DWORD allocationSize = sensorContext->CaptureBuffer->PayloadSize;

        // Allocate at least the minimum buffer size needed to retrieve the 
        // payload structure.
        if (allocationSize < sizeof(WINBIO_CAPTURE_DATA))
        {
            allocationSize = sizeof(WINBIO_CAPTURE_DATA);
        }

        // Free the old buffer and allocate a new one.
        _AdapterRelease(sensorContext->CaptureBuffer);
        sensorContext->CaptureBuffer = NULL;

        sensorContext->CaptureBuffer = 
            (PWINBIO_CAPTURE_DATA)_AdapterAlloc(allocationSize);
        if (sensorContext->CaptureBuffer == NULL)
        {
            sensorContext->CaptureBufferSize = 0;
            return E_OUTOFMEMORY;
        }
        sensorContext->CaptureBufferSize = allocationSize;
        return WINBIO_E_BAD_CAPTURE;
    }

    // Normalize the status value before sending it back to the biometric service.
    if (sensorContext->CaptureBuffer != NULL &&
        sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA))
    {
        switch (sensorContext->CaptureBuffer->SensorStatus)
        {
            case WINBIO_SENSOR_ACCEPT:
                // The capture was acceptable.
                break;

            case WINBIO_SENSOR_REJECT:
                // The capture was not acceptable. Overwrite the WinBioHresult value
                // in case it has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_BAD_CAPTURE;
                break;

            case WINBIO_SENSOR_BUSY:
                // The device is busy. Reset the WinBioHresult value in case it 
                // has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_DEVICE_BUSY;
                break;

            case WINBIO_SENSOR_READY:
            case WINBIO_SENSOR_NOT_CALIBRATED:
            case WINBIO_SENSOR_FAILURE:
            default:
                // There has been a device failure. Reset the WinBioHresult value
                // in case it has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_INVALID_DEVICE_STATE;
                break;
        }

        *RejectDetail = sensorContext->CaptureBuffer->RejectDetail;
        hr = sensorContext->CaptureBuffer->WinBioHresult;
    }
    else
    {
        // The buffer is not large enough or the buffer pointer is NULL.
        hr = WINBIO_E_INVALID_DEVICE_STATE;
    }
    return hr;
}

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbio_adapter.h (Winbio_adapter.h を含む)