Função WinBioControlUnit (winbio.h)

  • Artigo

Permite que o chamador execute operações de controle definidas pelo fornecedor em uma unidade biométrica. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel. Essa função é fornecida para acesso a operações de fornecedor estendidas para as quais privilégios elevados não são necessários. Se os direitos de acesso forem necessários, chame a função WinBioControlUnitPrivileged .

Sintaxe

HRESULT WinBioControlUnit(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_UNIT_ID        UnitId,
  [in]            WINBIO_COMPONENT      Component,
  [in]            ULONG                 ControlCode,
                  PUCHAR                SendBuffer,
  [in]            SIZE_T                SendBufferSize,
                  PUCHAR                ReceiveBuffer,
  [in]            SIZE_T                ReceiveBufferSize,
                  SIZE_T                *ReceiveDataSize,
  [out, optional] ULONG                 *OperationStatus
);

Parâmetros

[in] SessionHandle

Um valor WINBIO_SESSION_HANDLE que identifica uma sessão biométrica aberta. Abra um identificador de sessão síncrona chamando WinBioOpenSession. Abra um identificador de sessão assíncrona chamando WinBioAsyncOpenSession.

[in] UnitId

Um valor WINBIO_UNIT_ID que identifica a unidade biométrica. Esse valor deve corresponder à ID de unidade usada anteriormente na função WinBioLockUnit .

[in] Component

Um valor WINBIO_COMPONENT que especifica o componente dentro da unidade biométrica que deve executar a operação. Esse pode ser um dos valores a seguir.

Valor Significado
WINBIO_COMPONENT_SENSOR
 Envie o comando para o adaptador do sensor.
WINBIO_COMPONENT_ENGINE
 Envie o comando para o adaptador do mecanismo.
WINBIO_COMPONENT_STORAGE
 Envie o comando para o adaptador de armazenamento.

[in] ControlCode

Um código definido pelo fornecedor reconhecido pela unidade biométrica especificada pelo parâmetro UnitId e pelo adaptador especificado pelo parâmetro Component .

SendBuffer

Endereço do buffer que contém as informações de controle a serem enviadas ao adaptador especificado pelo parâmetro Component . 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 .

ReceiveBuffer

Endereço do buffer que recebe informações enviadas pelo adaptador especificado pelo parâmetro Component . O formato e o conteúdo do buffer são definidos pelo fornecedor.

[in] ReceiveBufferSize

Tamanho, em bytes, do buffer especificado pelo parâmetro ReceiveBuffer .

ReceiveDataSize

Ponteiro para um valor SIZE_T que contém o tamanho, em bytes, dos dados gravados no buffer especificado pelo parâmetro ReceiveBuffer .

[out, optional] OperationStatus

Ponteiro para um inteiro que contém 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 retornará um valor HRESULT que indica o erro. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.

Código de retorno Descrição
E_HANDLE
 O identificador de sessão não é válido.
E_INVALIDARG
 O valor especificado no parâmetro ControlCode não é reconhecido.
E_POINTER
 Os parâmetros SendBuffer, ReceiveBuffer, ReceiveDataSize e OperationStatus não podem ser NULL.
WINBIO_E_INVALID_CONTROL_CODE
 O valor especificado no parâmetro ControlCode não é reconhecido.
WINBIO_E_LOCK_VIOLATION
 A unidade biométrica especificada pelo parâmetro UnitId deve ser bloqueada antes que qualquer operação de controle possa ser executada.

Comentários

Você deve chamar WinBioLockUnit antes de chamar WinBioControlUnit. A função WinBioLockUnit cria uma região bloqueada na qual as operações definidas pelo fornecedor podem ser executadas com segurança.

Os fornecedores que criam plug-ins devem decidir quais operações estendidas têm privilégios e quais estão disponíveis para todos os clientes. Para executar uma operação privilegiada, o aplicativo cliente deve chamar a função WinBioControlUnitPrivileged . A Estrutura Biométrica do Windows permite que somente os clientes que têm os direitos de acesso apropriados chamem WinBioControlUnitPrivileged.

Para usar WinBioControlUnit de forma síncrona, chame a função com um identificador de sessão criado chamando WinBioOpenSession. A função é bloqueada até que a operação seja concluída ou um erro seja encontrado.

Para usar WinBioControlUnit de forma assíncrona, chame a função com um identificador de sessão criado chamando WinBioAsyncOpenSession. A estrutura aloca uma estrutura WINBIO_ASYNC_RESULT e a usa para retornar informações sobre êxito ou falha da operação. A estrutura WINBIO_ASYNC_RESULT é retornada para o retorno de chamada do aplicativo ou para a fila de mensagens do aplicativo, dependendo do valor definido no parâmetro NotificationMethod da função WinBioAsyncOpenSession .

  • Se você optar por receber avisos de conclusão usando um retorno de chamada, deverá implementar uma função PWINBIO_ASYNC_COMPLETION_CALLBACK e definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_CALLBACK.
  • Se você optar por receber avisos de conclusão usando a fila de mensagens do aplicativo, deverá definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_MESSAGE. A estrutura retorna um ponteiro WINBIO_ASYNC_RESULT para o campo LPARAM da mensagem da janela.
Para evitar vazamentos de memória, você deve chamar WinBioFree para liberar a estrutura WINBIO_ASYNC_RESULT depois de terminar de usá-la.

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.h (inclua Winbio.h)
Biblioteca Winbio.lib
DLL Winbio.dll

Confira também

WinBioControlUnitPrivileged

WinBioLockUnit