WinBioControlUnitPrivileged-Funktion (winbio.h)

Ermöglicht dem Aufrufer, privilegierte 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. 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
);

Die Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine geöffnete 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 Einheiten-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 Hersteller definierter Code, der von der biometrischen Einheit erkannt wird, die durch den UnitId-Parameter und den vom Component-Parameter angegebenen Adapter angegeben wurde.

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 vom Parameter Component angegebenen Adapter gesendet werden. Das Format und der Inhalt des Puffers sind vom Anbieter definiert.

[in] ReceiveBufferSize

Größe des durch den ReceiveBuffer-Parameter angegebenen Puffers in Bytes.

ReceiveDataSize

Zeigen Sie auf einen SIZE_T Wert, der die Größe der Daten in Byte enthält, die in den durch den ReceiveBuffer-Parameter angegebenen Puffer geschrieben wurden.

[out, optional] OperationStatus

Zeigen Sie auf eine ganze Zahl, die einen vom Anbieter definierten Statuscode enthält, der das Ergebnis des Steuerelementvorgangs 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ögliche Werte sind die Werte in der folgenden Tabelle, sind jedoch nicht beschränkt. Eine Liste allgemeiner Fehlercodes finden Sie unter "Allgemeine HRESULT-Werte".

Bemerkungen

Anbieter, die Plug-Ins erstellen, müssen entscheiden, welche erweiterten Vorgänge privilegierte sind und welche für alle Clients verfügbar sind. Zum Ausführen eines privilegierten Vorgangs muss die Clientanwendung die WinBioControlUnitPrivileged-Funktion aufrufen. Das Windows Biometrie-Framework ermöglicht nur Clients mit den entsprechenden Zugriffsrechten, um diese Funktion aufzurufen. 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 der Sitzungshandle geöffnet worden sein, indem WINBIO_FLAG_MAINTENANCE angegeben wurde. Nur die Administratoren und lokalen Systemkonten 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 blockiert, bis der Vorgang abgeschlossen ist oder ein Fehler aufgetreten ist.

Um WinBioControlUnitPrivileged asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wurde. Das Framework weist eine WINBIO_ASYNC_RESULT Struktur zu und verwendet es, um Informationen zum Erfolg oder Fehler des Vorgangs 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 Parameter NotificationMethod der WinBioAsyncOpenSession-Funktion festgelegt haben.

• Wenn Sie sich für den Empfang von Abschlussbenachrichtigungen mithilfe eines Rückrufs entscheiden, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
• Wenn Sie mithilfe der Anwendungsnachrichtenwarteschlange Abschlussbenachrichtigungen empfangen möchten, müssen Sie den Parameter NotificationMethod auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT Zeiger auf das LPARAM-Feld der Fenstermeldung zurück.

Anforderungen

Siehe auch

WinBioControlUnit

WinBioLockUnit