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

Artículo
08/27/2023

Lo llama el adaptador del motor para buscar plantillas que coincidan con un vector de índice especificado.

Sintaxis

PIBIO_STORAGE_QUERY_BY_CONTENT_FN PibioStorageQueryByContentFn;

HRESULT PibioStorageQueryByContentFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor,
            ULONG IndexVector[],
  [in]      SIZE_T IndexElementCount
)
{...}

Parámetros

[in, out] Pipeline

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

[in] SubFactor

Valor de WINBIO_BIOMETRIC_SUBTYPE que especifica el subfactor asociado a la plantilla.

IndexVector[]

[in] IndexElementCount

Valor que contiene el número de elementos de la matriz de vectores de índice. Debe coincidir con el tamaño especificado al crear la base de datos. Si la base de datos se creó con un índice de longitud cero, este parámetro debe ser cero.

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
E_INVALIDARG	El argumento especificado por el parámetro SubFactor no es válido.
E_POINTER	Un argumento de puntero obligatorio es NULL.
E_OUTOFMEMORY	No se pudo asignar memoria para el encabezado de registro.
WINBIO_E_DATABASE_BAD_INDEX_VECTOR	El tamaño del vector de índice no coincide con el tamaño de índice especificado cuando se creó la base de datos.
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 produjo 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 aunque la consulta devuelva un conjunto vacío.

Si la base de datos se creó con un vector de índice de longitud cero, el conjunto de resultados contendrá todos los registros para los que el subfactor de plantilla coincide con el parámetro SubFactor . En ese caso, si el autor de la llamada pasa WINBIO_SUBTYPE_ANY para el parámetro SubFactor , esta función devuelve todos los registros de la base de datos.

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 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.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryByContent
//
// Purpose:
//      Locates templates that match a specified index vector.
//
// Parameters:
//      Pipeline          - Pointer to a WINBIO_PIPELINE structure associated with 
//                          the biometric unit performing the operation.
//      SubFactor         - A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                          associated with the template.
//      IndexVector       - Pointer to an array of ULONG index values.
//      IndexElementCount - A value that contains the number of elements in the index 
//                          vector array.
//
static HRESULT
WINAPI
StorageAdapterQueryByContent(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in ULONG IndexVector[],
    __in SIZE_T IndexElementCount
    )
{
    HRESULT hr = S_OK;
    BOOL lockAcquired = FALSE;
    struct _MY_ADAPTER_FILE_HEADER fileHeader = {0};
    SIZE_T remainingRecords = 0;
    LARGE_INTEGER currentRecordOffset = {0};
    struct _MY_ADAPTER_RECORD_HEADER *recordHeader = NULL;
    SIZE_T recordHeaderSize = 0;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(IndexVector))
    {
        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;
    }

    // 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;
    }

    // Validate the IndexElementCount argument.
    if (IndexElementCount != storageContext->IndexElementCount)
    {
        hr = WINBIO_E_DATABASE_BAD_INDEX_VECTOR;
        goto cleanup;
    }
    if (storageContext->IndexElementCount > 0 &&
        !ARGUMENT_PRESENT(IndexVector))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Clear the result set.
    hr = StorageAdapterClearContext(Pipeline);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Lock the database for reading.
    hr = _LockDatabase( Pipeline->StorageHandle, FALSE);
    if (FAILED(hr))
    {
        goto cleanup;
    }
    lockAcquired = TRUE;

    // Read the header block.
    hr = _ReadFileHeader( Pipeline->StorageHandle, &fileHeader );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Scan through all records looking for index vector matches.
    recordHeaderSize = 
        sizeof(struct _MY_ADAPTER_RECORD_HEADER) +
        (SIZE_T)fileHeader.IndexElementCount * sizeof(ULONG);

    currentRecordOffset = _MY_ADAPTER_FIRST_RECORD_OFFSET;
    remainingRecords = fileHeader.TotalRecordCount;

    while (remainingRecords > 0)
    {
        SIZE_T recordSize = 0;
        BOOLEAN match = FALSE;
        LARGE_INTEGER dataOffset = {0};

        // If you did not give up the current header during the previous 
        // iteration of the loop, reuse it.
        if (recordHeader == NULL)
        {
            recordHeader = (struct _MY_ADAPTER_RECORD_HEADER*)_AdapterAlloc( recordHeaderSize );
            if (recordHeader == NULL)
            {
                hr = E_OUTOFMEMORY;
                goto cleanup;
            }
        }
        else
        {
            ZeroMemory(recordHeader, recordHeaderSize);
        }

        hr = _ReadRecordHeader(
                Pipeline->StorageHandle,
                currentRecordOffset,
                recordHeader,
                recordHeaderSize
                );
        if (FAILED(hr))
        {
            goto cleanup;
        }

        recordSize = recordHeader->RecordSize;

        // Skip records marked for deletion.
        if ((recordHeader->Flags & _MY_ADAPTER_FLAG_RECORD_DELETED) == 0)
        {
            // Call a custom function (_MatchIndexVector) that compares the index
            // vector of the current record with the input index vector.
            hr = _MatchIndexVector(
                    SubFactor,
                    IndexVector,
                    IndexElementCount,
                    recordHeader->SubFactor,
                    _GetIndexVector(recordHeader),
                    storageContext->IndexElementCount,
                    &match
                    );
            if (FAILED(hr))
            {
                goto cleanup;
            }

            if (match == TRUE)
            {
                // Calculate the file offset of this record's data area.
                dataOffset.QuadPart = 
                    currentRecordOffset.QuadPart + 
                    recordHeader->RecordHeaderSize;

                // Add the matching record to the result set in the pipeline.
                hr = _ResultSetAddElement( 
                        &storageContext->ResultSet, 
                        recordHeader, 
                        dataOffset
                        );
                if (FAILED(hr))
                {
                    goto cleanup;
                }
                // The result set now owns the record header. Set the pointer
                // to NULL.
                recordHeader = NULL;
            }
        }

        currentRecordOffset.QuadPart += recordSize;
        --remainingRecords;
    }

    // If the search was successful, but the result set is empty, return 
    // WINBIO_E_DATABASE_NO_RESULTS
    if (SUCCEEDED(hr))
    {
        SIZE_T elementCount = 0;
        hr = _ResultSetGetCount(&storageContext->ResultSet, &elementCount);
    }

cleanup:

    if (recordHeader != NULL)
    {
        _AdapterRelease(recordHeader);
        recordHeader = NULL;
    }

    if (lockAcquired == TRUE)
    {
        _UnlockDatabase( Pipeline->StorageHandle);
        lockAcquired = FALSE;
    }

    if (FAILED(hr))
    {
        // Clear any partial result set from the pipeline.
        StorageAdapterClearContext(Pipeline);
    }

    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)