IDXGIResource1 ::CreateSharedHandle, méthode (dxgi1_2.h)
Crée un handle vers 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 SECURITY_ATTRIBUTES qui contient deux membres de données distincts mais connexes : 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 puisse créer pour ne pas hériter 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 lpSecurityDescriptor membre 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 des droits d’accès et de sécurité des objets de synchronisation.
[in] dwAccess
Droits d’accès demandés à la ressource. Outre les droits d’accès génériques , DXGI définit les valeurs suivantes :
- DXGI_SHARED_RESOURCE_READ ( 0x8000000000L ) : 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 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 du caractère de barre oblique inverse (\). Pour plus d’informations, consultez espaces de noms d’objets noyau. Le basculement rapide des utilisateurs est implémenté à l’aide de sessions Terminal Services. Les noms d’objets noyau doivent suivre les instructions décrites pour les services 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 vers la ressource à partager. Vous pouvez utiliser ce handle dans les appels pour accéder à la ressource.
Valeur de retour
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 suffisante n’est pas disponible pour créer le handle.
- Éventuellement d’autres codes d’erreur décrits dans la rubrique DXGI_ERROR.
Remarques
CreateSharedHandle retourne uniquement le handle NT lorsque vous avez créé la ressource en tant que handles partagés et spécifiés 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 partage 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 échouera.
Vous pouvez transmettre le handle qui CreateSharedHandle retourne dans un appel à la méthode ID3D11Device1 ::OpenSharedResource1 pour permettre à un appareil d’accéder à une ressource partagée que vous avez créée sur un autre appareil.
Étant donné que le handle qui CreateSharedHandle retourne est un handle NT, vous pouvez utiliser le handle avec CloseHandle, DuplicateHandle, et ainsi de suite. Vous pouvez appeler CreateSharedHandle une seule fois pour une ressource partagée ; les appels ultérieurs échouent. Si vous avez besoin de handles supplémentaires 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 à l'ID3D11Device1 ::OpenSharedResourceByName méthode pour donner à 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 commencer et empêcher votre application de démarrer. Pour éviter cette situation, créez une ressource nommée de façon aléatoire et stockez le nom afin qu’elle puisse uniquement être obtenue par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cet effet. Pour limiter votre application à une instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.
Si vous avez créé la ressource en tant que partage et 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 échouera.
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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8 et Mise à jour de plateforme pour Windows 7 [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2012 et Mise à jour de plateforme pour Windows Server 2008 R2 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | dxgi1_2.h |
| bibliothèque | Dxgi.lib |