Метод IDXGIResource1::CreateSharedHandle (dxgi1_2.h)

Статья
08/23/2023

Создает дескриптор для общего ресурса. Затем вы можете использовать возвращенный дескриптор с несколькими устройствами Direct3D.

Синтаксис

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

Параметры

[in, optional] pAttributes

Указатель на SECURITY_ATTRIBUTES структуру, содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, могут ли дочерние процессы наследовать возвращаемый дескриптор.

Задайте для этого параметра значение NULL , если требуется, чтобы дочерние процессы, создаваемые приложением, не наследовали дескриптор, возвращенный Командлетом CreateSharedHandle, и если требуется, чтобы ресурс, связанный с возвращенным дескриптором, мог получить дескриптор безопасности по умолчанию.

Элемент lpSecurityDescriptor структуры указывает SECURITY_DESCRIPTOR для ресурса. Присвойте этому элементу значение NULL , если требуется, чтобы среда выполнения назначила дескриптор безопасности по умолчанию ресурсу, связанному с возвращенным дескриптором. Списки управления доступом в дескрипторе безопасности по умолчанию для ресурса поступают из основного маркера или маркера олицетворения создателя. Дополнительные сведения см. в разделе Синхронизация безопасности объектов и прав доступа.

[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 Server 2008 R2 с установленным обновлением платформы для Windows 7createSharedHandle завершается сбоем с 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 , чтобы закрыть дескриптор, чтобы избежать утечек памяти.

Если вы передаете имя ресурса в lpName при вызове CreateSharedHandle для предоставления общего доступа к ресурсу, вы можете передать это имя в вызове метода 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 8 и Обновление платформы для Windows 7 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 и обновление платформы для Windows Server 2008 R2 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	dxgi1_2.h
Библиотека	Dxgi.lib

См. также раздел

IDXGIResource1

Поделиться через