PIBIO_STORAGE_QUERY_BY_SUBJECT_FN Rückruffunktion (winbio_adapter.h)

Artikel
08/27/2023

Wird vom Windows Biometric Framework oder vom Engine-Adapter aufgerufen, um Vorlagen zu suchen, die einer angegebenen Identität und einem angegebenen Unterfaktor entsprechen.

Syntax

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

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

Parameter

[in, out] Pipeline

Zeiger auf die WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.

[in] Identity

Zeiger auf eine WINBIO_IDENTITY Struktur, die die zu ermittelnde GUID oder SID enthält. Wenn das Feld Typ dieser Struktur WINBIO_IDENTITY_TYPE_WILDCARD enthält, gibt die Abfrage jede Vorlage zurück, die dem SubFactor-Parameter entspricht.

[in] SubFactor

Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der den zu findenden Unterfaktor angibt. Wenn dieser Wert WINBIO_SUBTYPE_ANY ist, gibt die Abfrage jede Vorlage zurück, die dem Identity-Parameter entspricht.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Rückgabecode	Beschreibung
E_INVALIDARG	Das durch den SubFactor-Parameter angegebene Argument ist ungültig, oder ein Element der struktur, die durch den Identity-Parameter angegeben wird, ist ungültig.
E_POINTER	Ein obligatorisches Zeigerargument ist NULL.
WINBIO_E_DATABASE_NO_RESULTS	Die Abfrage war erfolgreich, aber es konnten keine übereinstimmenden Datensätze gefunden werden.
WINBIO_E_DATABASE_LOCKED	Die Datenbank ist gesperrt.
WINBIO_E_DATABASE_READ_ERROR	Ein nicht angegebenes Problem ist aufgetreten.
WINBIO_E_INVALID_DEVICE_STATE	Der StorageContext-Member des Pipelineobjekts ist NULL , oder der FileHandle-Member ist ungültig.

Hinweise

Wenn diese Methode erfolgreich zurückgibt, wird das Resultset in der Pipeline durch die Ergebnisse der Abfrage ersetzt, auch wenn die Abfrage einen leeren Satz zurückgibt.

Aufrufer dieser Funktion sollten in der Lage sein, alle Datensätze wie folgt abzurufen:

Übergeben einer WINBIO_IDENTITY-Struktur im Identity-Parameter , wobei das Feld Typ auf WINBIO_IDENTITY_TYPE_WILDCARD festgelegt ist.
Übergeben WINBIO_SUBTYPE_ANY im SubFactor-Parameter .

Nach einem erfolgreichen Aufruf dieser Funktion sollte der Resultsetcursor auf dem ersten Datensatz im Satz positioniert werden.

Wichtig

Versuchen Sie nicht, den für den SubFactor-Parameter angegebenen Wert zu überprüfen. Der Windows-Biometriedienst überprüft den angegebenen Wert, bevor er an Ihre Implementierung übergeben wird. Wenn der Wert WINBIO_SUBTYPE_NO_INFORMATION oder WINBIO_SUBTYPE_ANY ist, überprüfen Sie ggf..

Beispiele

Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio_adapter.h (Winbio_adapter.h einschließen)