Freigeben über


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.

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.
WINBIO_E_INVALID_CONTROL_CODE
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

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.
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

WinBioControlUnitPrivileged

WinBioLockUnit