atributo handle

O atributo [handle] especifica um tipo de identificador definido pelo usuário ou "personalizado".

typedef [handle] typename;  
handle_t __RPC_USER typename_bind (typename);
void __RPC_USER typename_unbind (typename, handle_t);

Parâmetros

typename

Especifica o nome do tipo binding-handle definido pelo usuário.

Comentários

Os identificadores definidos pelo usuário permitem que os desenvolvedores criem identificadores significativos para o aplicativo. Um identificador definido pelo usuário só pode ser definido em uma declaração de tipo, não em um declarador de função.

Um parâmetro de um tipo definido pelo atributo [handle] é usado para determinar a associação para a chamada e é transmitido para o procedimento chamado.

O usuário deve fornecer rotinas de associação e desassociação para converter entre tipos de identificador primitivos e definidos pelo usuário. Considerando um identificador definido pelo usuário do tipo typename, o usuário deve fornecer as rotinas typename_bind e typename_unbind. Por exemplo, se o tipo de identificador definido pelo usuário for chamado MYHANDLE, as rotinas serão nomeadas MYHANDLE_bind e MYHANDLE_unbind.

Se tiver êxito, a rotina typename_bind deverá retornar um identificador de associação primitiva válido. Se não tiver êxito, a rotina deverá retornar um NULL. Se a rotina retornar NULL, a rotina typename_unbind não será chamada. Se a rotina de associação retornar um identificador de associação inválido diferente de NULL, o comportamento do stub será indefinido.

Quando o procedimento remoto tem um identificador definido pelo usuário como um parâmetro ou como um identificador implícito, os stubs do cliente chamam a rotina de associação antes de chamar o procedimento remoto. Os stubs do cliente chamam a rotina de desassociação após a chamada remota.

No DCE IDL, um parâmetro com o atributo [handle] deve aparecer como o primeiro parâmetro na lista de argumentos de procedimento remoto. Os parâmetros subsequentes, incluindo outros atributos [handle], são tratados como parâmetros comuns. A Microsoft dá suporte a uma extensão para IDL de DCE que permite que o parâmetro [handle] definido pelo usuário apareça em posições diferentes do primeiro parâmetro.

Exemplos

typedef [handle] struct 
{ 
    char machine[8]; 
    char nmpipe[256]; 
} h_service; 
 
handle_t __RPC_USER h_service_bind(h_service); 
void __RPC_USER h_service_unbind(h_service, handle_t);

Confira também

Associação e identificadores

Arquivo IDL (Definição de Interface)

implicit_handle

Typedef