IDXGIResource1::CreateSharedHandle, méthode (dxgi1_2.h)
Crée un handle pour une ressource partagée. Vous pouvez ensuite utiliser le handle retourné avec plusieurs appareils Direct3D.
Syntaxe
HRESULT CreateSharedHandle(
[in, optional] const SECURITY_ATTRIBUTES *pAttributes,
[in] DWORD dwAccess,
[in, optional] LPCWSTR lpName,
[out] HANDLE *pHandle
);
Paramètres
[in, optional] pAttributes
Pointeur vers une structure de SECURITY_ATTRIBUTES qui contient deux membres de données distincts mais associés : un descripteur de sécurité facultatif et une valeur booléenne qui détermine si les processus enfants peuvent hériter du handle retourné.
Définissez ce paramètre sur NULL si vous souhaitez que les processus enfants que l’application peut créer n’héritent pas du handle retourné par CreateSharedHandle, et si vous souhaitez que la ressource associée au handle retourné obtienne un descripteur de sécurité par défaut.
Le membre lpSecurityDescriptor de la structure spécifie un SECURITY_DESCRIPTOR pour la ressource. Définissez ce membre sur NULL si vous souhaitez que le runtime attribue un descripteur de sécurité par défaut à la ressource associée au handle retourné. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut pour la ressource proviennent du jeton principal ou d’emprunt d’identité du créateur. Pour plus d’informations, consultez Synchronisation des droits d’accès et de sécurité des objets.
[in] dwAccess
Droits d’accès demandés à la ressource. En plus des droits d’accès génériques, DXGI définit les valeurs suivantes :
- DXGI_SHARED_RESOURCE_READ ( 0x80000000L ) : spécifie l’accès en lecture à la ressource.
- DXGI_SHARED_RESOURCE_WRITE ( 1 ) : spécifie l’accès en écriture à la ressource.
[in, optional] lpName
Nom de la ressource à partager. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.
Vous aurez besoin du nom de la ressource si vous appelez la méthode ID3D11Device1::OpenSharedResourceByName pour accéder à la ressource partagée par son nom. Si vous appelez plutôt la méthode ID3D11Device1::OpenSharedResource1 pour accéder à la ressource partagée par handle, définissez ce paramètre sur NULL.
Si lpName correspond au nom d’une ressource existante, CreateSharedHandle échoue avec DXGI_ERROR_NAME_ALREADY_EXISTS. Cela se produit parce que ces objets partagent le même espace de noms.
Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception de la barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets du noyau. La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour Terminal Services afin que les applications puissent prendre en charge plusieurs utilisateurs.
L’objet peut être créé dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.
[out] pHandle
Pointeur vers une variable qui reçoit la valeur NT HANDLE pour la ressource à partager. Vous pouvez utiliser ce handle dans les appels pour accéder à la ressource.
Valeur retournée
Retourne S_OK en cas de réussite ; sinon, retourne l’une des valeurs suivantes :
- DXGI_ERROR_INVALID_CALL si l’un des paramètres n’est pas valide.
- DXGI_ERROR_NAME_ALREADY_EXISTS si le nom fourni de la ressource à partager est déjà associé à une autre ressource.
- E_ACCESSDENIED si l’objet est créé dans un espace de noms protégé.
- E_OUTOFMEMORY si la mémoire n’est pas suffisante pour créer le handle.
- Éventuellement d’autres codes d’erreur décrits dans la rubrique DXGI_ERROR .
Notes
CreateSharedHandle retourne uniquement le handle NT lorsque vous avez créé la ressource comme partagée et spécifié qu’elle utilise des handles NT (autrement dit, vous définissez les indicateurs D3D11_RESOURCE_MISC_SHARED_NTHANDLE et D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX ). Si vous avez créé la ressource en tant que ressource partagée et spécifié qu’elle utilise des handles NT, vous devez utiliser CreateSharedHandle pour obtenir un handle pour le partage. Dans ce cas, vous ne pouvez pas utiliser la méthode IDXGIResource::GetSharedHandle , car elle échoue.
Vous pouvez passer le handle que CreateSharedHandle retourne dans un appel à la méthode ID3D11Device1::OpenSharedResource1 pour donner à un appareil l’accès à une ressource partagée que vous avez créée sur un autre appareil.
Étant donné que le handle retourné par CreateSharedHandle est un handle NT, vous pouvez utiliser le handle avec CloseHandle, DuplicateHandle, etc. Vous ne pouvez appeler CreateSharedHandle qu’une seule fois pour une ressource partagée ; Les appels ultérieurs échouent. Si vous avez besoin de plus de handles pour la même ressource partagée, appelez DuplicateHandle. Lorsque vous n’avez plus besoin du handle de ressource partagée, appelez CloseHandle pour fermer le handle, afin d’éviter les fuites de mémoire.
Si vous passez un nom pour la ressource à lpName lorsque vous appelez CreateSharedHandle pour partager la ressource, vous pouvez ensuite passer ce nom dans un appel à la méthode ID3D11Device1::OpenSharedResourceByName pour accorder à un autre appareil l’accès à la ressource partagée. Si vous utilisez une ressource nommée, un utilisateur malveillant peut utiliser cette ressource nommée avant de le faire et empêcher le démarrage de votre application. Pour éviter cette situation, créez une ressource nommée de manière aléatoire et stockez le nom afin qu’il ne puisse être obtenu que par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cette fin. Pour limiter votre application à un instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.
Si vous avez créé la ressource comme partagée et que vous n’avez pas spécifié qu’elle utilise des handles NT, vous ne pouvez pas utiliser CreateSharedHandle pour obtenir un handle pour le partage, car CreateSharedHandle échoue.
Exemples
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.
Spécifications
| Client minimal pris en charge | Windows 8 et mise à jour de plateforme pour Windows 7 [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2012 et Platform Update pour Windows Server 2008 R2 [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | dxgi1_2.h |
| Bibliothèque | Dxgi.lib |