PIBIO_SENSOR_FINISH_CAPTURE_FNコールバック関数 (winbio_adapter.h)
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 生体認証フレームワークによって認識されます。
| リターン コード | 説明 |
|---|---|
|
サンプルをキャプチャできませんでした。 このエラー コードを返す場合は、問題の性質を示す RejectDetail パラメーターの値も指定する必要があります。 |
|
センサー ドライバーは 、ERROR_CANCELLED または ERROR_OPERATION_ABORTEDを返しました。 |
|
デバイスエラーが発生しました。 |
|
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 を含む) |