PIBIO_STORAGE_CONTROL_UNIT_FN función de devolución de llamada (winbio_adapter.h)
Llamado por Windows Biometric Framework para realizar una operación de control definida por el proveedor que no requiere privilegios elevados. Llame a la función StorageAdapterControlUnitPrivileged para realizar una operación de control definida por el proveedor que requiera privilegios elevados.
Sintaxis
PIBIO_STORAGE_CONTROL_UNIT_FN PibioStorageControlUnitFn;
HRESULT PibioStorageControlUnitFn(
[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
)
{...}
Parámetros
[in, out] Pipeline
Puntero a la estructura WINBIO_PIPELINE asociada a la unidad biométrica que realiza la operación.
[in] ControlCode
Valor de ULONG que especifica la operación definida por el proveedor que se va a realizar.
[in] SendBuffer
Puntero a un búfer que contiene la información de control enviada al adaptador de almacenamiento. El formato y el contenido del búfer se definen por el proveedor.
[in] SendBufferSize
Tamaño, en bytes, del búfer especificado por el parámetro SendBuffer .
[in] ReceiveBuffer
Puntero al búfer que recibe información enviada por el adaptador de almacenamiento en respuesta a la operación de control. El formato del búfer está definido por el proveedor.
[in] ReceiveBufferSize
Tamaño, en bytes, del búfer especificado por el parámetro ReceiveBuffer .
[out] ReceiveDataSize
Puntero a una variable que recibe el tamaño, en bytes, de los datos escritos en el búfer especificado por el parámetro ReceiveBuffer .
[out] OperationStatus
Puntero a una variable que recibe un código de estado definido por el proveedor que especifica el resultado de la operación de control.
Valor devuelto
Si la función se realiza correctamente, devuelve S_OK. Si se produce un error en la función, debe devolver uno de los siguientes valores HRESULT para indicar el error.
| Código devuelto | Descripción |
|---|---|
|
Un argumento de puntero obligatorio es NULL. |
|
El adaptador no reconoce el tamaño o el formato del búfer especificado por el parámetro SendBuffer , o bien el adaptador no reconoce el valor especificado en el parámetro ControlCode . |
|
El búfer especificado por el parámetro ReceiveBuffer es demasiado pequeño. |
|
Operación cancelada. |
|
Se produjo un error de hardware. |
|
El adaptador no reconoce el valor especificado en el parámetro ControlCode .
Nota A partir de Windows 8, use solo E_INVALIDARG para indicar esta condición.
|
Comentarios
La implementación de esta función debe ser idéntica a la implementación de la función StorageAdapterControlUnitPrivileged , salvo que no se requieren privilegios elevados para realizar las operaciones especificadas por el parámetro ControlCode . Usted es responsable de definir las operaciones y decidir qué no requerirá privilegios elevados.
Esta función debe comprobar el valor del parámetro ReceiveBufferSize para estar seguro de que el búfer especificado por el parámetro ReceiveBuffer es lo suficientemente grande como para contener los datos que se devuelven.
Ejemplos
El pseudocódigo siguiente muestra una posible implementación de esta función. El ejemplo no se compila. Debes adaptarlo para adaptarlo a tu propósito.
/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterControlUnit
//
// 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
// storage adapter.
// SendBufferSize - Size, in bytes, of the buffer specified by the
// SendBuffer parameter.
// ReceiveBuffer - Receives information returned by the storage 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
StorageAdapterControlUnit(
__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_STORAGE_CONTEXT storageContext =
(PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;
// Verify the state of the pipeline.
if (storageContext == NULL ||
Pipeline->StorageHandle == 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 has put an open handle to a storage
// device in the Pipeline structure. It also assumes that the driver performs
// overlapped I/O and that a properly initialized OVERLAPPED structure is
// contained in the storage context.
result = DeviceIoControl(
Pipeline->StorageHandle,
ControlCode,
SendBuffer,
(DWORD)SendBufferSize,
ReceiveBuffer,
(DWORD)ReceiveBufferSize,
(LPDWORD)ReceiveDataSize,
&storageContext->Overlapped
);
if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
{
SetLastError(ERROR_SUCCESS);
result = GetOverlappedResult(
Pipeline->StorageHandle,
&storageContext->Overlapped,
(LPDWORD)ReceiveDataSize,
TRUE
);
}
*OperationStatus = GetLastError();
if (!result)
{
hr = _AdapterGetHresultFromWin32(*OperationStatus);
}
cleanup:
return hr;
}
Requisitos
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 R2 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winbio_adapter.h (incluya Winbio_adapter.h) |