IDXGIResource1：：CreateSharedHandle 方法 (dxgi1_2.h)

  • 项目

创建共享资源的句柄。 然后，可以将返回的句柄用于多个 Direct3D 设备。

语法

HRESULT CreateSharedHandle(
  [in, optional] const SECURITY_ATTRIBUTES *pAttributes,
  [in]           DWORD                     dwAccess,
  [in, optional] LPCWSTR                   lpName,
  [out]          HANDLE                    *pHandle
);

参数

[in, optional] pAttributes

指向 SECURITY_ATTRIBUTES 结构的指针，该结构包含两个独立但相关的数据成员：可选的安全描述符和一个布尔值，用于确定子进程是否可以继承返回的句柄。

如果希望应用程序可能创建的子进程不继承 CreateSharedHandle 返回的句柄，并且希望与返回的句柄关联的资源获取默认安全描述符，请将此参数设置为 NULL。

结构的 lpSecurityDescriptor 成员指定 资源的SECURITY_DESCRIPTOR 。 如果希望运行时将默认安全描述符分配给与返回的句柄关联的资源，请将此成员设置为 NULL 。 资源的默认安全描述符中的 ACL 来自创建者的主令牌或模拟令牌。 有关详细信息，请参阅 同步对象安全性和访问权限。

[in] dwAccess

请求的资源访问权限。 除了 通用访问权限之外，DXGI 还定义了以下值：

  • DXGI_SHARED_RESOURCE_READ ( 0x80000000L ) - 指定对资源的读取访问权限。
  • DXGI_SHARED_RESOURCE_WRITE ( 1 ) - 指定对资源的写入访问权限。
可以使用按位 OR 运算组合这些值。

[in, optional] lpName

要共享的资源的名称。 名称限制为MAX_PATH个字符。 名称比较区分大小写。

如果调用 ID3D11Device1：：OpenSharedResourceByName 方法来按名称访问共享资源，则需要资源名称。 如果改为调用 ID3D11Device1：：OpenSharedResource1 方法以通过句柄访问共享资源，请将此参数设置为 NULL。

如果 lpName 与现有资源的名称匹配， 则 CreateSharedHandle 将失败并 DXGI_ERROR_NAME_ALREADY_EXISTS。 发生这种情况的原因是这些对象共享相同的命名空间。

名称可以具有“Global”或“Local”前缀，以在全局命名空间或会话命名空间中显式创建对象。 名称的其余部分可以包含除反斜杠字符 (\) 以外的任何字符。 有关详细信息，请参阅 内核对象命名空间。 使用终端服务会话实现快速用户切换。 内核对象名称必须遵循终端服务概述的准则，以便应用程序可以支持多个用户。

可以在专用命名空间中创建 对象。 有关详细信息，请参阅 对象命名空间。

[out] pHandle

指向变量的指针，该变量接收要共享的资源的 NT HANDLE 值。 可以在调用中使用此句柄来访问资源。

返回值

如果成功，则返回S_OK;否则，返回以下值之一：

  • 如果 其中一个参数无效，DXGI_ERROR_INVALID_CALL。
  • DXGI_ERROR_NAME_ALREADY_EXISTS 提供的资源名称是否已与其他资源相关联。
  • E_ACCESSDENIED对象是否在受保护的命名空间中创建。
  • 如果没有足够的内存来创建句柄，E_OUTOFMEMORY。
  • 可能是 DXGI_ERROR 主题中描述的其他错误代码。
适用于 Windows 7 的平台更新： 在安装了适用于 Windows 7 的平台更新的 Windows 7 或 Windows Server 2008 R2 上， CreateSharedHandle 失败并出现E_NOTIMPL。 有关适用于 Windows 7 的平台更新的详细信息，请参阅 适用于 Windows 7 的平台更新。

备注

CreateSharedHandle 仅在将资源创建为共享并指定其使用 NT 句柄时返回 NT 句柄， (也就是说，) 设置 D3D11_RESOURCE_MISC_SHARED_NTHANDLE 和 D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX 标志。 如果将资源创建为共享资源，并指定它使用 NT 句柄，则必须使用 CreateSharedHandle 获取用于共享的句柄。 在这种情况下，无法使用 IDXGIResource：：GetSharedHandle 方法，因为它会失败。

可以传递 CreateSharedHandle 在调用 ID3D11Device1：：OpenSharedResource1 方法时返回的句柄，以便为设备授予对在不同设备上创建的共享资源的访问权限。

由于 CreateSharedHandle 返回的句柄是 NT 句柄，因此可以将句柄与 CloseHandle、 DuplicateHandle 等一起使用。 对于共享资源，只能调用 CreateSharedHandle 一次;稍后调用失败。 如果需要对同一共享资源使用更多句柄，请调用 DuplicateHandle。 如果不再需要共享资源句柄，请调用 CloseHandle 关闭句柄，以避免内存泄漏。

如果在调用 CreateSharedHandle 共享资源时将资源的名称传递给 lpName，则随后可以在调用 ID3D11Device1：：OpenSharedResourceByName 方法中传递此名称，以便为另一台设备授予对共享资源的访问权限。 如果使用命名资源，恶意用户可以先使用此命名资源，并阻止应用启动。 若要防止出现这种情况，请创建一个随机命名的资源并存储该名称，以便只能由授权用户获取。 或者，可以将文件用于此目的。 若要将应用限制为每个用户一个实例，请在用户的配置文件目录中创建一个锁定的文件。

如果将资源创建为共享资源，但未指定它使用 NT 句柄，则无法使用 CreateSharedHandle 获取用于共享的句柄，因为 CreateSharedHandle 将失败。

示例

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.

要求

   
最低受支持的客户端 适用于 Windows 7 的 Windows 8 和平台更新 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 和适用于 Windows Server 2008 R2 的平台更新 [桌面应用 |UWP 应用]
目标平台 Windows
标头 dxgi1_2.h
Library Dxgi.lib

请参阅

IDXGIResource1