WinBioGetProperty-Funktion (winbio.h)

  • Artikel

Ruft eine Sitzungs-, Einheits- oder Vorlageneigenschaft ab. Ab Windows 10 Build 1607 ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.

Syntax

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert. Öffnen Sie ein synchrones Sitzungshandle, indem Sie WinBioOpenSession aufrufen. Öffnen Sie ein asynchrones Sitzungshandle, indem Sie WinBioAsyncOpenSession aufrufen.

[in] PropertyType

Ein WINBIO_PROPERTY_TYPE Wert, der die Quelle der Eigenschafteninformationen angibt. Dies muss derzeit WINBIO_PROPERTY_TYPE_UNIT oder WINBIO_PROPERTY_TYPE_ACCOUNT sein. Weitere Informationen zu Eigenschaftentypen finden Sie unter WINBIO_PROPERTY_TYPE Konstanten.

Der WINBIO_PROPERTY_TYPE_ACCOUNT-Wert wird ab Windows 10 unterstützt.

[in] PropertyId

Ein WINBIO_PROPERTY_ID Wert, der die Eigenschaft angibt, die Sie abfragen möchten. Die folgenden Werte sind möglich.

Wert Bedeutung
WINBIO_PROPERTY_SAMPLE_HINT
 Schätzt die maximale Anzahl guter biometrischer Stichproben, die zum Ausfüllen einer Registrierungsvorlage erforderlich sind. Das Ergebnis der Eigenschaftenabfrage wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als ULONG-Wert verweist, der den Hinweis enthält.
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO
Enthält erweiterte Informationen zu den Funktionen und Attributen der Sensorkomponente, die mit einer bestimmten biometrischen Einheit verbunden ist. Das Ergebnis der Eigenschaftenabfrage wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als WINBIO_EXTENDED_SENSOR_INFO-Struktur verweist. Dieser Wert wird ab Windows 10 unterstützt.
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO
Enthält erweiterte Informationen zu den Funktionen und Attributen der Engine-Komponente, die mit einer bestimmten biometrischen Einheit verbunden ist. Das Ergebnis der Eigenschaftenabfrage wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als WINBIO_EXTENDED_ENGINE_INFO-Struktur verweist. Dieser Wert wird ab Windows 10 unterstützt.
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO
Enthält erweiterte Informationen zu den Funktionen und Attributen der Speicherkomponente, die mit einer bestimmten biometrischen Einheit verbunden ist. Das Ergebnis der Eigenschaftenabfrage wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als WINBIO_EXTENDED_STORAGE_INFO-Struktur verweist. Dieser Wert wird ab Windows 10 unterstützt.
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS
Enthält erweiterte Informationen über die status einer Registrierung, die in einer bestimmten biometrischen Einheit ausgeführt wird. Das Ergebnis der Eigenschaftenabfrage wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als WINBIO_EXTENDED_ENROLLMENT_STATUS-Struktur verweist. Wenn keine Registrierung für die biometrische Einheit ausgeführt wird, weist das TemplateStatus-Element der zurückgegebenen Struktur den Wert WINBIO_E_INVALID_OPERATION auf. Dieser Wert wird ab Windows 10 unterstützt.
WINBIO_PROPERTY_ANTI_SPOOF_POLICY
Enthält die Werte der Antispoofingrichtlinie für ein bestimmtes Benutzerkonto. Der Eigenschaftsvorgang wird in dem Puffer zurückgegeben, auf den der PropertyBuffer-Parameter als WINBIO_ANTI_SPOOF_POLICY-Struktur verweist. Dieser Wert wird ab Windows 10 unterstützt.
 

Weitere Informationen zu diesen Eigenschaften finden Sie unter WINBIO_PROPERTY Konstanten.

[in, optional] UnitId

Ein WINBIO_UNIT_ID Wert, der die biometrische Einheit identifiziert. Sie können einen Einheitenbezeichner finden, indem Sie die Funktionen WinBioEnumBiometricUnits oder WinBioLocateSensor aufrufen.

Wenn Sie WINBIO_PROPERTY_ANTI_SPOOF_POLICY als Wert für den PropertyId-Parameter angeben, geben Sie 0 für den UnitId-Parameter an. Wenn Sie eine andere Eigenschaft mit dem PropertyId-Parameter angeben, können Sie für den UnitId-Parameter nicht 0 angeben.

[in, optional] Identity

Eine WINBIO_IDENTITY-Struktur , die die SID des Kontos bereitstellt, für das Sie die Antispoofingrichtlinie abrufen möchten, wenn Sie WINBIO_PROPERTY_ANTI_SPOOF_POLICY als Wert des PropertyId-Parameters angeben.

