PIBIO_ENGINE_CONTROL_UNIT_FN função de retorno de chamada (winbio_adapter.h)
Chamado pela Estrutura Biométrica do Windows para executar uma operação de controle definida pelo fornecedor que não exige privilégios elevados. Chame a função EngineAdapterControlUnitPrivileged para executar uma operação de controle definida pelo fornecedor que requer privilégios elevados.
Sintaxe
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
)
{...}
Parâmetros
[in, out] Pipeline
Ponteiro para uma estrutura WINBIO_PIPELINE associada à unidade biométrica que executa a operação.
[in] ControlCode
Um valor ULONG que especifica a operação definida pelo fornecedor a ser executada.
[in] SendBuffer
Ponteiro para um buffer que contém as informações de controle enviadas para o adaptador do mecanismo. O formato e o conteúdo do buffer são definidos pelo fornecedor.
[in] SendBufferSize
Tamanho, em bytes, do buffer especificado pelo parâmetro SendBuffer .
[in] ReceiveBuffer
Ponteiro para um buffer que recebe informações retornadas pelo adaptador do mecanismo em resposta à operação de controle. O formato do buffer é definido pelo fornecedor.
[in] ReceiveBufferSize
Tamanho, em bytes, do buffer especificado pelo parâmetro ReceiveBuffer .
[out] ReceiveDataSize
Ponteiro para uma variável que recebe o tamanho, em bytes, dos dados gravados no buffer especificado pelo parâmetro ReceiveBuffer .
[out] OperationStatus
Ponteiro para uma variável que recebe um código de status definido pelo fornecedor que especifica o resultado da operação de controle.
Retornar valor
Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela deverá retornar um dos seguintes valores HRESULT para indicar o erro.
| Código de retorno | Descrição |
|---|---|
|
Um argumento de ponteiro obrigatório é NULL. |
|
O tamanho ou o formato do buffer especificado pelo parâmetro SendBuffer não está correto ou o valor especificado no parâmetro ControlCode não é reconhecido pelo adaptador. |
|
O buffer especificado pelo parâmetro ReceiveBuffer é muito pequeno. |
|
A operação foi cancelada. |
|
Houve uma falha de hardware. |
|
O valor especificado no parâmetro ControlCode não é reconhecido pelo adaptador.
Nota Começando com Windows 8, use apenas E_INVALIDARG para sinalizar essa condição.
|
Comentários
Sua implementação dessa função deve ser idêntica à implementação da função EngineAdapterControlUnitPrivileged , exceto que privilégios elevados não são necessários para executar as operações especificadas pelo parâmetro ControlCode . Você é responsável por definir as operações e decidir quais não exigirão privilégios elevados.
Essa função deve marcar o valor do parâmetro ReceiveBufferSize para ter certeza de que o buffer especificado pelo parâmetro ReceiveBuffer é grande o suficiente para conter os dados que estão sendo retornados.
Exemplos
O pseudocódigo a seguir mostra uma implementação possível dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar ao seu propósito.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbio_adapter.h (inclua Winbio_adapter.h) |