Share via

WinBioControlUnitPrivileged-Funktion (winbio.h)

  • Artikel

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.

Wert Bedeutung
WINBIO_COMPONENT_SENSOR
 Senden Sie den Befehl an den Sensoradapter.
WINBIO_COMPONENT_ENGINE
 Senden Sie den Befehl an den Engine-Adapter.
WINBIO_COMPONENT_STORAGE
 Senden Sie den Befehl an den Speicheradapter.

[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
E_HANDLE
 Das Sitzungshandle ist ungültig.
E_INVALIDARG
 Der im ControlCode-Parameter angegebene Wert wird nicht erkannt.
E_POINTER
 Die Parameter SendBuffer, ReceiveBuffer, ReceiveDataSize, OperationStatus können nicht NULL sein.
E_ACCESSDENIED
 Der Aufrufer verfügt nicht über die Berechtigung zum Ausführen des Vorgangs, oder die Sitzung wurde nicht mit WINBIO_FLAG_MAINTENANCE geöffnet.
E_INVALIDARG
 Der im ControlCode-Parameter angegebene Wert wird nicht erkannt.
WINBIO_E_LOCK_VIOLATION
 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.
Um Speicherverluste zu verhindern, müssen Sie WinBioFree aufrufen, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie sie verwendet haben.

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

Weitere Informationen

WinBioControlUnit

WinBioLockUnit