PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN Rückruffunktion (winbio_adapter.h)
Wird vom Windows Biometric Framework aufgerufen, um eine Vorlage aus dem aktuellen Featuresatz zu erstellen und eine übereinstimmende Vorlage in der Datenbank zu suchen. Wenn eine Übereinstimmung gefunden werden kann, muss der Moduladapter die Parameter Identity, SubFactor, PayloadBlob mit den entsprechenden Informationen aus der gespeicherten Vorlage füllen.
Syntax
PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN PibioEngineIdentifyFeatureSetFn;
HRESULT PibioEngineIdentifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[out] PWINBIO_IDENTITY Identity,
[out] PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
[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.
[out] Identity
Zeiger auf eine WINBIO_IDENTITY-Struktur , die die GUID oder SID der aus der Datenbank wiederhergestellten Vorlage enthält. Dieser Wert wird nur zurückgegeben, wenn eine Übereinstimmung gefunden wird.
[out] SubFactor
Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der den der Vorlage in der Datenbank zugeordneten Unterfaktor empfängt. Weitere Details finden Sie im Abschnitt „Anmerkungen“. Dieser Wert wird nur zurückgegeben, wenn eine Übereinstimmung gefunden wird.
[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 eine Variable, die die Größe des puffers in Bytes empfängt, die durch den PayloadBlob-Parameter angegeben wird. Wenn keine Nutzlastdaten vorhanden sind, legen Sie diesen Wert auf 0 fest.
[out] HashValue
Adresse einer Variablen, die einen Zeiger auf den generierten Hashwert für die Vorlage empfängt. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf NULL fest.
[out] HashSize
Zeiger auf eine Variable, die die Größe des durch den HashValue-Parameter angegebenen Puffers in Bytes empfängt. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf 0 fest.
[out] RejectDetail
Zeiger auf eine Variable, die 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, um anzugeben, dass das letzte Update erfolgreich war und keine zusätzlichen Featuresätze erforderlich sind, um die Vorlage abzuschließen. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Pipelineparameter ist NULL. |
|
Der Featuresatz erfüllte nicht die internen Anforderungen des Engineadapters für einen Identifizierungsvorgang. Weitere Informationen zum Fehler werden durch den RejectDetail-Parameter angegeben. |
|
Der Featuresatz in der Pipeline entspricht keiner Identität in der Datenbank. |
Hinweise
Der Algorithmus, der zum Generieren des Vorlagenhashs verwendet wird, ist der, der vom letzten Aufruf in dieser Pipeline an EngineAdapterSetHashAlgorithm ausgewählt wurde.
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.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterIdentifyFeatureSet
//
// Purpose:
// Build a template from the current feature set and locate a matching
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - The GUID or SID of the template recovered from the
// database
// SubFactor - Sub-factor associated with the template in the
// database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified by the
// PayloadBlob parameter.
// HashValue - Hash value for the template
// HashSize - Size, in bytes, of the buffer specified by the
// HashValue parameter.
// RejectDetail - Receives additional information if a capture
// failure prevents the engine from performing a matching
// operation.
//
static HRESULT
WINAPI
EngineAdapterIdentifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__out PWINBIO_IDENTITY Identity,
__out PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
SIZE_T recordCount = 0;
SIZE_T index = 0;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(SubFactor) ||
!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.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
*SubFactor = WINBIO_SUBTYPE_NO_INFORMATION;
*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;
}
// If your adapter supports index vectors to place templates into buckets,
// call a custom function (_AdapterCreateIndexVector) to create an index
// vector from the template data in the feature set. In this example, the
// engine adapter context attached to the pipeline contains a FeatureSet
// member.
hr = _AdapterCreateIndexVector(
context,
context->FeatureSet,
context->FeatureSetSize,
indexVector,
NUMBER_OF_TEMPLATE_BINS,
RejectDetail
);
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the records in the index vector. If your adapter does not support
// index vectors (the vector length is zero), calling the WbioStorageQueryByContent
// function will retrieve all records.
// WbioStorageQueryByContent is a wrapper function in the Winbio_adapter.h
// header file.
hr = WbioStorageQueryByContent(
Pipeline,
WINBIO_SUBTYPE_ANY,
indexVector,
NUMBER_OF_TEMPLATE_BINS
);
if (FAILED(hr))
{
goto cleanup;
}
// Determine the size of the result set. WbioStorageGetRecordCount is a wrapper
// function in the Winbio_adapter.h header file.
hr = WbioStorageGetRecordCount( Pipeline, &recordCount);
if (FAILED(hr))
{
goto cleanup;
}
// Point the result set cursor at the first record. WbioStorageFirstRecord
// is a wrapper function in the Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Iterate through all records in the result set and determine which record
// matches the current feature set. WbioStorageGetCurrentRecord is a wrapper
// function in the Winbio_adapter.h header file.
for (index = 0; index < recordCount; ++index)
{
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 storage.
// 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) && hr != WINBIO_E_NO_MATCH)
{
goto cleanup;
}
if (match)
{
break;
}
hr = WbioStorageNextRecord( Pipeline );
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_MORE_RECORDS)
{
hr = S_OK;
break;
}
else
{
goto cleanup;
}
}
}
if (match)
{
// 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;
}
// Return information about the matching template to the caller.
CopyMemory( Identity, thisRecord.Identity, sizeof(WINBIO_IDENTITY));
*SubFactor = thisRecord.SubFactor;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
}
else
{
hr = WINBIO_E_UNKNOWN_ID;
}
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_UNKNOWN_ID;
}
return hr;
}
Anforderungen
| 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) |