Função RpcSsContextLockExclusive (rpcasync.h)
A função RpcSsContextLockExclusive permite que um aplicativo comece a usar um identificador de contexto no modo exclusivo. A função RpcSsContextLockExclusive permite que métodos declarados como não sequenciados (compartilhados) no arquivo IDL ou ACF sejam alterados dinamicamente para acessar um identificador de contexto no modo serializado (exclusivo).
Sintaxe
RPC_STATUS RpcSsContextLockExclusive(
[in] RPC_BINDING_HANDLE ServerBindingHandle,
[in] PVOID UserContext
);
Parâmetros
[in] ServerBindingHandle
Identificador de associação no servidor que representa uma associação a um cliente. O servidor representa o cliente indicado por esse identificador. Se um valor igual a zero for especificado, o servidor representará o cliente que está sendo atendido por esse thread de servidor.
[in] UserContext
Ponteiro passado para a rotina do gerenciador ou servidor por RPC. Consulte Observações.
Para identificadores de contexto somente de saída, a função RpcSsContextLockExclusive não executa nenhuma operação.
Retornar valor
Retorna RPC_S_OK após a execução bem-sucedida, indicando que o thread agora tem acesso ao identificador de contexto no modo exclusivo. Retorna ERROR_MORE_WRITES quando vários threads tentam um bloqueio exclusivo no identificador de contexto. Consulte Observações.
Comentários
Modificar se um identificador de contexto é serializado ou não pode ser útil para aplicativos que determinam se um identificador de contexto deve ser fechado com base nas condições detectadas durante a execução. Para alterar um identificador de contexto de serializado (exclusivo) para não inicializado (compartilhado), use a função RpcSsContextLockShared .
Para o parâmetro UserContext , se a rotina do gerenciador receber um ponteiro para um identificador de contexto, ele deverá passar a função RpcSsContextLockExclusive o mesmo ponteiro que recebeu do RPC. Se a rotina do gerenciador receber o próprio identificador de contexto, que é típico para [in] apenas identificadores de contexto, ele deverá passar o próprio identificador de contexto para a função RpcSsContextLockExclusive . O exemplo de código a seguir demonstra isso:
void _UseShared(
/* [in] */ handle_t Binding,
//...
/* [in] */ TestContextHandleShared *Ctx,
//...
)
{
//...
RpcStatus = RpcSsContextLockExclusive(Binding, Ctx);
//...
}
Se uma rotina de gerente usa vários identificadores de contexto [entrada, saída] como um argumento, o RPC fornece à rotina do gerente um ponteiro para o identificador de contexto, não o próprio identificador de contexto. O ponteiro tem a garantia de ser exclusivo e, portanto, passá-lo para a função RpcSsContextLockExclusive é inequívoco. No entanto, se uma função usa vários [in] apenas identificadores de contexto, o RPC fornece à rotina do gerenciador o próprio identificador de contexto. Portanto, o identificador de contexto pode não ser exclusivo. Nesse caso, o RPC executa essa função no primeiro identificador de contexto com o valor fornecido.
Os métodos não devem modificar um identificador de contexto quando estiverem no modo compartilhado. Chamar a função RpcSsContextLockExclusive não elimina um bloqueio de leitor no identificador de contexto especificado; isso garante um identificador de contexto inalterado para aplicativos que não modificam identificadores de contexto no modo compartilhado. Se dois threads tentarem obter um bloqueio exclusivo no mesmo identificador de contexto chamando a função RpcSsContextLockExclusive ao mesmo tempo, um thread escolhido arbitrariamente será retornado RPC_S_OK e o outro será retornado ERROR_MORE_WRITES. O thread retornado ERROR_MORE_WRITES recebe um bloqueio exclusivo, mas seu bloqueio de leitor no identificador de contexto é perdido após o retorno. Um chamador que recebe ERROR_MORE_WRITES não deve assumir nada sobre o identificador de contexto no retorno da função RpcSsContextLockExclusive , pois ela pode ter sido destruída.
As chamadas assíncronas não devem usar a função RpcSsContextLockExclusive no mesmo objeto de chamada de mais de um thread por vez.
A função RpcSsContextLockExclusive pode falhar devido a condições de memória insuficiente e, portanto, os servidores RPC devem estar preparados para lidar com esses erros.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | rpcasync.h (inclua Rpc.h) |
| Biblioteca | Rpcrt4.lib |
| DLL | Rpcrt4.dll |