PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN fungsi panggilan balik (winbio_adapter.h)
Dipanggil oleh Windows Biometric Framework untuk melakukan operasi kontrol yang ditentukan vendor yang memerlukan hak istimewa yang ditingkatkan. Panggil fungsi SensorAdapterControlUnit untuk melakukan operasi kontrol yang ditentukan vendor yang tidak memerlukan hak istimewa yang ditinggikan.
Sintaks
PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN PibioSensorControlUnitPrivilegedFn;
HRESULT PibioSensorControlUnitPrivilegedFn(
[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 sensor. 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 sensor 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 SensorAdapterControlUnit Kecuali bahwa hak istimewa yang ditinggikan diperlukan untuk melakukan operasi yang ditentukan oleh parameter ControlCode . Anda bertanggung jawab untuk mendefinisikan operasi dan memutuskan mana yang 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.
//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterControlUnitPrivileged
//
// Purpose:
// Performs a vendor-defined control operation that requires 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
// sensor adapter
// SendBufferSize - Size, in bytes, of the buffer specified by the
// SendBuffer parameter
// ReceiveBuffer - Receives information returned by the sensor 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
SensorAdapterControlUnitPrivileged(
__inout PWINBIO_PIPELINE Pipeline,
__in ULONG ControlCode,
__in_bcount(SendBufferSize) PUCHAR SendBuffer,
__in SIZE_T SendBufferSize,
__in_bcount(ReceiveBufferSize) PUCHAR ReceiveBuffer,
__in SIZE_T ReceiveBufferSize,
__out SIZE_T *ReceiveDataSize,
__out ULONG *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_SENSOR_CONTEXT sensorContext =
(PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;
// Verify the state of the pipeline.
if (sensorContext == NULL ||
Pipeline->SensorHandle == INVALID_HANDLE_VALUE)
{
hr = WINBIO_E_INVALID_DEVICE_STATE;
goto cleanup;
}
switch (ControlCode)
{
case MY_PRIVILEGED_CTRL_CODE_P1:
{
CTRL_CODE_P1_SEND_BUFFER *sendBuffer = (CTRL_CODE_P1_SEND_BUFFER*)SendBuffer;
// Verify the size of the send buffer.
if (SendBufferSize < sizeof(CTRL_CODE_P1_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_P1_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_PRIVILEGED_CTRL_CODE_P2:
// Continue testing for other non-privileged control codes that your
// adapter supports.
{
CTRL_CODE_P2_SEND_BUFFER *sendBuffer = (CTRL_CODE_P2_SEND_BUFFER*)SendBuffer;
// Verify the size of the send buffer.
if (SendBufferSize < sizeof(CTRL_CODE_P2_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_P2_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 the driver performs overlapped I/O and that a properly
// initialized OVERLAPPED structure is contained in the sensor context.
result = DeviceIoControl(
Pipeline->SensorHandle,
ControlCode,
SendBuffer,
(DWORD)SendBufferSize,
ReceiveBuffer,
(DWORD)ReceiveBufferSize,
(LPDWORD)ReceiveDataSize,
&sensorContext->Overlapped
);
if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
{
SetLastError(ERROR_SUCCESS);
result = GetOverlappedResult(
Pipeline->SensorHandle,
&sensorContext->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) |