fungsi panggilan balik PIBIO_SENSOR_START_CAPTURE_FN (winbio_adapter.h)
Dipanggil oleh Windows Biometric Framework untuk memulai pengambilan biometrik asinkron.
Sintaks
PIBIO_SENSOR_START_CAPTURE_FN PibioSensorStartCaptureFn;
HRESULT PibioSensorStartCaptureFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] WINBIO_BIR_PURPOSE Purpose,
[out] LPOVERLAPPED *Overlapped
)
{...}
Parameter
[in, out] Pipeline
Arahkan ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.
[in] Purpose
Bitmask WINBIO_BIR_PURPOSE yang menentukan penggunaan sampel yang dimaksudkan. Ini bisa menjadi bitwise ATAU dari nilai berikut:
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
Beberapa sensor memiliki kemampuan untuk menangkap informasi biometrik pada beberapa resolusi. Jika parameter Tujuan menentukan lebih dari satu bendera, adaptor Anda harus menggunakan bendera yang mewakili resolusi tertinggi untuk menentukan resolusi operasi pengambilan.
[out] Overlapped
Alamat variabel yang menerima penunjuk ke struktur TUMPANG TINDIH yang melacak status operasi penangkapan asinkron. Struktur ini dibuat dan dikelola oleh adaptor sensor tetapi digunakan oleh Windows Biometric Framework untuk sinkronisasi. Untuk informasi lebih lanjut, lihat bagian Keterangan.
Mengembalikan nilai
Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi mengembalikan nilai HRESULT yang menunjukkan kesalahan. Nilai berikut akan dikenali oleh Windows Biometric Framework.
| Menampilkan kode | Deskripsi |
|---|---|
|
Argumen pointer wajib adalah NULL. |
|
Parameter Tujuan tidak valid. |
|
Memori tidak cukup untuk melakukan operasi. |
|
Perangkat belum siap untuk mengambil data. |
|
Terjadi kegagalan perangkat. |
|
Anggota SensorContext dari struktur WINBIO_PIPELINE yang diacu oleh argumen Alur adalah NULL atau anggota SensorHandle diatur ke INVALID_HANDLE_VALUE. |
Keterangan
Fungsi ini tidak memblokir. Jika adaptor mengeluarkan beberapa perintah ke sensor untuk mempersiapkan operasi pengambilan, semua kecuali perintah akhir dapat sinkron. Perintah akhir, yang dikeluarkan segera sebelum SensorAdapterStartCapture mengembalikan kontrol ke Windows Biometric Framework, harus asinkron dan harus menggunakan I/O yang tumpang tindih.
Untuk menggunakan I/O yang tumpang tindih, mulailah dengan menambahkan objek TUMPANG TINDIH ke definisi struktur konteks adaptor sensor privat. Struktur ini tersedia untuk adaptor melalui bidang SensorContext dari objek WINBIO_PIPELINE .
Saat menerapkan SensorAdapterAttach, Anda harus melakukan tindakan berikut untuk menginisialisasi struktur YANG TUMPANG TINDIH :
- Bersihkan struktur YANG TUMPANG TINDIH dengan memanggil fungsi ZeroMemory .
- Buat objek peristiwa reset manual dengan menggunakan fungsi CreateEvent . Sangat penting bahwa objek peristiwa menjadi manual daripada reset otomatis. Penggunaan peristiwa reset otomatis dalam I/O yang tumpang tindih dapat menyebabkan kurangnya respons yang tidak dapat dipulihkan dalam operasi pemrosesan I/O.
- Simpan handel peristiwa ini di anggota hEvent dari struktur TUMPANG TINDIH .
Windows Biometric Framework menggunakan objek TUMPANG TINDIH saat memanggil fungsi sistem operasi seperti GetOverlappedResult dan WaitForMultipleObjects untuk menentukan kapan operasi penangkapan telah selesai.
Handel peristiwa dalam struktur TUMPANG TINDIH harus dalam keadaan tidak diberi sinyal saat SensorAdapterStartCapture kembali. Memanggil DeviceIoControl untuk memulai operasi I/O yang tumpang tindih secara otomatis mengatur ulang peristiwa. Jika adaptor Anda menggunakan beberapa mekanisme lain untuk memulai operasi I/O, Anda harus mengatur ulang peristiwa sendiri.
Windows Biometric Framework menjamin bahwa hanya satu operasi I/O asinkron yang luar biasa kapan saja untuk setiap unit biometrik. Akibatnya, adaptor sensor hanya membutuhkan satu struktur TUMPANG TINDIH untuk setiap alur pemrosesan.
Windows Biometric Framework membuka dan menutup handel adaptor sensor dan bertanggung jawab untuk memastikan bahwa handel telah dikonfigurasi untuk I/O yang tumpang tindih.
Contoh
Pseudocode berikut menunjukkan satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Anda harus menyesuaikannya agar sesuai dengan tujuan Anda.
//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterStartCapture
//
// Purpose:
// Begins an asynchronous biometric capture.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated with
// the biometric unit.
// Purpose - A WINBIO_BIR_PURPOSE bitmask that specifies the intended
// use of the sample.
// Overlapped - Receives a pointer to an OVERLAPPED structure.
//
static HRESULT
WINAPI
SensorAdapterStartCapture(
__inout PWINBIO_PIPELINE Pipeline,
__in WINBIO_BIR_PURPOSE Purpose,
__out LPOVERLAPPED *Overlapped
)
{
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(Purpose) ||
!ARGUMENT_PRESENT(Overlapped))
{
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;
}
*Overlapped = NULL;
// Synchronously retrieve the status.
hr = SensorAdapterQueryStatus(Pipeline, &sensorStatus);
if (FAILED(hr))
{
return hr;
}
// Determine whether the sensor requires calibration.
if (sensorStatus == WINBIO_SENSOR_NOT_CALIBRATED)
{
// Call a custom function that sends IOCTLs to
// the sensor to calibrate it. This operation is
// synchronous.
hr = _SensorAdapterCalibrate(Pipeline);
// Retrieve the status again to determine whether the
// sensor is ready.
if (SUCCEEDED(hr))
{
hr = SensorAdapterQueryStatus(Pipeline, &sensorStatus);
}
if (FAILED(hr))
{
return hr;
}
}
if (sensorStatus == WINBIO_SENSOR_BUSY)
{
return WINBIO_E_DEVICE_BUSY;
}
if (sensorStatus != WINBIO_SENSOR_READY)
{
return WINBIO_E_INVALID_DEVICE_STATE;
}
// Determine whether the data format has been previously determined.
// If it has not, find a format supported by both the engine and
// the sensor.
if ((sensorContext->Format.Owner == 0) &&
(sensorContext->Format.Type == 0))
{
// Retrieve the format preferred by the engine.
hr = Pipeline->EngineInterface->QueryPreferredFormat(
Pipeline,
&sensorContext->Format,
&sensorContext->VendorFormat
);
if (SUCCEEDED(hr))
{
// Call a private function that queries the sensor driver
// and attaches an attribute array to the sensor context.
// This operation is synchronous.
hr = _SensorAdapterGetAttributes(Pipeline);
}
if (SUCCEEDED(hr))
{
// Search the sensor attributes array for the format
// preferred by the engine adapter.
DWORD i = 0;
for (i = 0; i < sensorContext->AttributesBuffer->SupportedFormatEntries; i++)
{
if ((sensorContext->AttributesBuffer->SupportedFormat[i].Owner == sensorContext->Format.Owner) &&
(sensorContext->AttributesBuffer->SupportedFormat[i].Type == sensorContext->Format.Type))
{
break;
}
}
if (i == sensorContext->AttributesBuffer->SupportedFormatEntries)
{
// No match was found. Use the default.
sensorContext->Format.Owner = WINBIO_ANSI_381_FORMAT_OWNER;
sensorContext->Format.Type = WINBIO_ANSI_381_FORMAT_TYPE;
}
}
else
{
return hr;
}
}
// Set up the parameter-input block needed for the IOCTL.
captureParameters.PayloadSize = sizeof(WINBIO_CAPTURE_PARAMETERS);
captureParameters.Purpose = Purpose;
captureParameters.Format.Owner = sensorContext->Format.Owner;
captureParameters.Format.Type = sensorContext->Format.Type;
CopyMemory(&captureParameters.VendorFormat, &sensorContext->VendorFormat, sizeof (WINBIO_UUID));
captureParameters.Flags = WINBIO_DATA_FLAG_RAW;
// Determine whether a buffer has already been allocated for this sensor.
if (sensorContext->CaptureBuffer == NULL)
{
DWORD allocationSize = 0;
sensorContext->CaptureBufferSize = 0;
// This sample assumes that the sensor driver returns
// a fixed-size DWORD buffer containing the required
// size of the capture buffer if it receives a buffer
// that is smaller than sizeof(WINBIO_CAPTURE_DATA).
//
// Call the driver with a small buffer to get the
// allocation size required for this sensor.
//
// Because this operation is asynchronous, you must block
// and wait for it to complete.
result = DeviceIoControl(
Pipeline->SensorHandle,
IOCTL_VENDOR_PRIVATE_CMD_CAPTURE_DATA,
&captureParameters,
sizeof(WINBIO_CAPTURE_PARAMETERS),
&allocationSize,
sizeof(DWORD),
&bytesReturned,
&sensorContext->Overlapped
);
if (!result && GetLastError() == ERROR_IO_PENDING)
{
SetLastError(ERROR_SUCCESS);
result = GetOverlappedResult(
Pipeline->SensorHandle,
&sensorContext->Overlapped,
&bytesReturned,
TRUE
);
}
if (!result || bytesReturned != sizeof (DWORD))
{
// An error occurred.
hr = _AdapterGetHresultFromWin32(GetLastError());
return hr;
}
// Make sure that you allocate at least the minimum buffer
// size needed to get the payload structure.
if (allocationSize < sizeof(WINBIO_CAPTURE_DATA))
{
allocationSize = sizeof(WINBIO_CAPTURE_DATA);
}
// Allocate the buffer.
sensorContext->CaptureBuffer = (PWINBIO_CAPTURE_DATA)_AdapterAlloc(allocationSize);
if (!sensorContext->CaptureBuffer)
{
sensorContext->CaptureBufferSize = 0;
return E_OUTOFMEMORY;
}
sensorContext->CaptureBufferSize = allocationSize;
}
else
{
// The buffer has already been allocated. Clear the buffer contents.
SensorAdapterClearContext(Pipeline);
}
// Send the capture request. Because this is an asynchronous operation,
// the IOCTL call will return immediately regardless of
// whether the I/O has completed.
result = DeviceIoControl(
Pipeline->SensorHandle,
IOCTL_VENDOR_PRIVATE_CMD_CAPTURE_DATA,
&captureParameters,
sizeof (WINBIO_CAPTURE_PARAMETERS),
sensorContext->CaptureBuffer,
sensorContext->CaptureBufferSize,
&bytesReturned,
&sensorContext->Overlapped
);
if (result ||
(!result && GetLastError() == ERROR_IO_PENDING))
{
*Overlapped = &sensorContext->Overlapped;
return S_OK;
}
else
{
hr = _AdapterGetHresultFromWin32(GetLastError());
return hr;
}
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 7 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 R2 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbio_adapter.h (termasuk Winbio_adapter.h) |