Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
O atributo [context_handle] identifica um handle de ligação que mantém o contexto, ou informação de 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
-
Tipo-Atributo-Lista
-
Especifica um ou mais atributos que se aplicam ao tipo.
-
Especificador de tipo
-
Especifica um tipo de ponteiro ou um identificador de tipo. Uma especificação de armazenamento opcional pode preceder o especificador de tipo.
-
Declarador e Lista de Declaradores
-
Especifica declaradores C padrão, como identificadores, declaradores de ponteiro e declaradores de array. O declarador de um handle de contexto deve incluir pelo menos um declarador de ponteiro. Para mais informações, consulte Atributos de Array e Sized-Pointer, Arrays e Arrays e Ponteiros. A lista de declaradores consiste em um ou mais declaradores, separados por vírgulas. O identificador do nome do parâmetro no declarador da função é opcional.
-
function-attr-list
-
Especifica zero ou mais atributos que se aplicam à função. Atributos válidos da função são [callback],[local]; o atributo do ponteiro [ref],[único] ou [ptr]; e os atributos de utilização [string],[ignorar] e [context_handle].
-
PTR-DECL
-
Especifica declaradores de zero ou mais ponteiros. Um declarador de ponteiro é o mesmo que o declarador de ponteiro usado em C; É construído a partir do * designador, modificadores como FAR e do qualificador const.
-
Nome da função
-
Especifica o nome do procedimento remoto.
-
Parameter-attribute-list
-
Especifica atributos direcionais zero ou mais, atributos de campo, atributos de utilização e atributos de ponteiro apropriados para o tipo de parâmetro especificado. Separa múltiplos atributos com vírgulas.
-
tipo de alça de contexto
-
Especifica o identificador que especifica o tipo de handle de contexto conforme definido numa declaração typedef que assume o atributo [context_handle]. A rotina de resumo é opcional.
Windows Server 2003 e Windows XP: Uma única interface pode acomodar tanto controlos de contexto serializados como não serializados, permitindo que um método numa interface aceda exclusivamente a um handle de contexto (serializado), enquanto outros métodos acedam a esse handle de contexto em modo partilhado (não serializado). Estas capacidades de acesso são comparáveis aos mecanismos de bloqueio de leitura/escrita; Métodos que usam um handle de contexto serializado são utilizadores exclusivos (escritores), enquanto métodos que usam um handle de contexto não serializado são utilizadores partilhados (leitores). Os métodos que destroem ou modificam o estado de um handle de contexto devem ser serializados. Métodos que não modificam o estado de um handle de contexto, como aqueles que simplesmente leem de um handle de contexto, podem ser não serializados. Note-se que os métodos de criação são implicitamente serializados.
Observações
O atributo [context_handle] pode aparecer como um atributo tipo IDL typedef , como um atributo de tipo de retorno de função ou como um atributo de parâmetro. Quando aplica o atributo [context_handle] a uma definição de tipo, deve também fornecer uma rotina de resumo do contexto. Consulte a Rotina de Execução do Contexto do Servidor para mais detalhes.
Quando usa o compilador MIDL em modo padrão (/ms_ext), um handle de contexto pode ser qualquer tipo de pointer selecionado pelo utilizador, desde que cumpra os requisitos para os handles de contexto aqui descritos. Os dados associados a tal tipo de handle de contexto não são transmitidos na rede e só devem ser manipulados pela aplicação servidor. Os compiladores IDL do DCE restringem os controlos de contexto a ponteiros de tipo void*. Portanto, esta funcionalidade não está disponível quando se utiliza o compilador MIDL /osf switch.
Tal como noutros tipos de handles, o handle de contexto é opaco para a aplicação cliente e quaisquer dados associados a ele não são transmitidos. No servidor, o handle de contexto serve como handle do contexto ativo, e todos os dados associados ao tipo de handle de contexto são acessíveis.
Para criar um handle de contexto, o cliente passa ao servidor um apontador [out][ref] para um handle de contexto. (O próprio handle de contexto pode ter um valor NULL ou não-NULL — desde que o seu valor seja consistente com os atributos do apontador. Por exemplo, quando o tipo de handle de contexto tem o atributo[ref] aplicado, não pode ter um valor NULL.) Outra alça de ligação deve ser fornecida para realizar a ligação até que a alça de contexto seja criada. Quando não é especificado um handle explícito, usa-se a ligação implícita. Quando não existe nenhum atributo [implicit_handle], é usado um autohandle.
O procedimento remoto no servidor cria um handle de contexto ativo. O cliente deve usar esse handle de contexto como parâmetro [in] ou [in, out] em chamadas subsequentes. Um handle de contexto apenas [in]-pode ser usado como um handle de ligação, pelo que deve ter um valor não NULL . Um handle de contexto apenas [in]não reflete alterações de estado no servidor.
No servidor, o procedimento chamado pode interpretar o handle de contexto conforme necessário. Por exemplo, o procedimento chamado pode alocar armazenamento de heap e usar o handle de contexto como apontador para esse armazenamento.
Para fechar um handle de contexto, o cliente passa o handle de contexto como um argumento [in], [out]. O servidor deve devolver um handle de contexto NULL quando já não está a manter o contexto em nome do chamador. Por exemplo, se o handle de contexto representa um ficheiro aberto e a chamada fecha o ficheiro, o servidor deve definir o handle de contexto para NULL e devolvê-lo ao cliente. Um valor NULL é inválido como handle de ligação em chamadas subsequentes.
Um handle de contexto é válido apenas para um servidor. Quando uma função tem dois parâmetros de handle e o handle de contexto não é NULL, os handles de ligação devem referir-se ao mesmo espaço de endereçamento.
Quando uma função tem um handle de contexto [in] ou [in, out], o seu handle de contexto pode ser usado como handle de ligação. Neste caso, a ligação implícita não é usada e o atributo [implicit_handle] ou [auto_handle] é ignorado.
As seguintes restrições aplicam-se aos handles de contexto:
- Os handles de contexto não podem ser elementos de array, membros de estrutura ou membros de sindicato. Só podem ser parâmetros.
- Os handles de contexto não podem ter o atributo [transmit_as] ou [represent_as].
- Os parâmetros que são apontadores para handles de contexto[fora] devem ser apontadores [ref].
- Um handle [em] contexto pode ser usado como handle de binding e não pode ser NULL.
- Um handle de contexto de entrada e saída pode ser NULL na entrada, mas apenas se o procedimento tiver outro parâmetro de handle explícito. Se não existirem outros parâmetros explícitos de handle de contexto não NULL , o handle de contexto [in, out] não pode ser NULL.
- Um handle de contexto não pode ser usado com callbacks.
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);
Consulte também