Função WinBioGetProperty (winbio.h)

Recupera uma propriedade de sessão, unidade ou modelo. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel.

Sintaxe

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

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] PropertyType

Um valor WINBIO_PROPERTY_TYPE que especifica a origem das informações da propriedade. Atualmente, isso deve ser WINBIO_PROPERTY_TYPE_UNIT ou WINBIO_PROPERTY_TYPE_ACCOUNT. Para obter mais informações sobre tipos de propriedade, consulte Constantes WINBIO_PROPERTY_TYPE.

O valor de WINBIO_PROPERTY_TYPE_ACCOUNT tem suporte a partir de Windows 10.

[in] PropertyId

Um valor WINBIO_PROPERTY_ID que especifica a propriedade que você deseja consultar. Os valores a seguir são possíveis.

Valor Significado
WINBIO_PROPERTY_SAMPLE_HINT
Estima o número máximo de boas amostras biométricas necessárias para concluir um modelo de registro. O resultado da consulta de propriedade é retornado no buffer para o qual o parâmetro PropertyBuffer aponta como um valor ULONG que contém a dica.
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO
Contém informações estendidas sobre os recursos e atributos do componente do sensor que está conectado a uma unidade biométrica específica. O resultado da consulta de propriedade é retornado no buffer para o qual o parâmetro PropertyBuffer aponta como uma estrutura WINBIO_EXTENDED_SENSOR_INFO . Esse valor tem suporte a partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO
Contém informações estendidas sobre os recursos e atributos do componente do mecanismo que está conectado a uma unidade biométrica específica. O resultado da consulta de propriedade é retornado no buffer para o qual o parâmetro PropertyBuffer aponta como uma estrutura WINBIO_EXTENDED_ENGINE_INFO . Esse valor tem suporte a partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO
Contém informações estendidas sobre os recursos e atributos do componente de armazenamento que está conectado a uma unidade biométrica específica. O resultado da consulta de propriedade é retornado no buffer para o qual o parâmetro PropertyBuffer aponta como uma estrutura WINBIO_EXTENDED_STORAGE_INFO . Esse valor tem suporte a partir de Windows 10.
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS
Contém informações estendidas sobre o status de um registro em andamento em uma unidade biométrica específica. O resultado da consulta de propriedade é retornado no buffer para o qual o parâmetro PropertyBuffer aponta como uma estrutura WINBIO_EXTENDED_ENROLLMENT_STATUS . Se nenhum registro estiver em andamento na unidade biométrica, o membro TemplateStatus da estrutura retornada terá um valor de WINBIO_E_INVALID_OPERATION. Esse valor tem suporte a partir de Windows 10.
WINBIO_PROPERTY_ANTI_SPOOF_POLICY
Contém os valores da política antispoofing para uma conta de usuário específica. A operação de propriedade é retornada no buffer para o qual o parâmetro PropertyBuffer aponta como uma estrutura WINBIO_ANTI_SPOOF_POLICY . Esse valor tem suporte a partir de Windows 10.
 

Para obter mais informações sobre essas propriedades, consulte Constantes WINBIO_PROPERTY.

[in, optional] UnitId

Um valor WINBIO_UNIT_ID que identifica a unidade biométrica. Você pode encontrar um identificador de unidade chamando as funções WinBioEnumBiometricUnits ou WinBioLocateSensor .

Se você especificar WINBIO_PROPERTY_ANTI_SPOOF_POLICY como o valor do parâmetro PropertyId , especifique 0 para o parâmetro UnitId . Se você especificar qualquer outra propriedade com o parâmetro PropertyId , não poderá especificar 0 para o parâmetro UnitId .

[in, optional] Identity

Uma estrutura WINBIO_IDENTITY que fornece o SID da conta para a qual você deseja obter a política antispoofing, se você especificar WINBIO_PROPERTY_ANTI_SPOOF_POLICY como o valor do parâmetro PropertyId .

Se você especificar qualquer outro valor para o parâmetro PropertyId , o parâmetro Identity deverá ser NULL.

[in, optional] SubFactor

Reservado. Isso deve ser WINBIO_SUBTYPE_NO_INFORMATION.

PropertyBuffer

Endereço de um ponteiro para um buffer que recebe o valor da propriedade. Para obter informações sobre o conteúdo desse buffer para propriedades diferentes, consulte as descrições dos valores de propriedade para o parâmetro PropertyId .

[out, optional] PropertyBufferSize

Ponteiro para uma variável que recebe o tamanho, em bytes, do buffer apontado pelo parâmetro PropertyBuffer .

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 especificado pelo parâmetro SessionHandle não é válido.
E_POINTER
Os argumentos Identity, PropertyBuffer ou PropertyBufferSize não podem ser NULL.
E_INVALIDARG
Os argumentos UnitId, Identity ou SubFactor estão incorretos.
WINBIO_E_INVALID_PROPERTY_TYPE
O valor do argumento PropertyType está incorreto.
WINBIO_E_INVALID_PROPERTY_ID
O valor do argumento PropertyId está incorreto.
WINBIO_E_LOCK_VIOLATION
O chamador tentou consultar uma propriedade que reside dentro de uma região bloqueada.
WINBIO_E_UNSUPPORTED_PROPERTY
O objeto que está sendo consultado não dá suporte à propriedade especificada.
WINBIO_E_ENROLLMENT_IN_PROGRESS
Não foi possível concluir a operação porque a unidade biométrica especificada está sendo usada para uma transação de registro (somente pool do sistema).

Comentários

Para usar WinBioGetProperty 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 evitar vazamentos de memória ao usar WinBioGetProperty de forma síncrona, você deve chamar WinBioFree para liberar a memória apontada pelo parâmetro PropertyBuffer quando terminar de usar os dados contidos no buffer.

Para usar WinBioGetProperty 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. Se a operação for bem-sucedida, a estrutura retornará informações em uma estrutura GetProperty aninhada. 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 ao usar WinBioGetProperty de forma assíncrona, você deve chamar WinBioFree para liberar a estrutura de WINBIO_ASYNC_RESULT depois de terminar de usá-la. A estrutura WINBIO_ASYNC_RESULT e o buffer de propriedades ocupam um único bloco de memória, portanto, seu aplicativo só precisa passar o endereço da estrutura WINBIO_ASYNC_RESULT para WinBioFree. Quando você chama WinBioFree dessa forma, WinBioFree libera automaticamente a estrutura WINBIO_ASYNC_RESULT e o buffer de propriedades. Se você tentar liberar o buffer de propriedades separadamente nesse caso, o aplicativo deixará de responder.

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

WinBioFree

WinBioSetProperty