Função RpcServerListen (rpcdce.h)

Artigo
08/25/2023

A função RpcServerListen sinaliza a biblioteca de tempo de execução RPC para escutar chamadas de procedimento remoto. Essa função não afetará as interfaces de escuta automática; use RpcServerRegisterIfEx se você precisar dessa funcionalidade.

Sintaxe

RPC_STATUS RpcServerListen(
  unsigned int MinimumCallThreads,
  unsigned int MaxCalls,
  unsigned int DontWait
);

Parâmetros

MinimumCallThreads

Dica para o tempo de execução RPC que especifica o número mínimo de threads de chamada que devem ser criados e mantidos no servidor fornecido. Esse valor é apenas uma dica e é interpretado de forma diferente em diferentes versões do Windows. No Windows XP, esse valor é o número de threads criados anteriormente em cada pool de threads que o tempo de execução do RPC cria. Um aplicativo deve especificar um para esse parâmetro e adiar as decisões de criação de thread para o tempo de execução do RPC.

MaxCalls

Número máximo recomendado de chamadas de procedimento remoto simultâneo que o servidor pode executar. Para permitir um desempenho eficiente, as bibliotecas de tempo de execução RPC interpretam o parâmetro MaxCalls como um limite sugerido em vez de como um limite superior absoluto.

Use RPC_C_LISTEN_MAX_CALLS_DEFAULT para especificar o valor padrão.

DontWait

Sinalizador que controla o retorno de RpcServerListen. Um valor diferente de zero indica que RpcServerListen deve retornar imediatamente após concluir o processamento da função. Um valor zero indica que RpcServerListen não deve retornar até que a função RpcMgmtStopServerListening tenha sido chamada e todas as chamadas remotas tenham sido concluídas.

Valor retornado

Valor	Significado
RPC_S_OK	A chamada foi bem-sucedida.
RPC_S_ALREADY_LISTENING	O servidor já está escutando.
RPC_S_NO_PROTSEQS_REGISTERED	Não há sequências de protocolo registradas.
RPC_S_MAX_CALLS_TOO_SMALL	O valor máximo de chamadas é muito pequeno.

Nota Para obter uma lista de códigos de erro válidos, consulte RPC Return Values.

Comentários

Um servidor chama RpcServerListen quando o servidor está pronto para processar chamadas de procedimento remoto. O RPC permite que um servidor processe simultaneamente várias chamadas. O parâmetro MaxCalls recomenda o número máximo de chamadas de procedimento remoto simultâneos que o servidor deve executar.

O valor MaxCalls não deve ser zero e deve ser maior que MinimumCallThreads. Valores maiores que 0x7FFFFFFF são definidos como 0x7FFFFFFF sem aviso prévio.

Windows XP/2000: Definir o parâmetro MaxCalls como RPC_C_LISTEN_MAX_CALLS_DEFAULT remove o limite de chamadas de procedimento remoto simultâneas, em vez de defini-lo como o valor definido pela constante de 1234. Remover o limite de chamadas simultâneas máximas permite quantas chamadas de procedimento remoto simultâneas o computador puder lidar. Esse comportamento permite maior eficiência no tempo de execução do RPC.

Um aplicativo de servidor é responsável pelo controle de simultaneidade entre as rotinas do gerenciador de servidores porque cada rotina é executada em um thread separado.

Quando o parâmetro DontWait tem um valor igual a zero, a biblioteca de tempo de execução RPC continua escutando chamadas de procedimento remoto (ou seja, a rotina não retorna ao aplicativo de servidor) até que ocorra um dos seguintes eventos:

Uma das rotinas de gerente do aplicativo de servidor chama RpcMgmtStopServerListening.
Um cliente chama um procedimento remoto fornecido pelo servidor que direciona o servidor para chamar RpcMgmtStopServerListening.
Um cliente chama RpcMgmtStopServerListening com um identificador de associação para o servidor.

Depois de receber uma solicitação de parada de escuta, a biblioteca de tempo de execução RPC para de aceitar novas chamadas de procedimento remoto para todas as interfaces registradas. A execução de chamadas tem permissão para ser concluída, incluindo retornos de chamada. Depois que todas as chamadas forem concluídas, RpcServerListen retornará ao chamador.

Quando o parâmetro DontWait tem um valor diferente de zero, RpcServerListen retorna ao servidor imediatamente após processar todas as instruções associadas à função. Você pode usar a função RpcMgmtWaitServerListen para executar a operação de espera geralmente associada a RpcServerListen.

Nota A implementação de RPC da Microsoft de RpcServerListen inclui dois parâmetros adicionais que não aparecem na especificação DCE: DontWait e MinimumCallThreads.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	rpcdce.h (inclua Rpc.h)
Biblioteca	Rpcrt4.lib
DLL	Rpcrt4.dll