IDXGIResource1::CreateSharedHandle-Methode (dxgi1_2.h)
Erstellt einen Handle zu einer freigegebenen 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 Datenelemente enthält: ein optionaler Sicherheitsdeskriptor und ein boolescher Wert, der bestimmt, ob untergeordnete Prozesse den zurückgegebenen Handle erben können.
Legen Sie diesen Parameter auf NULL fest, wenn sie untergeordnete Prozesse erstellen möchten, die die Anwendung möglicherweise nicht erbt, die von CreateSharedHandle zurückgegeben wird, und wenn die Ressource, die dem zurückgegebenen Handle zugeordnet ist, einen Standardsicherheitsdeskriptor abrufen soll.
Das lpSecurityDescriptor-Element der Struktur gibt einen SECURITY_DESCRIPTOR für die Ressource an. Legen Sie dieses Element auf NULL fest, wenn Die Laufzeit dem zurückgegebenen Handle eine Standardsicherheitsbeschreibung zuweisen soll. Die ACLs im Standardsicherheitsdeskriptor für die Ressource stammen aus dem primären oder Identitätstoken des Erstellers. Weitere Informationen finden Sie unter "Synchronisierungsobjektsicherheit und Zugriffsrechte".
[in] dwAccess
Die angeforderten Zugriffsrechte für die Ressource. Zusätzlich zu den generischen Zugriffsrechten definiert 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. Der Namevergleich ist Groß-/Kleinschreibung.
Sie benötigen den Ressourcennamen, wenn Sie die ID3D11Device1::OpenSharedResourceByName-Methode aufrufen, um auf die freigegebene Ressource nach Name 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_EXISTS fehl. Dies tritt auf, da diese Objekte denselben Namespace teilen.
Der Name kann über ein Präfix "Global" oder "Local" verfügen, um das Objekt im globalen oder Sitzungsnamespace explizit zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen enthalten, außer dem Backslashzeichen (\). Weitere Informationen finden Sie unter Kernel-Objekt-Namespaces. Schnelle Benutzerwechsel werden mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien entsprechen, die für Terminaldienste beschrieben werden, sodass Anwendungen mehrere Benutzer unterstützen können.
Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Objektnamespaces.
[out] pHandle
Ein Zeiger auf eine Variable, die den NT HANDLE-Wert an die Ressource empfängt, die freigegeben werden soll. Sie können diesen Handle in Aufrufen verwenden, um auf die Ressource zuzugreifen.
Rückgabewert
Gibt S_OK zurück, wenn es erfolgreich ist; andernfalls gibt einen der folgenden Werte zurück:
- DXGI_ERROR_INVALID_CALL , wenn eine 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 nicht verfügbar ist, um den Handle zu erstellen.
- Möglicherweise andere Fehlercodes, die im Thema DXGI_ERROR beschrieben werden.
Hinweise
CreateSharedHandle gibt nur den NT-Handle zurück, wenn Sie die Ressource als freigegeben erstellt und angegeben haben, dass es NT-Handle verwendet (das heißt, 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 es NT-Handle verwendet, müssen Sie CreateSharedHandle verwenden, um einen Handle für die Freigabe abzurufen. In dieser Situation können Sie die IDXGIResource::GetSharedHandle-Methode nicht verwenden, da sie fehlschlägt.
Sie können den Handle übergeben, den CreateSharedHandle in einem Aufruf an die ID3D11Device1::OpenSharedResource1-Methode zurückgibt, um einem gerät Zugriff auf eine freigegebene Ressource zu geben, die Sie auf einem anderen Gerät erstellt haben.
Da der Handle, den CreateSharedHandle zurückgibt, ein NT-Handle ist, können Sie den Handle mit CloseHandle, DuplicateHandle usw. verwenden. Sie können CreateSharedHandle nur einmal für eine freigegebene Ressource aufrufen; späteren Aufrufen schlägt fehl. Wenn Sie mehr Handle für dieselbe freigegebene Ressource benötigen, rufen Sie DuplikatHandle auf. Wenn Sie den freigegebenen Ressourcenhandpunkt nicht mehr benötigen, rufen Sie CloseHandle auf, um den Handle zu schließen, um Speicherlecks 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 an die 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 ausführen und verhindern, dass Ihre App gestartet wird. Um diese Situation zu verhindern, erstellen Sie eine zufällig benannte Ressource, und speichern Sie den Namen, damit sie 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 es NT-Handle verwendet, können Sie createSharedHandle nicht verwenden, um einen Handle für die Freigabe abzurufen, 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
| Unterstützte Mindestversion (Client) | Windows 8 und Plattformupdate für Windows 7 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 und Plattformupdate für Windows Server 2008 R2 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | dxgi1_2.h |
| Bibliothek | Dxgi.lib |