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 ) - 指定对资源的写入访问权限。
[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 主题中描述的其他错误代码。
备注
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 |