IDisplayDeviceInterop::CreateSharedHandle-Methode (windows.devices.display.core.interop.h)

Artikel
11/20/2024

Für ein DisplaySurface- oder ein DisplayFence--Objekt erstellt ein freigegebenes Handle, das für die Interoperabilität mit Direct3D oder anderen Grafik-APIs verwendet werden kann.

Syntax

HRESULT CreateSharedHandle(
  IInspectable              *pObject,
  const SECURITY_ATTRIBUTES *pSecurityAttributes,
  DWORD                     Access,
  HSTRING                   Name,
  HANDLE                    *pHandle
);

Parameter

pObject

Ein Zeiger auf die IUnknown Schnittstelle eines DisplaySurface- oder eines DisplayFence--Objekts.

pSecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur, die zwei separate, aber verwandte Datenmember enthält: einen optionalen Sicherheitsdeskriptor und einen booleschen Wert, der bestimmt, ob untergeordnete Prozesse das zurückgegebene Handle erben können.

Legen Sie diesen Parameter auf nullptr fest, wenn untergeordnete Prozesse, die von der Anwendung erstellt werden, möglicherweise nicht erben sollen, die von CreateSharedHandle-zurückgegeben werden, und wenn Sie möchten, dass die Ressource, die dem zurückgegebenen Handle zugeordnet ist, einen Standardsicherheitsdeskriptor abrufen soll.

Der lpSecurityDescriptor Element der Struktur gibt einen SECURITY_DESCRIPTOR für die Ressource an. Legen Sie dieses Element auf nullptr fest, wenn die Laufzeit der Ressource, die dem zurückgegebenen Handle zugeordnet ist, einen Standardsicherheitsdeskriptor zuweisen soll. Die Zugriffssteuerungslisten (ACLs) im Standardsicherheitsdeskriptor für die Ressource stammen aus dem primären oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsberechtigungen.

Access

Die angeforderten Zugriffsrechte für die Ressource. Zusätzlich zu den generischen Zugriffsrechtenkann eine Oberfläche diese Werte verwenden.

DXGI_SHARED_RESOURCE_READ (0x800000000L). Gibt den Lesezugriff auf die Ressource an.
DXGI_SHARED_RESOURCE_WRITE (1). Gibt schreibzugriff auf die Ressource an.

Sie können diese Werte mithilfe eines bitweisen OR-Vorgangs kombinieren.

Wenn pObject- ein Zaun ist, müssen Sie GENERIC_ALLverwenden.

Name

Typ: LPCWSTR-

Eine mit Null beendete Unicode-Zeichenfolge, die den Namen enthält, der dem freigegebenen Heap zugeordnet werden soll. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn Name dem Namen einer vorhandenen Ressource entspricht, schlägt CreateSharedHandle- mit DXGI_ERROR_NAME_ALREADY_EXISTSfehl. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernel-Objektnamespaces. Schnelle Benutzerumschaltung wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien für Terminaldienste entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Object Namespaces.

pHandle

Ein Zeiger auf einen HANDLE, der das neue freigegebene Handle empfängt.

Rückgabewert

Typ: HRESULT-

Diese Methode gibt S_OK zurück, wenn sie erfolgreich war, andernfalls ein Fehlercode, der angibt, warum die Methode fehlgeschlagen ist. Wenn dies erfolgreich war, zeigt pHandle- immer auf den neu erstellten Handle.

Bemerkungen

Das von CreateSharedHandle- zurückgegebene Handle kann in jeder Funktion verwendet werden, die ein "NT-Handle" für eine GPU-Oberfläche oder einen Zaun erfordert (je nachdem, welches Objekt übergeben wurde), vorausgesetzt, der Aufrufer wurde Zugriff gewährt. Hier sind einige Beispiele.

Freigeben von Oberflächen und Zäunen mit Direct3D 12 mithilfe von ID3D12Device::OpenSharedHandle.
Freigeben von Oberflächen mit Direct3D 11 mit ID3D11Device1::OpenSharedResource.
Teilen Sie Zäune mit Direct3D 11 mit ID3D11Device5::OpenSharedFence.

Mehrere Prozesse können Überhandles desselben Objekts verfügen, wodurch die Verwendung des Objekts für die Synchronisierung von Prozessen oder die Freigabe ermöglicht wird. Die folgenden Objektfreigabemechanismen sind verfügbar.

Ein untergeordneter Prozess, der von der funktion CreateProcess erstellt wird, kann ein Handle an ein Oberflächen- oder Zaunobjekt erben, wenn der pSecurityAttributes Parameter von CreateSharedHandle die Vererbung ermöglicht.
Ein Prozess kann das Objekthandle in einem Aufruf der DuplicateHandle--Funktion angeben, um ein dupliziertes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann.
Ein Prozess kann den Namen des Objekts in einem Aufruf des OpenSharedHandle- oder ID3D12Device::OpenSharedHandleByName-Funktion angeben.

Verwenden Sie die CloseHandle--Funktion, um den Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Objekt wird zerstört, wenn der letzte Handle geschlossen wurde und der letzte Schnittstellenverweis freigegeben wurde.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10 Build 20348
mindestens unterstützte Server-	Windows 10 Build 20348
Zielplattform-	Fenster
Header-	windows.devices.display.core.interop.h
Library	d3d12.lib
DLL-	d3d12.dll

Freigeben über