Método IDXGIResource1::CreateSharedHandle (dxgi1_2.h)

  • Artículo

Crea un identificador para un recurso compartido. A continuación, puede usar el identificador devuelto con varios dispositivos Direct3D.

Sintaxis

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

Parámetros

[in, optional] pAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES que contiene dos miembros de datos independientes pero relacionados: un descriptor de seguridad opcional y un valor booleano que determina si los procesos secundarios pueden heredar el identificador devuelto.

Establezca este parámetro en NULL si desea que los procesos secundarios que la aplicación cree no hereden el identificador devuelto por CreateSharedHandle y si desea que el recurso asociado al identificador devuelto obtenga un descriptor de seguridad predeterminado.

El miembro lpSecurityDescriptor de la estructura especifica un SECURITY_DESCRIPTOR para el recurso. Establezca este miembro en NULL si desea que el runtime asigne un descriptor de seguridad predeterminado al recurso asociado al identificador devuelto. Las ACL del descriptor de seguridad predeterminado para el recurso proceden del token principal o de suplantación del creador. Para obtener más información, consulte Seguridad de objetos de sincronización y derechos de acceso.

[in] dwAccess

Derechos de acceso solicitados al recurso. Además de los derechos de acceso genéricos, DXGI define los siguientes valores:

  • DXGI_SHARED_RESOURCE_READ ( 0x800000000L ): especifica el acceso de lectura al recurso.
  • DXGI_SHARED_RESOURCE_WRITE ( 1 ): especifica el acceso de escritura al recurso.
Puede combinar estos valores mediante una operación OR bit a bit.

[in, optional] lpName

Nombre del recurso que se va a compartir. El nombre está limitado a MAX_PATH caracteres. La comparación de nombres distingue mayúsculas de minúsculas.

Necesitará el nombre del recurso si llama al método ID3D11Device1::OpenSharedResourceByName para acceder al recurso compartido por nombre. Si en su lugar llama al método ID3D11Device1::OpenSharedResource1 para acceder al recurso compartido mediante handle, establezca este parámetro en NULL.

Si lpName coincide con el nombre de un recurso existente, CreateSharedHandle produce un error con DXGI_ERROR_NAME_ALREADY_EXISTS. Esto ocurre porque estos objetos comparten el mismo espacio de nombres.

El nombre puede tener un prefijo "Global" o "Local" para crear explícitamente el objeto en el espacio de nombres global o de sesión. El resto del nombre puede contener cualquier carácter excepto el carácter de barra diagonal inversa (\). Para obtener más información, vea Espacios de nombres de objeto kernel. El cambio rápido de usuario se implementa mediante sesiones de Terminal Services. Los nombres de objeto de kernel deben seguir las directrices descritas para Terminal Services para que las aplicaciones puedan admitir varios usuarios.

El objeto se puede crear en un espacio de nombres privado. Para obtener más información, vea Espacios de nombres de objeto.

[out] pHandle

Puntero a una variable que recibe el valor NT HANDLE al recurso que se va a compartir. Puede usar este identificador en las llamadas para acceder al recurso.

Valor devuelto

Devuelve S_OK si se ejecuta correctamente; de lo contrario, devuelve uno de los valores siguientes:

  • DXGI_ERROR_INVALID_CALL si uno de los parámetros no es válido.
  • DXGI_ERROR_NAME_ALREADY_EXISTS si el nombre proporcionado del recurso que se va a compartir ya está asociado a otro recurso.
  • E_ACCESSDENIED si el objeto se está creando en un espacio de nombres protegido.
  • E_OUTOFMEMORY si no hay suficiente memoria disponible para crear el identificador.
  • Posiblemente otros códigos de error que se describen en el tema DXGI_ERROR .
Actualización de la plataforma para Windows 7: En Windows 7 o Windows Server 2008 R2 con la actualización de plataforma para Windows 7 instalada, CreateSharedHandle produce un error E_NOTIMPL. Para obtener más información sobre la actualización de plataforma para Windows 7, consulta Actualización de plataforma para Windows 7.

Comentarios

CreateSharedHandle solo devuelve el identificador NT cuando creó el recurso como compartido y especificó que usa identificadores NT (es decir, se establecen las marcas de D3D11_RESOURCE_MISC_SHARED_NTHANDLE y D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX ). Si creó el recurso como compartido y especificó que usa identificadores NT, debe usar CreateSharedHandle para obtener un identificador para compartir. En esta situación, no puede usar el método IDXGIResource::GetSharedHandle porque se producirá un error.

Puede pasar el identificador que devuelve CreateSharedHandle en una llamada al método ID3D11Device1::OpenSharedResource1 para conceder a un dispositivo acceso a un recurso compartido que creó en otro dispositivo.

Dado que el identificador que devuelve CreateSharedHandle es un identificador NT, puede usar el identificador con CloseHandle, DuplicateHandle, etc. Puede llamar a CreateSharedHandle solo una vez para un recurso compartido; se produce un error en las llamadas posteriores. Si necesita más identificadores para el mismo recurso compartido, llame a DuplicateHandle. Cuando ya no necesite el identificador de recursos compartidos, llame a CloseHandle para cerrar el identificador, con el fin de evitar pérdidas de memoria.

Si pasa un nombre para el recurso a lpName cuando llama a CreateSharedHandle para compartir el recurso, posteriormente puede pasar este nombre en una llamada al método ID3D11Device1::OpenSharedResourceByName para conceder a otro dispositivo acceso al recurso compartido. Si usa un recurso con nombre, un usuario malintencionado puede usar este recurso con nombre antes de hacerlo e impedir que la aplicación se inicie. Para evitar esta situación, cree un recurso con nombre aleatorio y almacene el nombre para que un usuario autorizado solo pueda obtenerlo. Como alternativa, puede usar un archivo para este fin. Para limitar la aplicación a una instancia por usuario, cree un archivo bloqueado en el directorio del perfil del usuario.

Si creó el recurso como compartido y no especificó que usa identificadores NT, no puede usar CreateSharedHandle para obtener un identificador para compartir porque Se producirá un error en CreateSharedHandle .

Ejemplos

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.

Requisitos

   
Cliente mínimo compatible Actualización de windows 8 y plataforma para Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 y Actualización de plataforma para Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado dxgi1_2.h
Library Dxgi.lib

Consulte también

IDXGIResource1