atributo context_handle
O atributo [context_handle] identifica um identificador de associação que mantém informações de contexto ou estado no servidor entre chamadas de procedimento remoto.
typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;
[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator], ...);
[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);
[ void __RPC_USER context-handle-type_rundown (
context-handle-type); ]
Parâmetros
-
type-attribute-list
-
Especifica um ou mais atributos que se aplicam ao tipo .
-
type-specifier
-
Especifica um tipo de ponteiro ou um identificador de tipo. Uma especificação de armazenamento opcional pode preceder o especificador de tipo.
-
declarator e declarator-list
-
Especifica declaradores C padrão, como identificadores, declaradores de ponteiro e declaradores de matriz. O declarador de um identificador de contexto deve incluir pelo menos um declarador de ponteiro. Para obter mais informações, consulte Atributos de matriz e Sized-Pointer, matrizes e matrizes e ponteiros. A lista de declaradores consiste em um ou mais declaradores, separados por vírgulas. O identificador de nome do parâmetro no declarador de função é opcional.
-
function-attr-list
-
Especifica zero ou mais atributos que se aplicam à função. Os atributos de função válidos são [retorno de chamada], [local]; o atributo de ponteiro [ref], [unique]ou [ptr]; e os atributos de uso [cadeiade caracteres], [ignorar]e [context_handle].
-
ptr-decl
-
Especifica zero ou mais declaradores de ponteiro. Um declarador de ponteiro é o mesmo que o declarador de ponteiro usado em C; ele é construído a partir do * designador, modificadores como far e o qualificador const.
-
nome da função
-
Especifica o nome do procedimento remoto.
-
parameter-attribute-list
-
Especifica zero ou mais atributos direcionais, atributos de campo, atributos de uso e atributos de ponteiro apropriados para o tipo de parâmetro especificado. Separe vários atributos com vírgulas.
-
context-handle-type
-
Especifica o identificador que especifica o tipo de identificador de contexto conforme definido em uma declaração typedef que usa o atributo [context_handle] . A rotina de rundown é opcional.
Windows Server 2003 e Windows XP: Uma única interface pode acomodar identificadores de contexto serializados e não sequenciados, permitindo que um método em uma interface acesse um identificador de contexto exclusivamente (serializado), enquanto outros métodos acessam esse identificador de contexto no modo compartilhado (não serializado). Esses recursos de acesso são comparáveis aos mecanismos de bloqueio de leitura/gravação; os métodos que usam um identificador de contexto serializado são usuários exclusivos (gravadores), enquanto os métodos que usam um identificador de contexto não serializado são usuários compartilhados (leitores). Métodos que destroem ou modificam o estado de um identificador de contexto devem ser serializados. Métodos que não modificam o estado de um identificador de contexto, como os métodos que simplesmente leem de um identificador de contexto, podem ser não sequenciados. Observe que os métodos de criação são serializados implicitamente.
Comentários
O atributo [context_handle] pode aparecer como um atributo de tipo typedef IDL, como um atributo de tipo de retorno de função ou como um atributo de parâmetro. Ao aplicar o atributo [context_handle] a uma definição de tipo, você também deve fornecer uma rotina de resumo de contexto. Consulte Rotina de Execução de Contexto do Servidor para obter detalhes.
Quando você usa o compilador MIDL no modo padrão (/ms_ext), um identificador de contexto pode ser qualquer tipo de ponteiro selecionado pelo usuário, desde que ele esteja em conformidade com os requisitos de identificadores de contexto descritos aqui. Os dados associados a esse tipo de identificador de contexto não são transmitidos na rede e só devem ser manipulados pelo aplicativo do servidor. Os compiladores de IDL do DCE restringem identificadores de contexto a ponteiros do tipo void*. Portanto, esse recurso não está disponível quando você usa o comutador /osf do compilador MIDL.
Assim como acontece com outros tipos de identificador, o identificador de contexto é opaco para o aplicativo cliente e todos os dados associados a ele não são transmitidos. No servidor, o identificador de contexto serve como um identificador no contexto ativo e todos os dados associados ao tipo de identificador de contexto são acessíveis.
Para criar um identificador de contexto, o cliente passa para o servidor um ponteiro [out], [ref] para um identificador de contexto. (O próprio identificador de contexto pode ter um valor NULL ou não NULL , desde que seu valor seja consistente com seus atributos de ponteiro. Por exemplo, quando o tipo de identificador de contexto tem o atributo [ref] aplicado a ele, ele não pode ter um valor NULL .) Outro identificador de associação deve ser fornecido para realizar a associação até que o identificador de contexto seja criado. Quando nenhum identificador explícito é especificado, a associação implícita é usada. Quando nenhum atributo [implicit_handle] está presente, um identificador automático é usado.
O procedimento remoto no servidor cria um identificador de contexto ativo. O cliente deve usar esse identificador de contexto como um parâmetro [in] ou [in, out] em chamadas subsequentes. Um identificador de contexto [in]-only pode ser usado como um identificador de associação, portanto, ele deve ter um valor não NULL . Um identificador de contexto [in]-only não reflete as alterações de estado no servidor.
No servidor, o procedimento chamado pode interpretar o identificador de contexto conforme necessário. Por exemplo, o procedimento chamado pode alocar o armazenamento de heap e usar o identificador de contexto como um ponteiro para esse armazenamento.
Para fechar um identificador de contexto, o cliente passa o identificador de contexto como um argumento [in], [out] . O servidor deve retornar um identificador de contexto NULL quando não estiver mais mantendo o contexto em nome do chamador. Por exemplo, se o identificador de contexto representar um arquivo aberto e a chamada fechar o arquivo, o servidor deverá definir o identificador de contexto como NULL e devolvê-lo ao cliente. Um valor NULL é inválido como um identificador de associação em chamadas subsequentes.
Um identificador de contexto só é válido para um servidor. Quando uma função tem dois parâmetros de identificador e o identificador de contexto não é NULL, os identificadores de associação devem se referir ao mesmo espaço de endereço.
Quando uma função tem um identificador de contexto [in] ou [in, out], seu identificador de contexto pode ser usado como o identificador de associação. Nesse caso, a associação implícita não é usada e o atributo [implicit_handle] ou [auto_handle] é ignorado.
As seguintes restrições se aplicam a identificadores de contexto:
- Os identificadores de contexto não podem ser elementos de matriz, membros da estrutura ou membros do sindicato. Eles só podem ser parâmetros.
- Os identificadores de contexto não podem ter o atributo [transmit_as] ou [represent_as] .
- Os parâmetros que são ponteiros para identificadores de contexto [out] devem ser ponteiros [ref].
- Um identificador de contexto [in] pode ser usado como o identificador de associação e não pode ser NULL.
- Um identificador de contexto [in, out pode ser NULL na entrada, mas somente se o procedimento tiver outro parâmetro de identificador explícito. Se não houver outros parâmetros explícitos de identificador de contexto não NULL , o identificador de contexto [in, out] não poderá ser NULL.
- Um identificador de contexto não pode ser usado com retornos de chamada.
Exemplos
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);
Confira também