PIBIO_STORAGE_QUERY_BY_SUBJECT_FN función de devolución de llamada (winbio_adapter.h)

Artículo
08/27/2023

Lo llama el marco biométrico de Windows o el adaptador del motor para buscar plantillas que coincidan con una identidad y un subfactor especificados.

Sintaxis

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

HRESULT PibioStorageQueryBySubjectFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor
)
{...}

Parámetros

[in, out] Pipeline

Puntero a la estructura de WINBIO_PIPELINE asociada a la unidad biométrica que realiza la operación.

[in] Identity

Puntero a una estructura de WINBIO_IDENTITY que contiene el GUID o el SID que se va a ubicar. Si el campo Tipo de esta estructura contiene WINBIO_IDENTITY_TYPE_WILDCARD, la consulta devuelve cada plantilla que coincida con el parámetro SubFactor .

[in] SubFactor

Valor de WINBIO_BIOMETRIC_SUBTYPE que especifica el subfactor que se va a ubicar. Si este valor es WINBIO_SUBTYPE_ANY, la consulta devuelve cada plantilla que coincida con el parámetro Identity .

Valor devuelto

Si la función se ejecuta 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
E_INVALIDARG	El argumento especificado por el parámetro SubFactor no es válido o un miembro de la estructura especificada por el parámetro Identity no es válido.
E_POINTER	Un argumento de puntero obligatorio es NULL.
WINBIO_E_DATABASE_NO_RESULTS	La consulta se realizó correctamente, pero no se encontró ningún registro coincidente.
WINBIO_E_DATABASE_LOCKED	La base de datos está bloqueada.
WINBIO_E_DATABASE_READ_ERROR	Se ha producido un problema no especificado.
WINBIO_E_INVALID_DEVICE_STATE	El miembro StorageContext del objeto de canalización es NULL o el miembro FileHandle no es válido.

Comentarios

Si este método devuelve correctamente, el conjunto de resultados de la canalización se reemplaza por los resultados de la consulta incluso si la consulta devuelve un conjunto vacío.

Los autores de llamadas de esta función deben poder recuperar todos los registros mediante:

Pasar una estructura de WINBIO_IDENTITY en el parámetro Identity con el campo Tipo establecido en WINBIO_IDENTITY_TYPE_WILDCARD.
Pasar WINBIO_SUBTYPE_ANY en el parámetro SubFactor .

Después de una llamada correcta a esta función, el cursor del conjunto de resultados debe colocarse en el primer registro del conjunto.

Importante

No intente validar el valor proporcionado para el parámetro SubFactor . El servicio biométrico de Windows validará el valor proporcionado antes de pasarlo a la implementación. Si el valor es WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, valide cuando corresponda.

Ejemplos

El siguiente pseudocódigo muestra una posible implementación de esta función. El ejemplo no se compila. Debes adaptarlo para que se adapte a tu propósito.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryBySubject
//
// Purpose:
//      Locates templates that match a specified identity and sub-factor.
//
// Parameters:
//      Pipeline  -  Pointer to a WINBIO_PIPELINE structure associated with 
//                   the biometric unit performing the operation.
//      Identity  -  Pointer to a WINBIO_IDENTITY structure that contains the GUID 
//                   or SID to be located.
//      SubFactor -  A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                   to be located.
//
static HRESULT
WINAPI
StorageAdapterQueryBySubject(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL || storageContext->FileHandle == INVALID_HANDLE_VALUE)
    {
        hr =  WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Verify the Identity argument.
    if (Identity->Type != WINBIO_ID_TYPE_GUID &&
        Identity->Type != WINBIO_ID_TYPE_SID &&
        Identity->Type != WINBIO_ID_TYPE_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    if (Identity->Type == WINBIO_ID_TYPE_WILDCARD &&
        Identity->Value.Wildcard != WINBIO_IDENTITY_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // WINBIO_SUBTYPE_ANY is a valid sub-factor.
    // WINBIO_SUBTYPE_NO_INFORMATION is not a valid sub-factor.
    if (SubFactor == WINBIO_SUBTYPE_NO_INFORMATION)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Call a custom function (_FindAllMatchingRecords) that compares the 
    // identity and sub-factor values from the caller to the identity and
    // sub-factor values of every record in the database and adds the matching
    // database records to the result set in the pipeline.
    hr = _FindAllMatchingRecords( 
            Pipeline,
            Identity,
            SubFactor,
            &recordCount
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    if (recordCount == 0)
    {
        hr = WINBIO_E_DATABASE_NO_RESULTS;
        goto cleanup;
    }

cleanup:

    return hr;
}

Requisitos

Requisito	Value
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)