Método IDXGIResource1::CreateSharedHandle (dxgi1_2.h)
Cria um identificador para um recurso compartilhado. Em seguida, você pode usar o identificador retornado com vários dispositivos Direct3D.
Sintaxe
HRESULT CreateSharedHandle(
[in, optional] const SECURITY_ATTRIBUTES *pAttributes,
[in] DWORD dwAccess,
[in, optional] LPCWSTR lpName,
[out] HANDLE *pHandle
);
Parâmetros
[in, optional] pAttributes
Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que contém dois membros de dados separados, mas relacionados: um descritor de segurança opcional e um valor booliano que determina se os processos filho podem herdar o identificador retornado.
Defina esse parâmetro para NULL se você quiser processos filho que o aplicativo possa criar para não herdar o identificador retornado por CreateSharedHandlee se você quiser que o recurso associado ao identificador retornado obtenha um descritor de segurança padrão.
O lpSecurityDescriptor membro da estrutura especifica um SECURITY_DESCRIPTOR para o recurso. Defina esse membro como NULL se desejar que o runtime atribua um descritor de segurança padrão ao recurso associado ao identificador retornado. As ACLs no descritor de segurança padrão para o recurso vêm do token primário ou de representação do criador. Para obter mais informações, consulte direitos de acesso e segurança do objeto de sincronização.
[in] dwAccess
Os direitos de acesso solicitados ao recurso. Além dos direitos de acesso genéricos , o DXGI define os seguintes valores:
- DXGI_SHARED_RESOURCE_READ ( 0x80000000L ) – especifica o acesso de leitura ao recurso.
- DXGI_SHARED_RESOURCE_WRITE ( 1 ) – especifica o acesso de gravação ao recurso.
[in, optional] lpName
O nome do recurso a ser compartilhado. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.
Você precisará do nome do recurso se chamar o método ID3D11Device1::OpenSharedResourceByName para acessar o recurso compartilhado pelo nome. Se você chamar o método ID3D11Device1::OpenSharedResource1
Se lpName corresponder ao nome de um recurso existente, CreateSharedHandle falhará com DXGI_ERROR_NAME_ALREADY_EXISTS. Isso ocorre porque esses objetos compartilham o mesmo namespace.
O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). Para obter mais informações, consulte namespaces de objeto kernel. A alternância rápida de usuário é implementada usando sessões dos Serviços de Terminal. Os nomes de objeto kernel devem seguir as diretrizes descritas para os Serviços de Terminal para que os aplicativos possam dar suporte a vários usuários.
O objeto pode ser criado em um namespace privado. Para obter mais informações, consulte namespaces de objeto.
[out] pHandle
Um ponteiro para uma variável que recebe o valor NT HANDLE para o recurso a ser compartilhado. Você pode usar esse identificador em chamadas para acessar o recurso.
Valor de retorno
Retorna S_OK se tiver êxito; caso contrário, retorna um dos seguintes valores:
- DXGI_ERROR_INVALID_CALL se um dos parâmetros for inválido.
- DXGI_ERROR_NAME_ALREADY_EXISTS se o nome fornecido do recurso a ser compartilhado já estiver associado a outro recurso.
- E_ACCESSDENIED se o objeto estiver sendo criado em um namespace protegido.
- E_OUTOFMEMORY se a memória suficiente não estiver disponível para criar o identificador.
- Possivelmente outros códigos de erro descritos no tópico DXGI_ERROR.
Observações
CreateSharedHandle retorna apenas o identificador NT quando você criou o recurso como compartilhado e especificou que ele usa identificadores NT (ou seja, você define os sinalizadores D3D11_RESOURCE_MISC_SHARED_NTHANDLE e D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX). Se você criou o recurso como compartilhado e especificou que ele usa identificadores NT, você deve usar CreateSharedHandle para obter um identificador para compartilhamento. Nessa situação, você não pode usar o método IDXGIResource::GetSharedHandle porque ele falhará.
Você pode passar o identificador que CreateSharedHandle retorna em uma chamada para o método ID3D11Device1::OpenSharedResource1 para dar a um dispositivo acesso a um recurso compartilhado criado em um dispositivo diferente.
Como o identificador que CreateSharedHandle retorna é um identificador NT, você pode usar o identificador com CloseHandle, DuplicateHandle e assim por diante. Você pode chamar CreateSharedHandle apenas uma vez para um recurso compartilhado; chamadas posteriores falham. Se você precisar de mais identificadores para o mesmo recurso compartilhado, chame DuplicateHandle. Quando você não precisar mais do identificador de recurso compartilhado, chame CloseHandle para fechar o identificador, a fim de evitar vazamentos de memória.
Se você passar um nome para o recurso para lpName quando chamar CreateSharedHandle para compartilhar o recurso, você poderá, posteriormente, passar esse nome em uma chamada para o método ID3D11Device1::OpenSharedResourceByName para dar a outro dispositivo acesso ao recurso compartilhado. Se você usar um recurso nomeado, um usuário mal-intencionado poderá usar esse recurso nomeado antes de você e impedir que seu aplicativo seja iniciado. Para evitar essa situação, crie um recurso nomeado aleatoriamente e armazene o nome para que ele só possa ser obtido por um usuário autorizado. Como alternativa, você pode usar um arquivo para essa finalidade. Para limitar seu aplicativo a uma instância por usuário, crie um arquivo bloqueado no diretório de perfil do usuário.
Se você criou o recurso como compartilhado e não especificou que ele usa identificadores NT, não é possível usar CreateSharedHandle para obter um identificador para compartilhamento porque CreateSharedHandle falharão.
Exemplos
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
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 8 e Platform Update para Windows 7 [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2012 e Platform Update para Windows Server 2008 R2 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | dxgi1_2.h |
| biblioteca | Dxgi.lib |