PIBIO_ENGINE_VERIFY_FEATURE_SET_FN Rückruffunktion (winbio_adapter.h)
Wird vom Windows Biometric Framework aufgerufen, um die Vorlage im aktuellen Featuresatz mit einer bestimmten Vorlage in der Datenbank zu vergleichen. Wenn die Vorlagen gleichwertig sind, muss der Moduladapter den booleschen Wert, auf den der Match-Parameter verweist, auf TRUE festlegen, die übereinstimmende Vorlage im PayloadBlob-Parameter zurückgeben und einen Hash der Vorlage im HashValue-Parameter zurückgeben.
Syntax
PIBIO_ENGINE_VERIFY_FEATURE_SET_FN PibioEngineVerifyFeatureSetFn;
HRESULT PibioEngineVerifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_IDENTITY Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out] PBOOLEAN Match,
[out] PUCHAR *PayloadBlob,
[out] PSIZE_T PayloadBlobSize,
[out] PUCHAR *HashValue,
[out] PSIZE_T HashSize,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
Parameter
[in, out] Pipeline
Zeiger auf eine WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.
[in] Identity
Zeiger auf eine WINBIO_IDENTITY Struktur, die eine GUID oder SID enthält, die voraussichtlich mit der der aus der Datenbank wiederhergestellten Vorlage übereinstimmt.
[in] SubFactor
Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der dem der aus der Datenbank wiederhergestellten Vorlage entspricht. Weitere Details finden Sie im Abschnitt „Anmerkungen“.
[out] Match
Zeiger auf einen booleschen Wert, der angibt, ob die Parameter Identity und SubFactor mit denen der aus der Datenbank wiederhergestellten Vorlage übereinstimmen. TRUE gibt an, dass diese Werte übereinstimmen.
[out] PayloadBlob
Adresse einer Variablen, die einen Zeiger auf die mit der Vorlage gespeicherten Nutzlastdaten empfängt. Wenn keine Nutzlastdaten vorhanden sind, legen Sie diesen Wert auf NULL fest.
[out] PayloadBlobSize
Zeiger auf einen Wert, der die Größe des puffers in Bytes empfängt, die im PayloadBlob-Parameter angegeben ist. Wenn in der Vorlage keine Nutzlastdaten gespeichert sind, legen Sie diesen Wert auf 0 fest.
[out] HashValue
Adresse einer Variablen, die einen Zeiger auf den Hash der Vorlage empfängt. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf NULL fest.
[out] HashSize
Zeiger auf einen Wert, der die Größe des durch den HashValue-Parameter angegebenen Hashs in Bytes enthält. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf 0 fest.
[out] RejectDetail
Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen empfängt, wenn ein Erfassungsfehler verhindert, dass das Modul einen Abgleichsvorgang ausführt. Wenn die letzte Erfassung erfolgreich war, legen Sie diesen Parameter auf 0 fest. Die folgenden Werte werden für die Fingerabdruckerfassung definiert
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Ein obligatorischer Zeigerparameter ist NULL. |
|
Der im SubFactor-Parameter angegebene Wert ist nicht korrekt. |
|
Der Featuresatz erfüllte nicht die internen Anforderungen des Engineadapters für einen Überprüfungsvorgang. Weitere Informationen zum Fehler werden durch den RejectDetail-Parameter angegeben. |
|
Der Featuresatz in der Pipeline entspricht einem in der Datenbank gespeicherten Featuresatz, entspricht aber nicht der Kombination von Werten, die in den Parametern Identity und SubFactor übergeben werden. |
Hinweise
Der SubFactor-Parameter gibt den Teilfaktor an, der der biometrischen Vorlage zugeordnet ist. Das biometrische Windows-Framework unterstützt nur die Fingerabdruckerfassung und kann die folgenden Konstanten verwenden, um Untertypinformationen darzustellen.
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_SUBTYPE_ANY
Versuchen Sie nicht, den für den SubFactor-Parameter angegebenen Wert zu überprüfen. Der Windows-Biometrische Dienst ü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 gegebenenfalls.
Der hashwert, der von dieser Funktion zurückgegeben wird, sofern vorhanden, ist der Hash der Registrierungsvorlage in der Datenbank, nicht die übereinstimmende Vorlage, die an die Pipeline angefügt ist.
Die Puffer PayloadBlob und HashValue werden vom Moduladapter verwaltet, nachdem die EngineAdapterIdentifyFeatureSet-Funktion erfolgreich zurückgegeben wurde. Der Moduladapter muss die Pufferadresse für diese Pipeline bis zum nächsten Aufruf von EngineAdapterClearContext gültig bleiben.
Beispiele
Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterVerifyFeatureSet
//
// Purpose:
// Compares the template in the current feature set with a specific
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - GUID or SID that is expected to match that of the
// template recovered from the database
// SubFactor - A WINBIO_BIOMETRIC_SUBTYPE value that is expected
// to match that of the template recovered from the
// database
// Match - A Boolean value that specifies whether the Identity
// and SubFactor parameters match those of the template
// recovered from the database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified in the
// PayloadBlob parameter
// HashValue - Hash of the template
// HashSize - Size, in bytes, of the hash specified by the
// HashValue parameter
// RejectDetail - Receives additional information if a capture failure
// prevents the engine from performing a matching operation
//
static HRESULT
WINAPI
EngineAdapterVerifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_IDENTITY Identity,
__in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PBOOLEAN Match,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
WINBIO_REJECT_DETAIL rejectDetail = 0;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(Match) ||
!ARGUMENT_PRESENT(PayloadBlob) ||
!ARGUMENT_PRESENT(PayloadBlobSize) ||
!ARGUMENT_PRESENT(HashValue) ||
!ARGUMENT_PRESENT(HashSize) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Initialize the return values.
*Match = FALSE;
*PayloadBlob = NULL;
*PayloadBlobSize = 0;
*HashValue = NULL;
*HashSize = 0;
*RejectDetail = 0;
// The biometric unit cannot perform verification or identification
// operations while it is performing an enrollment sequence.
if (context->Enrollment.InProgress == TRUE)
{
hr = WINBIO_E_ENROLLMENT_IN_PROGRESS;
goto cleanup;
}
// Query the storage adapter to determine whether the Identity and
// SubFactor combination specified on input are in the database. If
// they are not, there can be no match. WbioStorageQueryBySubject
// is a wrapper function defined in the Winbio_adapter.h header file.
hr = WbioStorageQueryBySubject( Pipeline, Identity, SubFactor);
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
goto cleanup;
}
// Position the cursor on the first record in the database.
// WbioStorageFirstRecord is a wrapper function defined in the
// Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the current template record for the Identity and SubFactor
// combination specified on input.
hr = WbioStorageGetCurrentRecord( Pipeline, &thisRecord );
if (FAILED(hr))
{
goto cleanup;
}
// Call a custom function (_AdapterCompareTemplateToCurrentFeatureSet)
// to compare the feature set attached to the pipeline with the template
// retrieved from the database.
// If the template and feature set do not match, return WINBIO_E_NO_MATCH
// and set the Match parameter to FALSE.
// If your custom function cannot process the feature set, return
// WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
hr = _AdapterCompareTemplateToCurrentFeatureSet(
context,
context->FeatureSet,
context->FeatureSetSize,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
&match,
RejectDetail
);
if (FAILED(hr))
{
goto cleanup;
}
// If there is a match and if your engine adapter supports template
// hashing, call a custom function (_AdapterGenerateHashForTemplate)
// to calculate the hash. Save the hash value in the context area of
// the engine adapter.
// Skip this step if your adapter does not support template hashing.
hr = _AdapterGenerateHashForTemplate(
context,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
context->HashBuffer,
&context->HashSize
);
if (FAILED(hr))
{
goto cleanup;
}
// Set the return values.
*Match = TRUE;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
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 (einschließlich Winbio_adapter.h) |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für