IDXGIResource1::CreateSharedHandle-Methode (dxgi1_2.h)
Erstellt ein Handle für eine freigegebene Ressource. Anschließend können Sie den zurückgegebenen Handle mit mehreren Direct3D-Geräten verwenden.
Syntax
HRESULT CreateSharedHandle(
[in, optional] const SECURITY_ATTRIBUTES *pAttributes,
[in] DWORD dwAccess,
[in, optional] LPCWSTR lpName,
[out] HANDLE *pHandle
);
Parameter
[in, optional] pAttributes
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 NULL- fest, wenn untergeordnete Prozesse, die von der Anwendung erstellt werden, möglicherweise nicht erben sollen, das von CreateSharedHandlezurückgegebene Handle zurückgegeben wird, 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 NULL- fest, wenn die Laufzeit der Ressource, die dem zurückgegebenen Handle zugeordnet ist, einen Standardsicherheitsdeskriptor zuweisen soll. Die ACLs im Standardsicherheitsdeskriptor für die Ressource stammen aus dem primären oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
[in] dwAccess
Die angeforderten Zugriffsrechte für die Ressource. Zusätzlich zu den generischen Zugriffsrechtendefiniert DXGI die folgenden Werte:
- DXGI_SHARED_RESOURCE_READ ( 0x800000000L ) – gibt lesezugriff auf die Ressource an.
- DXGI_SHARED_RESOURCE_WRITE ( 1 ) – gibt schreibzugriff auf die Ressource an.
[in, optional] lpName
Der Name der ressource, die freigegeben werden soll. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.
Sie benötigen den Ressourcennamen, wenn Sie die ID3D11Device1::OpenSharedResourceByName Methode aufrufen, um auf die freigegebene Ressource anhand des Namens zuzugreifen. Wenn Sie stattdessen die ID3D11Device1::OpenSharedResource1 Methode aufrufen, um auf die freigegebene Ressource zuzugreifen, legen Sie diesen Parameter auf NULL-fest.
Wenn lpName- mit dem Namen einer vorhandenen Ressource übereinstimmt, 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 Object Namespaces. 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.
[out] pHandle
Ein Zeiger auf eine Variable, die den NT HANDLE-Wert an die freizugebende Ressource empfängt. Sie können dieses Handle in Aufrufen verwenden, um auf die Ressource zuzugreifen.
Rückgabewert
Gibt S_OK zurück, wenn dies erfolgreich ist; andernfalls gibt einen der folgenden Werte zurück:
- DXGI_ERROR_INVALID_CALL, wenn einer der Parameter ungültig ist.
- DXGI_ERROR_NAME_ALREADY_EXISTS, wenn der angegebene Name der zu teilenden Ressource bereits einer anderen Ressource zugeordnet ist.
- E_ACCESSDENIED, wenn das Objekt in einem geschützten Namespace erstellt wird.
- E_OUTOFMEMORY, wenn genügend Arbeitsspeicher zum Erstellen des Handles nicht verfügbar ist.
- Möglicherweise andere Fehlercodes, die im Thema DXGI_ERROR beschrieben werden.
Bemerkungen
CreateSharedHandle- gibt nur das NT-Handle zurück, wenn Sie die Ressource als freigegeben erstellt und angegeben haben, dass sie NT-Handles verwendet (d. h., Sie legen die D3D11_RESOURCE_MISC_SHARED_NTHANDLE und D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX Flags fest). Wenn Sie die Ressource als freigegeben erstellt und angegeben haben, dass sie NT-Handles verwendet, müssen Sie CreateSharedHandle- verwenden, um ein Handle für die Freigabe zu erhalten. In diesem Fall können Sie die IDXGIResource::GetSharedHandle--Methode nicht verwenden, da sie fehlschlägt.
Sie können das Handle übergeben, das CreateSharedHandle- in einem Aufruf des ID3D11Device1::OpenSharedResource1-Methode zurückgibt, um einem Gerät Zugriff auf eine freigegebene Ressource zu gewähren, die Sie auf einem anderen Gerät erstellt haben.
Da das Handle, das CreateSharedHandle- zurückgibt, ein NT-Handle ist, können Sie das Handle mit CloseHandle-, DuplicateHandle-usw. verwenden. Sie können CreateSharedHandle- nur einmal für eine freigegebene Ressource aufrufen; spätere Aufrufe schlagen fehl. Wenn Sie mehr Handles für dieselbe freigegebene Ressource benötigen, rufen Sie DuplicateHandle-auf. Wenn Sie das freigegebene Ressourcenhandle nicht mehr benötigen, rufen Sie CloseHandle- auf, um Speicherverluste zu vermeiden.
Wenn Sie einen Namen für die Ressource an lpName- übergeben, wenn Sie CreateSharedHandle- aufrufen, um die Ressource freizugeben, können Sie diesen Namen anschließend in einem Aufruf der ID3D11Device1::OpenSharedResourceByName Methode übergeben, um einem anderen Gerät Zugriff auf die freigegebene Ressource zu gewähren. Wenn Sie eine benannte Ressource verwenden, kann ein böswilliger Benutzer diese benannte Ressource verwenden, bevor Sie die App starten und verhindern. Um diese Situation zu verhindern, erstellen Sie eine zufällig benannte Ressource, und speichern Sie den Namen so, dass er nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie eine Datei für diesen Zweck verwenden. Um Ihre App auf eine Instanz pro Benutzer zu beschränken, erstellen Sie eine gesperrte Datei im Profilverzeichnis des Benutzers.
Wenn Sie die Ressource als freigegeben erstellt und nicht angegeben haben, dass sie NT-Handles verwendet, können Sie CreateSharedHandle- nicht verwenden, um ein Handle für die Freigabe zu erhalten, da CreateSharedHandle- fehlschlägt.
Beispiele
ID3D11Texture2D* pTexture2D;
ID3D11Device* pDevice;
pDevice->CreateTexture2D(…, &pTexture2D); // Create the texture as shared with NT HANDLEs.
HANDLE handle;
IDXGIResource1* pResource;
pTexture2D->QueryInterface(__uuidof(IDXGIResource1), (void**) &pResource);
pResource->CreateSharedHandle(NULL,
DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE,
NULL,
&handle);
// Pass the handle to another process to share the resource.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 8 und Plattformupdate für Windows 7 [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2012 und Plattformupdate für Windows Server 2008 R2 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | dxgi1_2.h |
| Library | Dxgi.lib |