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

Метод 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, содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, могут ли дочерние процессы наследовать возвращенный дескриптор.

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

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

[in] dwAccess

Запрошенные права доступа к ресурсу. Помимо универсальных прав доступа, DXGI определяет следующие значения:

  • DXGI_SHARED_RESOURCE_READ ( 0x8000000000L) — указывает доступ на чтение к ресурсу.
  • DXGI_SHARED_RESOURCE_WRITE (1) — указывает доступ на запись к ресурсу.
Эти значения можно объединить с помощью побитовой операции OR.

[in, optional] lpName

Имя ресурса для общего доступа. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.

При вызове метода ID3D11Device1::OpenSharedResourceByName для доступа к общему ресурсу по имени потребуется имя ресурса. Если вместо этого вызвать метод ID3D11Device1::OpenSharedResource1 для доступа к общему ресурсу по дескриптору, задайте для этого параметра значение null.

Если lpName соответствует имени существующего ресурса, CreateSharedHandle завершается ошибкой с DXGI_ERROR_NAME_ALREADY_EXISTS. Это происходит, так как эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.

Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.

[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, ДубликатомHandleи т. д. Вы можете вызывать 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]
целевая платформа Виндоус
заголовка dxgi1_2.h
библиотеки Dxgi.lib

См. также

IDXGIResource1