fungsi panggilan balik PIBIO_ENGINE_CONTROL_UNIT_FN (winbio_adapter.h)
Dipanggil oleh Windows Biometric Framework untuk melakukan operasi kontrol yang ditentukan vendor yang tidak memerlukan hak istimewa yang ditingkatkan. Panggil fungsi EngineAdapterControlUnitPrivileged untuk melakukan operasi kontrol yang ditentukan vendor yang memerlukan hak istimewa yang ditinggikan.
Sintaks
PIBIO_ENGINE_CONTROL_UNIT_FN PibioEngineControlUnitFn;
HRESULT PibioEngineControlUnitFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] ULONG ControlCode,
[in] PUCHAR SendBuffer,
[in] SIZE_T SendBufferSize,
[in] PUCHAR ReceiveBuffer,
[in] SIZE_T ReceiveBufferSize,
[out] PSIZE_T ReceiveDataSize,
[out] PULONG OperationStatus
)
{...}
Parameter
[in, out] Pipeline
Penunjuk ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.
[in] ControlCode
Nilai ULONG yang menentukan operasi yang ditentukan vendor untuk dilakukan.
[in] SendBuffer
Penunjuk ke buffer yang berisi informasi kontrol yang dikirim ke adaptor mesin. Format dan konten buffer ditentukan vendor.
[in] SendBufferSize
Ukuran, dalam byte, dari buffer yang ditentukan oleh parameter SendBuffer .
[in] ReceiveBuffer
Penunjuk ke buffer yang menerima informasi yang dikembalikan oleh adaptor mesin sebagai respons terhadap operasi kontrol. Format buffer ditentukan vendor.
[in] ReceiveBufferSize
Ukuran, dalam byte, dari buffer yang ditentukan oleh parameter ReceiveBuffer .
[out] ReceiveDataSize
Penunjuk ke variabel yang menerima ukuran, dalam byte, dari data yang ditulis ke buffer yang ditentukan oleh parameter ReceiveBuffer .
[out] OperationStatus
Penunjuk ke variabel yang menerima kode status yang ditentukan vendor yang menentukan hasil operasi kontrol.
Mengembalikan nilai
Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.
| Menampilkan kode | Deskripsi |
|---|---|
|
Argumen pointer wajib adalah NULL. |
|
Ukuran atau format buffer yang ditentukan oleh parameter SendBuffer tidak benar, atau nilai yang ditentukan dalam parameter ControlCode tidak dikenali oleh adaptor. |
|
Buffer yang ditentukan oleh parameter ReceiveBuffer terlalu kecil. |
|
Operasi dibatalkan. |
|
Terjadi kegagalan perangkat keras. |
|
Nilai yang ditentukan dalam parameter ControlCode tidak dikenali oleh adaptor.
Catatan Dimulai dengan Windows 8, gunakan hanya E_INVALIDARG untuk memberi sinyal kondisi ini.
|
Keterangan
Implementasi Anda dari fungsi ini harus identik dengan implementasi fungsi EngineAdapterControlUnitPrivileged Kecuali bahwa hak istimewa yang ditinggikan tidak diperlukan untuk melakukan operasi yang ditentukan oleh parameter ControlCode . Anda bertanggung jawab untuk mendefinisikan operasi dan memutuskan mana yang tidak akan memerlukan hak istimewa yang ditingkatkan.
Fungsi ini harus memeriksa nilai parameter ReceiveBufferSize untuk memastikan bahwa buffer yang ditentukan oleh parameter ReceiveBuffer cukup besar untuk menahan data yang dikembalikan.
Contoh
Pseudocode berikut menunjukkan salah satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Kau harus menyesuaikannya sesuai dengan tujuanmu.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterControlUnit
//
// Purpose:
// Performs a vendor-defined control operation that does not require
// elevated privilege.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// ControlCode - Specifies the vendor-defined operation to perform
// SendBuffer - Contains the control information sent to the
// engine adapter
// SendBufferSize - Size, in bytes, of the buffer specified by the
// SendBuffer parameter
// ReceiveBuffer - Receives information returned by the engine adapter
// in response to the control operation
// ReceiveBufferSize - Size, in bytes, of the buffer specified by the
// ReceiveBuffer parameter.
// ReceiveDataSize - Receives the size, in bytes, of the data written to
// the buffer specified by the ReceiveBuffer parameter
// OperationStatus - Receives a vendor-defined status code that specifies
// the outcome of the control operation.
//
static HRESULT
WINAPI
EngineAdapterControlUnit(
__inout PWINBIO_PIPELINE Pipeline,
__in ULONG ControlCode,
__in PUCHAR SendBuffer,
__in SIZE_T SendBufferSize,
__in PUCHAR ReceiveBuffer,
__in SIZE_T ReceiveBufferSize,
__out PSIZE_T ReceiveDataSize,
__out PULONG OperationStatus
)
{
HRESULT hr = S_OK;
BOOL result = TRUE;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(SendBuffer) ||
!ARGUMENT_PRESENT(ReceiveBuffer) ||
!ARGUMENT_PRESENT(ReceiveDataSize) ||
!ARGUMENT_PRESENT(OperationStatus))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT engineContext =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Verify the state of the pipeline.
if (engineContext == NULL ||
engineContext->FileHandle == INVALID_HANDLE_VALUE)
{
hr = WINBIO_E_INVALID_DEVICE_STATE;
goto cleanup;
}
switch (ControlCode)
{
case MY_NONPRIVILEGED_CTRL_CODE_NP1:
{
CTRL_CODE_NP1_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP1_SEND_BUFFER*)SendBuffer;
// Verify the size of the send buffer.
if (SendBufferSize < sizeof(CTRL_CODE_NP1_SEND_BUFFER))
{
hr = E_INVALIDARG;
break;
}
// Perform any other checks that may be required on the buffer
// contents. Return E_INVALIDARG if any of the checks fail.
if (sendBuffer->SomeField != SomeSpecialValue ||
sendBuffer->SomeOtherField != SomeOtherSpecialValue)
{
hr = E_INVALIDARG;
break;
}
if (ReceiveBufferSize < sizeof(CTRL_CODE_NP1_RECEIVE_BUFFER))
{
hr = E_NOT_SUFFICIENT_BUFFER;
break;
}
}
// Fall through and perform the control operation after the switch
// statement. Alternatively, depending on your requirements, you can
// perform the control operation here.
break;
case MY_NONPRIVILEGED_CTRL_CODE_NP2:
// Continue testing for other non-privileged control codes that your
// adapter supports.
{
CTRL_CODE_NP2_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP2_SEND_BUFFER*)SendBuffer;
// Verify the size of the send buffer.
if (SendBufferSize < sizeof(CTRL_CODE_NP2_SEND_BUFFER))
{
hr = E_INVALIDARG;
break;
}
// Perform any other checks that may be required on the buffer
// contents. Return E_INVALIDARG if any of the checks fail.
if (sendBuffer->SomeField != SomeSpecialValue ||
sendBuffer->SomeOtherField != SomeOtherSpecialValue)
{
hr = E_INVALIDARG;
break;
}
if (ReceiveBufferSize < sizeof(CTRL_CODE_NP2_RECEIVE_BUFFER))
{
hr = E_NOT_SUFFICIENT_BUFFER;
break;
}
}
break;
default:
// All unrecognized control code values should return an error.
hr = WINBIO_E_INVALID_CONTROL_CODE;
break;
}
if (FAILED(hr))
{
goto cleanup;
}
// If control code validation succeeds, perform the control operation. This
// example assumes that your adapter context structure contains an open
// handle to a hardware driver. It also assumes that the driver performs
// overlapped I/O and that a properly initialized OVERLAPPED structure is
// contained in the engine context.
result = DeviceIoControl(
Pipeline->EngineHandle,
ControlCode,
SendBuffer,
(DWORD)SendBufferSize,
ReceiveBuffer,
(DWORD)ReceiveBufferSize,
(LPDWORD)ReceiveDataSize,
&Pipeline->EngineContext->Overlapped
);
if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
{
SetLastError(ERROR_SUCCESS);
result = GetOverlappedResult(
Pipeline->EngineHandle,
&Pipeline->EngineContext->Overlapped,
(LPDWORD)ReceiveDataSize,
TRUE
);
}
*OperationStatus = GetLastError();
if (!result)
{
hr = _AdapterGetHresultFromWin32(*OperationStatus);
}
cleanup:
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) |