WinBioControlUnit-Funktion (winbio.h)
Ermöglicht dem Aufrufer, vom Anbieter definierte Kontrollvorgänge für eine biometrische Einheit auszuführen. Ab Windows 10 Build 1607 ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar. Diese Funktion wird für den Zugriff auf erweiterte Anbietervorgänge bereitgestellt, für die keine erhöhten Berechtigungen erforderlich sind. Wenn Zugriffsrechte erforderlich sind, rufen Sie die WinBioControlUnitPrivileged-Funktion auf .
Syntax
HRESULT WinBioControlUnit(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_UNIT_ID UnitId,
[in] WINBIO_COMPONENT Component,
[in] ULONG ControlCode,
PUCHAR SendBuffer,
[in] SIZE_T SendBufferSize,
PUCHAR ReceiveBuffer,
[in] SIZE_T ReceiveBufferSize,
SIZE_T *ReceiveDataSize,
[out, optional] ULONG *OperationStatus
);
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] UnitId
Ein WINBIO_UNIT_ID Wert, der die biometrische Einheit identifiziert. Dieser Wert muss der Einheits-ID entsprechen, die zuvor in der WinBioLockUnit-Funktion verwendet wurde.
[in] Component
Ein WINBIO_COMPONENT Wert, der die Komponente innerhalb der biometrischen Einheit angibt, die den Vorgang ausführen soll. Dies kann einer der folgenden Werte sein.
[in] ControlCode
Ein vom Anbieter definierter Code, der von der biometrischen Einheit erkannt wird, die durch den UnitId-Parameter und den vom Component-Parameter angegebenen Adapter angegeben wird.
SendBuffer
Adresse des Puffers, der die Steuerelementinformationen enthält, die an den vom Component-Parameter angegebenen Adapter gesendet werden sollen. Das Format und der Inhalt des Puffers sind vom Anbieter definiert.
[in] SendBufferSize
Größe des durch den SendBuffer-Parameter angegebenen Puffers in Bytes.
ReceiveBuffer
Adresse des Puffers, der informationen empfängt, die vom adapter gesendet werden, der durch den Component-Parameter angegeben wird. Das Format und der Inhalt des Puffers sind vom Anbieter definiert.
[in] ReceiveBufferSize
Größe des durch den ReceiveBuffer-Parameter angegebenen Puffers in Byte.
ReceiveDataSize
Zeiger auf einen SIZE_T Wert, der die Größe der Daten in Byte enthält, die in den vom ReceiveBuffer-Parameter angegebenen Puffer geschrieben werden.
[out, optional] OperationStatus
Zeiger auf eine ganze Zahl, die einen vom Anbieter definierten status Code enthält, der das Ergebnis des Steuerungsvorgangs angibt.
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 |
|---|---|
|
Das Sitzungshandle ist ungültig. |
|
Der im ControlCode-Parameter angegebene Wert wird nicht erkannt. |
|
Die Parameter SendBuffer, ReceiveBuffer, ReceiveDataSize, OperationStatus können nicht NULL sein. |
|
Der im ControlCode-Parameter angegebene Wert wird nicht erkannt. |
|
Die durch den UnitId-Parameter angegebene biometrische Einheit muss gesperrt werden, bevor Kontrollvorgänge ausgeführt werden können. |
Hinweise
Sie müssen WinBioLockUnit aufrufen, bevor Sie WinBioControlUnit aufrufen. Die WinBioLockUnit-Funktion erstellt einen gesperrten Bereich, in dem vom Anbieter definierte Vorgänge sicher ausgeführt werden können.
Anbieter, die Plug-Ins erstellen, müssen entscheiden, welche erweiterten Vorgänge privilegiert sind und welche für alle Clients verfügbar sind. Um einen privilegierten Vorgang auszuführen, muss die Clientanwendung die WinBioControlUnitPrivileged-Funktion aufrufen. Das Windows Biometric Framework ermöglicht nur Clients, die über die entsprechenden Zugriffsrechte verfügen, das Aufrufen von WinBioControlUnitPrivileged.
Um WinBioControlUnit 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 WinBioControlUnit asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wird. Das Framework ordnet eine WINBIO_ASYNC_RESULT-Struktur zu und verwendet sie, um Informationen über erfolgreiche oder fehlgeschlagene Vorgänge zurückzugeben. Die WINBIO_ASYNC_RESULT-Struktur wird an den Anwendungsrückruf oder an die Anwendungsnachrichtenwarteschlange zurückgegeben, abhängig vom Wert, den 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.
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 (winbio.h einschließen) |
| Bibliothek | Winbio.lib |
| DLL | Winbio.dll |