Wenn Sie einen anderen Wert für den PropertyId-Parameter angeben, muss der Identity-ParameterNULL sein.

[in, optional] SubFactor

Reserviert. Dies muss WINBIO_SUBTYPE_NO_INFORMATION sein.

PropertyBuffer

Adresse eines Zeigers auf einen Puffer, der den Eigenschaftswert empfängt. Informationen zum Inhalt dieses Puffers für verschiedene Eigenschaften finden Sie in den Beschreibungen der Eigenschaftswerte für den PropertyId-Parameter .

[out, optional] PropertyBufferSize

Zeiger auf eine Variable, die die Größe des Puffers in Byte empfängt, auf den der PropertyBuffer-Parameter verweist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, wird ein HRESULT-Wert zurückgegeben, der den Fehler angibt. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle. Eine Liste allgemeiner Fehlercodes finden Sie unter Allgemeine HRESULT-Werte.

Rückgabecode Beschreibung
E_HANDLE
 Das vom SessionHandle-Parameter angegebene Sitzungshandle ist ungültig.
E_POINTER
 Die Argumente Identity, PropertyBuffer oder PropertyBufferSize können nicht NULL sein.
E_INVALIDARG
 Die Argumente UnitId, Identity oder SubFactor sind falsch.
WINBIO_E_INVALID_PROPERTY_TYPE
 Der Wert des PropertyType-Arguments ist falsch.
WINBIO_E_INVALID_PROPERTY_ID
 Der Wert des PropertyId-Arguments ist falsch.
WINBIO_E_LOCK_VIOLATION
 Der Aufrufer hat versucht, eine Eigenschaft abzufragen, die sich in einem gesperrten Bereich befindet.
WINBIO_E_UNSUPPORTED_PROPERTY
 Das abgefragte Objekt unterstützt die angegebene Eigenschaft nicht.
WINBIO_E_ENROLLMENT_IN_PROGRESS
 Der Vorgang konnte nicht abgeschlossen werden, da die angegebene biometrische Einheit derzeit für eine Registrierungstransaktion (nur Systempool) verwendet wird.

Hinweise

Um WinBioGetProperty synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wird. Die Funktion wird blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler auftritt. Um Speicherverluste bei synchroner Verwendung von WinBioGetProperty zu verhindern, müssen Sie WinBioFree aufrufen, um den Speicher freizugeben, auf den der PropertyBuffer-Parameter verweist, wenn Sie die im Puffer enthaltenen Daten verwendet haben.

Um WinBioGetProperty asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wurde. Das Framework ordnet eine WINBIO_ASYNC_RESULT-Struktur zu und verwendet sie, um Informationen über erfolgreiche oder fehlgeschlagene Vorgänge zurückzugeben. Wenn der Vorgang erfolgreich ist, gibt das Framework Informationen in einer geschachtelten GetProperty-Struktur zurück. Die WINBIO_ASYNC_RESULT-Struktur wird an den Anwendungsrückruf oder die Anwendungsnachrichtenwarteschlange zurückgegeben, je nachdem, welche Werte Sie im NotificationMethod-Parameter der WinBioAsyncOpenSession-Funktion festgelegt haben:

  • Wenn Sie Vervollständigungsbenachrichtigungen mithilfe eines Rückrufs erhalten möchten, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
  • Wenn Sie Vervollständigungsbenachrichtigungen mithilfe der Anwendungsnachrichtenwarteschlange empfangen möchten, müssen Sie den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT Zeiger auf das LPARAM-Feld der Fenstermeldung zurück.
Um Speicherverluste bei der asynchronen Verwendung von WinBioGetProperty zu verhindern, müssen Sie WinBioFree aufrufen, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie die Verwendung abgeschlossen haben. Die WINBIO_ASYNC_RESULT-Struktur und der Eigenschaftenpuffer belegen einen einzelnen Speicherblock, sodass Ihre Anwendung nur die Adresse der WINBIO_ASYNC_RESULT-Struktur an WinBioFree übergeben muss. Wenn Sie WinBioFree auf diese Weise aufrufen, gibt WinBioFree automatisch sowohl die WINBIO_ASYNC_RESULT-Struktur als auch den Eigenschaftenpuffer frei. Wenn Sie versuchen, den Eigenschaftenpuffer in diesem Fall separat freizugeben, reagiert die Anwendung nicht mehr.

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.h (einschließlich Winbio.h)
Bibliothek Winbio.lib
DLL Winbio.dll

Weitere Informationen

WinBioFree

WinBioSetProperty