WinBioControlUnitPrivileged-Funktion (winbio.h)
Ermöglicht dem Aufrufer, privilegierte, vom Anbieter definierte Steuerungsvorgä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. Der Client muss diese Funktion aufrufen, um erweiterte Anbietervorgänge auszuführen, die erhöhte Zugriffsrechte erfordern. Wenn keine Berechtigungen erforderlich sind, kann der Client die WinBioControlUnit-Funktion aufrufen.
Syntax
HRESULT WinBioControlUnitPrivileged(
[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 Aufrufer verfügt nicht über die Berechtigung zum Ausführen des Vorgangs, oder die Sitzung wurde nicht mit WINBIO_FLAG_MAINTENANCE geöffnet. |
|
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
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 dieser Funktion. Um einen Vorgang auszuführen, der keine Berechtigungen erfordert, sollte der Client die WinBioControlUnit-Funktion aufrufen.
Sie müssen WinBioLockUnit aufrufen, bevor Sie WinBioControlUnitPrivileged aufrufen. Die WinBioLockUnit-Funktion erstellt einen gesperrten Bereich, in dem vom Anbieter definierte Vorgänge sicher ausgeführt werden können.
Um diese Funktion erfolgreich aufzurufen, muss das Sitzungshandle durch Angabe von WINBIO_FLAG_MAINTENANCE geöffnet worden sein. Nur die Konten "Administratoren" und "Lokales System" verfügen über die erforderlichen Berechtigungen.
Um WinBioControlUnitPrivileged synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wurde. Die Funktion wird blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler auftritt.
Um WinBioControlUnitPrivileged 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 |