atributo system_handle

O atributo [system_handle] especifica um tipo de identificador definido pelo sistema que representa o acesso a um objeto do sistema.

[system_handle(system-handle-type[,optional-access-mask])]

Parâmetros

system-handle-type

Especifica uma das opções de tipo de identificador do sistema.

As opções válidas são:

• sh_composition – um identificador de superfície DirectComposition
• sh_event – um objeto de evento nomeado ou sem nome
• sh_file - Um arquivo ou dispositivo de E/S
• sh_job - Um objeto de trabalho
• sh_mutex – um objeto mutex nomeado ou sem nome
• sh_pipe - Um objeto pipe anônimo ou nomeado
• sh_process - Um objeto de processo
• sh_reg_key - Uma chave do Registro
• sh_section - Uma seção de memória compartilhada
• sh_semaphore - Um objeto semáforo nomeado ou sem nome
• sh_socket – um objeto de soquete WinSock
• sh_thread - Um objeto thread
• sh_token - Um objeto de token de acesso

optional-access-mask

Opcionalmente, solicita direitos de acesso específicos aplicados ao identificador duplicado. Por padrão, quando isso não for especificado, o identificador será duplicado com o mesmo acesso.

Para especificar um nível diferente de acesso, use direitos de acesso específicos do objeto correspondentes ao objeto do sistema subjacente selecionado.

Mais informações sobre como os direitos de acesso são propagados durante a duplicação podem ser encontradas na documentação DuplicateHandle .

Links para listas de direitos de acesso para cada tipo de objeto podem ser encontrados na referência DuplicateHandle , bem como na página Ver também títulos de cada sh_* parâmetro.

Comentários

Para usar esse atributo, o -target sinalizador deve ser definido NT100 como (ou superior) ao executar midl.exe.

Os identificadores do sistema são identificadores definidos pelo sistema operacional para fornecer acesso a um recurso do sistema. O tipo específico do objeto por trás do identificador deve ser especificado ao declarar o atributo.

Para um identificador marcado [in], o identificador será duplicado no procedimento remoto e permanecerá válido durante esse procedimento. Ao retornar do procedimento remoto, o identificador duplicado é liberado. Para manter o acesso ao objeto subjacente, o aplicativo remoto deve duplicar o identificador em seu próprio espaço de endereço.

Por outro lado, para um identificador marcado [out]como , quando um procedimento remoto retorna um identificador de uma chamada, o procedimento remoto perderá a propriedade dele. Para manter o acesso ao objeto subjacente, o procedimento remoto deve duplicar o identificador e retornar a duplicata. O identificador retornado então se torna propriedade do chamador que assume a responsabilidade de fechá-lo quando o acesso ao objeto do sistema subjacente não é mais necessário.

Como esse é um mecanismo para retransmitir o acesso a um objeto do sistema, esse atributo só é aplicável a chamadas entre procedimentos no mesmo computador.

Os parâmetros de criação e acesso fornecidos ao objeto subjacente por trás do identificador do sistema em sua criação determinarão se ele pode ser realizado com êxito no contexto de procedimento remoto.

Uma matriz de system_handle pode ser passada para dentro ou para fora com a sintaxe encontrada na documentação do atributo size_is .

Exemplos

Os exemplos a seguir usam vários de system_handle. Para obter um exemplo completo, consulte o exemplo SystemHandlePassing .

interface MyInterface : IUnknown                         
{         
    HRESULT Proc1([in, system_handle(sh_file)] HANDLE writeThisFile);

    HRESULT Proc2([in, system_handle(sh_pipe, FILE_GENERIC_READ)] HANDLE readThisPipe);

    HRESULT Proc3([out, system_handle(sh_composition)] HANDLE* visual);

    HRESULT Proc4([in] DWORD cEvents, [out, system_handle(sh_event), size_is(cEvents)] HANDLE* pWatchAllTheseEvents);
}

Requisitos

Cliente mínimo com suporte	Windows 10 Atualização de Aniversário (versão 1607, build 14393)
Servidor mínimo com suporte	Windows Server 2016 (build 14393)

Confira também

opção /target

Associação e identificadores

Identificadores e objetos

Arquivo IDL (Definição de Interface)

Duplicatehandle

Descritores de segurança