IDisplayDeviceInterop ::CreateSharedHandle, méthode (windows.devices.display.core.interop.h)

Article
11/20/2024

Pour un DisplaySurface ou un objet DisplayFence, crée un handle partagé qui peut être utilisé pour l’interopérabilité avec Direct3D ou d’autres API graphiques.

Syntaxe

HRESULT CreateSharedHandle(
  IInspectable              *pObject,
  const SECURITY_ATTRIBUTES *pSecurityAttributes,
  DWORD                     Access,
  HSTRING                   Name,
  HANDLE                    *pHandle
);

Paramètres

pObject

Pointeur vers l’interface IUnknown d’un DisplaySurface ou d’un objet DisplayFence.

pSecurityAttributes

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 nullptr 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 nullptr 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 (ACL) 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 sécurité des objets de synchronisation et droits d’accès.

Access

Droits d’accès demandés à la ressource. Outre les droits d’accès génériques , une surface peut utiliser ces valeurs.

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.

Vous pouvez combiner ces valeurs à l’aide d’une opération OR au niveau du bit.

Si pObject est une clôture, vous devez utiliser GENERIC_ALL.

Name

Type : LPCWSTR

Chaîne Unicode terminée par null qui contient le nom à associer au tas partagé. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.

Si Nom 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 barre oblique inverse (\). Pour plus d’informations, consultez espaces de noms d’objets noyau. Le basculement rapide de l’utilisateur 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 Object.

pHandle

Pointeur vers un HANDLE qui reçoit ce nouveau handle partagé.

Valeur de retour

Type : HRESULT

Cette méthode retourne S_OK si elle a réussi, sinon un code d’échec indiquant pourquoi il a échoué. Si elle a réussi, pHandle pointe toujours vers le handle nouvellement créé.

Remarques

Le handle retourné par CreateSharedHandle peut être utilisé dans n’importe quelle fonction qui nécessite un « handle NT » sur une surface gpu ou une clôture (selon l’objet passé), à condition que l’appelant ait reçu l’accès. Voici quelques exemples.

Partagez des surfaces et des clôtures avec Direct3D 12 à l’aide de ID3D12Device ::OpenSharedHandle.
Partagez des surfaces avec Direct3D 11 à l’aide de ID3D11Device1 ::OpenSharedResource.
Partagez des clôtures avec Direct3D 11 à l’aide de ID3D11Device5 ::OpenSharedFence.

Plusieurs processus peuvent avoir des handles du même objet, ce qui permet d’utiliser l’objet pour la synchronisation ou le partage entre processus. Les mécanismes de partage d’objets suivants sont disponibles.

Un processus enfant créé par la fonction CreateProcess de peut hériter d’un handle à une surface ou à un objet de clôture si le paramètre pSecurityAttributes de CreateSharedHandle active l’héritage.
Un processus peut spécifier le handle d’objet dans un appel à la fonction DuplicateHandle pour créer un handle en double qui peut être utilisé par un autre processus.
Un processus peut spécifier le nom de l’objet dans un appel à la fonction OpenSharedHandle ou id3D12Device ::OpenSharedHandleByName.

Utilisez la fonction CloseHandle pour fermer le handle. Le système ferme automatiquement le handle lorsque le processus se termine. L’objet est détruit lorsque son dernier handle a été fermé et que sa dernière référence d’interface a été libérée.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10 Build 20348
serveur minimum pris en charge	Windows 10 Build 20348
plateforme cible	Windows
d’en-tête	windows.devices.display.core.interop.h
bibliothèque	d3d12.lib
DLL	d3d12.dll

Partager via