PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN fonction de rappel (winbio_adapter.h)
Appelée par la fonction SensorAdapterPushDataToEngine implémentée par l’adaptateur de capteur pour informer l’adaptateur moteur d’accepter un échantillon biométrique brut et d’extraire un ensemble de fonctionnalités. L’ensemble de fonctionnalités peut être utilisé pour la correspondance ou l’inscription.
Syntaxe
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
)
{...}
Paramètres
[in, out] Pipeline
Pointeur vers une structure WINBIO_PIPELINE associée à l’unité biométrique effectuant l’opération.
[in] SampleBuffer
Pointeur vers une structure WINBIO_BIR qui contient l’échantillon biométrique à traiter.
[in] SampleSize
Valeur SIZE_T qui contient la taille de la structure WINBIO_BIR retournée dans le paramètre SampleBuffer .
[in] Purpose
Masque de bits WINBIO_BIR_PURPOSE qui spécifie l’utilisation prévue de l’exemple. La structure WINBIO_BIR_PURPOSE spécifie l’objectif pour lequel les données de capture doivent être utilisées et (par conséquent) comment elles doivent être optimisées. Il peut s’agir d’un or au niveau du bit des valeurs suivantes :
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[out] RejectDetail
Pointeur vers une valeur WINBIO_REJECT_DETAIL qui reçoit des informations supplémentaires sur l’échec du traitement d’un échantillon biométrique. Si l’opération a réussi, ce paramètre est défini sur zéro. Les valeurs suivantes sont définies pour les exemples d’empreintes digitales :
- 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
Valeur retournée
Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle doit retourner l’une des valeurs HRESULT suivantes pour indiquer l’erreur.
| Code de retour | Description |
|---|---|
|
L’argument SampleSize ne peut pas être égal à zéro. L’argument Objectif doit être au niveau du bit OR des valeurs répertoriées dans la description du paramètre. |
|
Les arguments Pipeline, SampleBuffer et RejectDetail ne peuvent pas être NULL. |
|
L’opération n’a pas pu être effectuée en raison d’une mémoire insuffisante. |
|
Les données n’ont pas pu être traitées pour créer l’ensemble de fonctionnalités requis. RejectDetail contient des informations supplémentaires sur l’échec. |
Remarques
L’ensemble de fonctionnalités créé en appelant cette fonction est conservé dans le pipeline d’unités biométriques après le retour de la fonction. Il remplace tous les ensembles de fonctionnalités précédents.
L’implémentation de l’adaptateur de capteur de la fonction SensorAdapterPushDataToEngine doit utiliser la fonction wrapper suivante (définie dans Winbio_adapter.h) pour appeler EngineAdapterAcceptSampleData :
HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);
La structure WINBIO_BIR passée dans le paramètre SampleBuffer est la propriété de l’adaptateur de capteur. Étant donné que l’adaptateur de capteur contrôle la durée de vie de l’objet WINBIO_BIR , la fonction EngineAdapterAcceptSampleData ne doit pas tenter de libérer la structure ou d’enregistrer un pointeur vers celle-ci. En n’enregistrant pas le pointeur, vous empêchez d’autres parties de l’adaptateur de moteur de tenter d’utiliser la structure WINBIO_BIR après que la fonction EngineAdapterAcceptSampleData est retournée.
Si le champ Offset du membre StandardDataBlock de la structure WINBIO_BIR est supérieur à zéro (indiquant que le bir contient un échantillon biométrique au format de données standard), le champ BiometricDataFormat du membre HeaderBlock doit être défini comme suit :
- Le champ Propriétaire doit être WINBIO_ ANSI_381_FORMAT_OWNER.
- Le champ Type doit être WINBIO_ANSI_381_FORMAT_TYPE.
L’infrastructure biométrique Windows part également du principe que le membre HeaderBlock (structure WINBIO_BIR_HEADER ) contient les valeurs DataFlags et Purpose utilisées par l’adaptateur de capteur pour capturer l’exemple.
Les capteurs d’empreintes digitales qui traitent des échantillons d’empreintes digitales et rejettent les balayages incorrects dans l’adaptateur moteur doivent également utiliser des valeurs valides pour WINBIO_BIR_PURPOSE.
Exemples
Le pseudo-code suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 7 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 R2 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winbio_adapter.h (include Winbio_adapter.h) |