PIBIO_SENSOR_FINISH_CAPTURE_FN

SensorAdapterStartCapture 関数によって開始されたキャプチャ操作の完了を待機するために、Windows Biometric Framework から呼び出されます。

関数が成功した場合は S_OK を返します。関数が失敗した場合は、エラーを示す HRESULT 値を返します。Windows Biometric Framework では次の値が認識されます。

Windows Biometric Framework は、SensorAdapterStartCapture の呼び出しに成功した後、または SensorAdapterCancel を呼び出すときに、この関数を呼び出します。SensorAdapterStartCapture の呼び出しが失敗した場合、この関数は呼び出されません。

この関数の実装から制御が戻る時点では、パイプライン内のデータは SensorAdapterPushDataToEngine や SensorAdapterExportSensorData などの関数を後続で呼び出せる状態になっている必要があります。

これはブロッキング関数であり、センサーの I/O 操作が成功、失敗、またはキャンセルされた後にのみ制御を返す必要があります。通常は、センサー アダプター コンテキスト内の OVERLAPPED 構造体を GetOverlappedResult 関数に渡すことで、この関数をブロックさせます。SensorAdapterFinishCapture から制御が戻るときには、OVERLAPPED 構造体の hEvent ハンドルがシグナル状態になっている必要があります。GetOverlappedResult 関数は、センサーの I/O 操作の終了を検出すると、このハンドルを自動的に設定します。アダプターが I/O の完了を検出するために別の仕組みを使用している場合は、自分でイベントをシグナル状態にする必要があります。

例

次の擬似コードは、この関数の実装方法の一例を示しています。この例はそのままではコンパイルできません。目的に合わせて調整する必要があります。

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterFinishCapture
//
// 目的:
//      SensorAdapterStartCapture 関数によって開始されたキャプチャ操作の
//      完了を待機します。
//      
// パラメーター:
//      Pipeline     -  バイオメトリック ユニットに関連付けられた
//                      WINBIO_PIPELINE 構造体へのポインター。
//      RejectDetail -  バイオメトリック サンプルのキャプチャに失敗した
//                      理由に関する追加情報を受け取る
//                      WINBIO_REJECT_DETAIL 値へのポインター。
//
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;

    // ポインター引数が NULL でないことを確認します。
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // パイプラインからコンテキストを取得します。
    PWINBIO_SENSOR_CONTEXT sensorContext = 
             (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // パイプラインの状態を確認します。
    if (sensorContext == NULL || 
        Pipeline->SensorHandle == INVALID_HANDLE_VALUE)
    {
        return WINBIO_E_INVALID_DEVICE_STATE;
    }

    // RejectDetail 引数を初期化します。
    *RejectDetail = 0;

    // I/O の完了を待機します。このサンプルでは、I/O 操作が
    // SensorAdapterStartCapture のドキュメントに示されているコード例を
    // 使用して開始されていることを前提としています。
    SetLastError(ERROR_SUCCESS);

    result = GetOverlappedResult(
                Pipeline->SensorHandle,
                &sensorContext->Overlapped,
                &bytesReturned,
                TRUE
                );
    if (!result)
    {
        // I/O エラーが発生しました。
        return _AdapterGetHresultFromWin32(GetLastError());
    }

    if (bytesReturned == sizeof (DWORD))
    {
        // バッファーのサイズが不足しています。これは、用途に応じてデバイスが
        // より大きなバッファーを必要とする場合に発生します。より大きな
        // バッファーを割り当て、呼び出し元に I/O 要求を再発行させます。
        DWORD allocationSize = sensorContext->CaptureBuffer->PayloadSize;

        // 少なくとも、ペイロード構造体の取得に必要な最小バッファー サイズを
        // 割り当てます。
        if (allocationSize < sizeof(WINBIO_CAPTURE_DATA))
        {
            allocationSize = sizeof(WINBIO_CAPTURE_DATA);
        }

        // 古いバッファーを解放し、新しいバッファーを割り当てます。
        _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;
    }

    // バイオメトリック サービスに返す前に、ステータス値を正規化します。
    if (sensorContext->CaptureBuffer != NULL &&
        sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA))
    {
        switch (sensorContext->CaptureBuffer->SensorStatus)
        {
            case WINBIO_SENSOR_ACCEPT:
                // キャプチャは受け入れ可能でした。
                break;

            case WINBIO_SENSOR_REJECT:
                // キャプチャは受け入れられませんでした。適切に設定されていない場合に
                // 備えて、WinBioHresult 値を上書きします。
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_BAD_CAPTURE;
                break;

            case WINBIO_SENSOR_BUSY:
                // デバイスがビジーです。適切に設定されていない場合に備えて、
                // WinBioHresult 値をリセットします。
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_DEVICE_BUSY;
                break;

            case WINBIO_SENSOR_READY:
            case WINBIO_SENSOR_NOT_CALIBRATED:
            case WINBIO_SENSOR_FAILURE:
            default:
                // デバイス エラーが発生しました。適切に設定されていない場合に備えて、
                // WinBioHresult 値をリセットします。
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_INVALID_DEVICE_STATE;
                break;
        }

        *RejectDetail = sensorContext->CaptureBuffer->RejectDetail;
        hr = sensorContext->CaptureBuffer->WinBioHresult;
    }
    else
    {
        // バッファーのサイズが不足しているか、バッファー ポインターが NULL です。
        hr = WINBIO_E_INVALID_DEVICE_STATE;
    }
    return hr;
}