IDXGIResource1::CreateSharedHandle-Methode (dxgi1_2.h)
Erstellt ein Handle für eine freigegebene Ressource. Anschließend können Sie das zurückgegebene 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 die Anwendung möglicherweise erstellt, das von CreateSharedHandle zurückgegebene Handle nicht erben sollen, und wenn die Ressource, die dem zurückgegebenen Handle zugeordnet ist, einen Standardsicherheitsdeskriptor erhalten soll.
Der lpSecurityDescriptor-Member der -Struktur gibt einen SECURITY_DESCRIPTOR für die Ressource an. Legen Sie diesen Member auf NULL fest, wenn die Runtime 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 Token oder dem Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.
[in] dwAccess
Die angeforderten Zugriffsrechte für die Ressource. Zusätzlich zu den generischen Zugriffsrechten definiert DXGI die folgenden Werte:
- DXGI_SHARED_RESOURCE_READ ( 0x80000000L ) – 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. Beim Namenvergleich wird die Groß-/Kleinschreibung beachtet.
Sie benötigen den Ressourcennamen, wenn Sie die ID3D11Device1::OpenSharedResourceByName-Methode aufrufen, um anhand des Namens auf die freigegebene Ressource zuzugreifen. Wenn Sie stattdessen die ID3D11Device1::OpenSharedResource1-Methode aufrufen, um per Handle 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 liegt daran, dass diese Objekte denselben Namespace verwenden.
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 Kernelobjektnamespaces. Der schnelle Benutzerwechsel 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 Objektnamespaces.
[out] pHandle
Ein Zeiger auf eine Variable, die den NT HANDLE-Wert für die ressource empfängt, die freigegeben werden soll. Sie können dieses Handle in Aufrufen für den Zugriff auf die Ressource verwenden.
Rückgabewert
Gibt bei erfolgreicher Ausführung S_OK zurück. Gibt andernfalls 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 ressource, die freigegeben werden soll, bereits einer anderen Ressource zugeordnet ist.
- E_ACCESSDENIED, wenn das Objekt in einem geschützten Namespace erstellt wird.
- E_OUTOFMEMORY, wenn nicht genügend Arbeitsspeicher zum Erstellen des Handles verfügbar ist.
- Möglicherweise weitere Fehlercodes, die im Thema DXGI_ERROR beschrieben werden.
Hinweise
CreateSharedHandle gibt das NT-Handle nur 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 abzurufen. In diesem Fall können Sie die IDXGIResource::GetSharedHandle-Methode nicht verwenden, da sie fehlschlägt.
Sie können das Von CreateSharedHandle zurückgegebene Handle in einem Aufruf der ID3D11Device1::OpenSharedResource1-Methode übergeben, um einem Gerät Zugriff auf eine freigegebene Ressource zu gewähren, die Sie auf einem anderen Gerät erstellt haben.
Da das von CreateSharedHandle zurückgegebene Handle 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 weitere Handles für dieselbe freigegebene Ressource benötigen, rufen Sie DuplicateHandle auf. Wenn Sie das Handle für freigegebene Ressourcen nicht mehr benötigen, rufen Sie CloseHandle auf, um das Handle zu schließen, 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 dies tun und verhindern, dass Ihre App gestartet wird. Um dies zu verhindern, erstellen Sie eine zufällig benannte Ressource, und speichern Sie den Namen, sodass sie nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie zu diesem Zweck eine Datei verwenden. Um Ihre App auf eine instance pro Benutzer zu beschränken, erstellen Sie eine gesperrte Datei im Profilverzeichnis des Benutzers.
Wenn Sie die Ressource als freigegeben erstellt haben und nicht angegeben haben, dass sie NT-Handles verwendet, können Sie createSharedHandle nicht verwenden, um ein 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 |