PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN Rückruffunktion (winbio_adapter.h)
Wird von der SensorAdapterPushDataToEngine-Funktion aufgerufen, die vom Sensoradapter implementiert wird, um den Engineadapter zu benachrichtigen, eine biometrische Rohprobe zu akzeptieren und einen Featuresatz zu extrahieren. Der Featuresatz kann für den Abgleich oder die Registrierung verwendet werden.
Syntax
PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;
HRESULT PibioEngineAcceptSampleDataFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_BIR SampleBuffer,
[in] SIZE_T SampleSize,
[in] WINBIO_BIR_PURPOSE Purpose,
[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] SampleBuffer
Zeiger auf eine WINBIO_BIR Struktur, die die zu verarbeitende biometrische Stichprobe enthält.
[in] SampleSize
Ein SIZE_T Wert, der die Größe der WINBIO_BIR Struktur enthält, die im SampleBuffer-Parameter zurückgegeben wird.
[in] Purpose
Eine WINBIO_BIR_PURPOSE Bitmaske, die die beabsichtigte Verwendung des Beispiels angibt. Die WINBIO_BIR_PURPOSE-Struktur gibt den Zweck an, für den Erfassungsdaten verwendet werden sollen, und (daher) wie sie optimiert werden sollen. Dies kann ein bitweiser OR der folgenden Werte sein:
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[out] RejectDetail
Ein Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen über den Fehler bei der Verarbeitung einer biometrischen Stichprobe empfängt. Wenn der Vorgang erfolgreich war, wird dieser Parameter auf 0 festgelegt. Die folgenden Werte werden für Fingerabdruckbeispiele 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 |
|---|---|
|
Das Argument SampleSize darf nicht 0 sein. Das Argument Purpose muss ein bitweiser OR der werte sein, die in der Parameterbeschreibung aufgeführt sind. |
|
Die Argumente Pipeline, SampleBuffer und RejectDetail dürfen nicht NULL sein. |
|
Der Vorgang konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden. |
|
Die Daten konnten nicht zum Erstellen des erforderlichen Featuresatzes verarbeitet werden. Der RejectDetail enthält zusätzliche Informationen zum Fehler. |
Hinweise
Der Featuresatz, der durch aufrufen dieser Funktion erstellt wurde, wird in der Pipeline für biometrische Einheiten beibehalten, nachdem die Funktion zurückgegeben wurde. Es ersetzt alle vorherigen Featuresätze.
Die Sensoradapterimplementierung der SensorAdapterPushDataToEngine-Funktion sollte die folgende Wrapperfunktion (definiert in Winbio_adapter.h) verwenden, um EngineAdapterAcceptSampleData aufzurufen:
HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);
Die WINBIO_BIR Struktur, die im Parameter SampleBuffer übergeben wird, ist die Eigenschaft des Sensoradapters. Da der Sensoradapter die Lebensdauer des WINBIO_BIR -Objekts steuert, darf die EngineAdapterAcceptSampleData-Funktion nicht versuchen, die Struktur zuzuordnen oder einen Zeiger darauf zu speichern. Indem Sie den Zeiger nicht speichern, verhindern Sie, dass andere Teile des Moduladapters versuchen, die WINBIO_BIR-Struktur zu verwenden, nachdem die EngineAdapterAcceptSampleData-Funktion zurückgegeben wird.
Wenn das Offset-Feld des StandardDataBlock-Members der WINBIO_BIR-Struktur größer als 0 ist (was angibt, dass die BIR eine biometrische Stichprobe im Standarddatenformat enthält), muss das Feld BiometricDataFormat des HeaderBlock-Elements wie folgt festgelegt werden:
- Das Feld Besitzer muss WINBIO_ ANSI_381_FORMAT_OWNER sein.
- Das Feld Typ muss WINBIO_ANSI_381_FORMAT_TYPE sein.
Das Windows Biometric Framework geht auch davon aus, dass der HeaderBlock-Member (eine WINBIO_BIR_HEADER-Struktur ) die DataFlags - und Purpose-Werte enthält, die vom Sensoradapter zum Erfassen des Beispiels verwendet werden.
Fingerabdrucksensoren, die Fingerabdruckproben verarbeiten und fehlerhafte Wischvorgänge im Engine-Adapter ablehnen, sollten auch gültige Werte für WINBIO_BIR_PURPOSE verwenden.
Beispiele
Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
// Notifies the engine adapter to accept a raw biometric sample and
// extract a feature set.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation.
// SampleBuffer - Contains the biometric sample to be processed.
// SampleSize - Size of the structure returned in the SampleBuffer
// parameter.
// Purpose - Specifies the intended use of the sample.
// RejectDetail - Receives additional information about the failure,
// if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
PUCHAR featureSet = NULL;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(SampleBuffer) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Verify that input arguments are valid.
if (SampleSize == 0 ||
Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
{
hr = E_INVALIDARG;
goto cleanup;
}
// Release any feature set currently attached to the pipeline before
// creating a new feature set.
if (context->FeatureSet != NULL)
{
_AdapterRelease(context->FeatureSet);
context->FeatureSet = NULL;
context->FeatureSetSize = 0;
}
// An actual engine adapter would here process the contents of the sample
// buffer, generate a feature set suitable for the purpose(s) specified
// by the Purpose parameter, and attach the feature set to the pipeline.
// The following trivial example, however, creates a feature set simply
// by making an exact copy of the raw sample.
// If the sample data cannot be processed, return an HRESULT error code
// of WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
if (featureSet == NULL)
{
hr = E_OUTOFMEMORY;
goto cleanup;
}
RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
context->FeatureSet = featureSet;
featureSet = NULL;
context->FeatureSetSize = SampleSize;
cleanup:
if (FAILED(hr))
{
if (featureSet != NULL)
{
_AdapterRelease(featureSet);
}
}
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) |