PIBIO_ENGINE_VERIFY_FEATURE_SET_FN fonction de rappel (winbio_adapter.h)
Appelé par l’infrastructure biométrique Windows pour comparer le modèle dans l’ensemble de fonctionnalités actuel avec un modèle spécifique dans la base de données. Si les modèles sont équivalents, l’adaptateur moteur doit définir la valeur Boolean pointée par le paramètre Match sur TRUE, renvoyer le modèle correspondant dans le paramètre PayloadBlob et renvoyer un hachage du modèle dans le paramètre HashValue .
Syntaxe
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
)
{...}
Paramètres
[in, out] Pipeline
Pointeur vers une structure WINBIO_PIPELINE associée à l’unité biométrique qui effectue l’opération.
[in] Identity
Pointeur vers une structure WINBIO_IDENTITY qui contient un GUID ou un SID qui est censé correspondre à celui du modèle récupéré à partir de la base de données.
[in] SubFactor
Une valeur WINBIO_BIOMETRIC_SUBTYPE qui doit correspondre à celle du modèle récupéré à partir de la base de données. Pour plus d’informations, consultez la section Notes.
[out] Match
Pointeur vers une valeur booléenne qui spécifie si les paramètres Identity et SubFactor correspondent à ceux du modèle récupéré à partir de la base de données. TRUE spécifie que ces valeurs correspondent.
[out] PayloadBlob
Adresse d’une variable qui reçoit un pointeur vers les données de charge utile enregistrées avec le modèle. S’il n’existe aucune donnée de charge utile, définissez cette valeur sur NULL.
[out] PayloadBlobSize
Pointeur vers une valeur qui reçoit la taille, en octets, de la mémoire tampon spécifiée dans le paramètre PayloadBlob . Si aucune donnée de charge utile n’est stockée avec le modèle, définissez cette valeur sur zéro.
[out] HashValue
Adresse d’une variable qui reçoit un pointeur vers le hachage du modèle. Si l’adaptateur moteur ne prend pas en charge la génération de hachage, définissez cette valeur sur NULL.
[out] HashSize
Pointeur vers une valeur qui contient la taille, en octets, du hachage spécifié par le paramètre HashValue . Si l’adaptateur moteur ne prend pas en charge la génération de hachage, définissez cette valeur sur zéro.
[out] RejectDetail
Pointeur vers une valeur WINBIO_REJECT_DETAIL qui reçoit des informations supplémentaires si un échec de capture empêche le moteur d’effectuer une opération de correspondance. Si la capture la plus récente a réussi, définissez ce paramètre sur zéro. Les valeurs suivantes sont définies pour la capture 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 |
|---|---|
|
Un paramètre de pointeur obligatoire est NULL. |
|
La valeur spécifiée dans le paramètre SubFactor n’est pas correcte. |
|
L’ensemble de fonctionnalités ne répondait pas aux exigences internes de l’adaptateur moteur pour une opération de vérification. D’autres informations sur l’échec sont spécifiées par le paramètre RejectDetail . |
|
L’ensemble de fonctionnalités dans le pipeline correspond à celui stocké dans la base de données, mais il ne correspond pas à la combinaison de valeurs passées dans les paramètres Identity et SubFactor . |
Remarques
Le paramètre SubFactor spécifie le sous-facteur associé au modèle biométrique. Windows Biometric Framework prend uniquement en charge la capture d’empreintes digitales et peut utiliser les constantes suivantes pour représenter les informations de sous-type.
- 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
N’essayez pas de valider la valeur fournie pour le paramètre SubFactor . Le service de biométrie Windows valide la valeur fournie avant de la transmettre à votre implémentation. Si la valeur est WINBIO_SUBTYPE_NO_INFORMATION ou WINBIO_SUBTYPE_ANY, validez le cas échéant.
La valeur de hachage retournée par cette fonction, le cas échéant, est le hachage du modèle d’inscription trouvé dans la base de données, et non le modèle correspondant attaché au pipeline.
Les mémoires tampons PayloadBlob et HashValue sont détenues et gérées par l’adaptateur de moteur une fois que la fonction EngineAdapterIdentifyFeatureSet est retournée avec succès. L’adaptateur moteur doit conserver l’adresse de mémoire tampon valide, pour ce pipeline, jusqu’à l’appel suivant à EngineAdapterClearContext.
Exemples
Le pseudocode suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
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) |