функция обратного вызова PIBIO_SENSOR_CONTROL_UNIT_PRIVILEGED_FN (winbio_adapter.h)
Вызывается Windows Biometric Framework для выполнения определяемой поставщиком операции управления, требующей повышенных привилегий. Вызовите функцию SensorAdapterControlUnit , чтобы выполнить определяемую поставщиком операцию управления, которая не требует повышенных привилегий.
Синтаксис
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
)
{...}
Параметры
[in, out] Pipeline
Указатель на WINBIO_PIPELINE структуру, связанную с биометрической единицей, выполняющей операцию.
[in] ControlCode
Значение ULONG , указывающее определяемую поставщиком операцию.
[in] SendBuffer
Указатель на буфер, содержащий сведения об управлении, отправляемые адаптеру датчика. Формат и содержимое буфера определяются поставщиком.
[in] SendBufferSize
Размер буфера, заданного параметром SendBuffer , в байтах.
[in] ReceiveBuffer
Указатель на буфер, который получает сведения, возвращаемые адаптером датчика в ответ на операцию управления. Формат буфера определяется поставщиком.
[in] ReceiveBufferSize
Размер буфера, заданного параметром ReceiveBuffer , в байтах.
[out] ReceiveDataSize
Указатель на переменную, которая получает размер (в байтах) данных, записанных в буфер, заданный параметром ReceiveBuffer .
[out] OperationStatus
Указатель на переменную, которая получает определенный поставщиком код состояния, указывающий результат операции управления.
Возвращаемое значение
Если функция завершается успешно, она возвращает S_OK. Если функция завершается сбоем, она должна вернуть одно из следующих значений HRESULT , чтобы указать на ошибку.
| Код возврата | Описание |
|---|---|
|
Обязательный аргумент указателя — NULL. |
|
Размер или формат буфера, заданный параметром SendBuffer , неправильный, или значение, указанное в параметре ControlCode , не распознается адаптером. |
|
Буфер, заданный параметром ReceiveBuffer , слишком мал. |
|
Операция была отменена. |
|
Произошел сбой оборудования. |
|
Значение, указанное в параметре ControlCode , не распознается адаптером.
Примечание Начиная с Windows 8, используйте только E_INVALIDARG, чтобы сообщить об этом условии.
|
Комментарии
Реализация этой функции должна быть идентична реализации функции SensorAdapterControlUnit , за исключением того, что для выполнения операций, заданных параметром ControlCode , требуются повышенные привилегии. Вы несете ответственность за определение операций и выбор того, какие из них потребуют повышенных привилегий.
Эта функция должна проверка значение параметра ReceiveBufferSize, чтобы убедиться, что буфер, заданный параметром ReceiveBuffer, достаточно велик для хранения возвращаемых данных.
Примеры
В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio_adapter.h (включая Winbio_adapter.h) |