Função RpcServerUseProtseqEpEx (rpcdce.h)

Artigo
03/13/2024

A função RpcServerUseProtseqEpEx informa à biblioteca de tempo de execução RPC para usar a sequência de protocolo especificada combinada com o ponto de extremidade especificado para receber chamadas de procedimento remoto.

Sintaxe

RPC_STATUS RpcServerUseProtseqEpEx(
  RPC_WSTR     Protseq,
  unsigned int MaxCalls,
  RPC_WSTR     Endpoint,
  void         *SecurityDescriptor,
  PRPC_POLICY  Policy
);

Parâmetros

Protseq

Ponteiro para um identificador de cadeia de caracteres da sequência de protocolo para registrar com a biblioteca de tempo de execução RPC.

MaxCalls

Comprimento da fila de lista de pendências para a sequência de protocolo ncacn_ip_tcp . Todas as outras sequências de protocolo ignoram esse parâmetro. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT para especificar o valor padrão. Consulte Observações.

Endpoint

Ponteiro para as informações de endereço do ponto de extremidade a serem usadas na criação de uma associação para a sequência de protocolo especificada pelo Protseq.

SecurityDescriptor

Ponteiro para um parâmetro opcional fornecido para o subsistema de segurança. Usado somente para sequências de protocolo ncacn_np e ncalrpc . Todas as outras sequências de protocolo ignoram esse parâmetro. Não é recomendável usar um descritor de segurança no ponto de extremidade para tornar um servidor seguro. Esse parâmetro não aparece na especificação DCE para essa API.

Policy

Ponteiro para a estrutura RPC_POLICY , que contém sinalizadores que definem atributos específicos do transporte. No caso do transporte ncadg_mq , esses sinalizadores especificam as propriedades da fila de recebimento do processo do servidor. No caso dos transportes ncacn_ip_tcp ou ncadg_ip_udp , esses sinalizadores restringem a alocação de porta para portas dinâmicas e permitem que computadores multihomed se associem seletivamente a placas de interface de rede.

As configurações de sinalizador no campo Política são efetivas somente quando as sequências de protocolo ncacn_ip_tcp, ncadg_ip_udp ou ncadg_mq estão em uso. Para todas as outras sequências de protocolo, o tempo de execução de RPC ignora esses valores.

Nota Partes da política associada a pontos de extremidade dinâmicos são ignoradas quando a função RpcServerUseProtseqEpEx é chamada, já que a porta é especificada no próprio ponto de extremidade.

Valor retornado

Valor	Significado
RPC_S_OK	A chamada foi bem-sucedida.
RPC_S_PROTSEQ_NOT_SUPPORTED	Não há suporte para a sequência de protocolo neste host.
RPC_S_INVALID_RPC_PROTSEQ	A sequência de protocolo é inválida.
RPC_S_INVALID_ENDPOINT_FORMAT	O formato do ponto de extremidade é inválido.
RPC_S_OUT_OF_MEMORY	O sistema está sem memória.
RPC_S_DUPLICATE_ENDPOINT	O ponto de extremidade está duplicado.
RPC_S_INVALID_SECURITY_DESC	O descritor de segurança é inválido.

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

Comentários

Os parâmetros e efeitos de RpcServerUseProtseqEpEx subsume os de RpcServerUseProtseqEp. A diferença é o parâmetro Policy , que permite definir políticas específicas nos pontos de extremidade. Definir o campo NICFlags da estrutura RPC_POLICY como zero torna essa função estendida equivalente ao RpcServerUseProtseqEp original quando usada com os transportes ncacn_ip_tcp ou ncadg_ip_udp .

Um aplicativo de servidor chama RpcServerUseProtseqEpEx para registrar uma sequência de protocolo com a biblioteca de tempo de execução RPC. Com cada registro de sequência de protocolo, RpcServerUseProtseqEpEx inclui as informações de endereço de ponto de extremidade especificadas.

Para receber solicitações de chamada de procedimento remoto, um servidor deve registrar pelo menos uma sequência de protocolo com a biblioteca de tempo de execução RPC. Um aplicativo de servidor pode chamar essa rotina muitas vezes para registrar sequências de protocolo e pontos de extremidade adicionais. Para cada sequência de protocolo registrada por um servidor, a biblioteca de tempo de execução RPC cria um ou mais pontos de extremidade por meio dos quais o servidor recebe solicitações de chamada de procedimento remoto. A biblioteca de tempo de execução RPC cria pontos de extremidade diferentes para cada sequência de protocolo. No entanto, cada interface no processo é acessível por meio de qualquer ponto de extremidade. Para obter mais informações, consulte Escrevendo um cliente ou servidor RPC seguro.

Para MaxCalls, o valor fornecido pelo aplicativo é apenas uma dica. O tempo de execução de RPC ou o provedor do Windows Sockets pode substituir o valor. Por exemplo, no Windows XP ou Windows 2000 Professional, o valor é limitado a 5. Os valores maiores que 5 são ignorados e 5 são usados. No Windows Server 2003 e no Windows 2000 Server, o valor será respeitado.

Os aplicativos devem ter cuidado para passar valores razoáveis em MaxCalls. Valores grandes em Servidor, Servidor Avançado ou Datacenter Server podem fazer com que uma grande quantidade de memória de pool não paginado seja usada. Usar um valor muito pequeno também é desfavorável, pois pode resultar em pacotes TCP SYN sendo atendidos pelo TCP RST do servidor se a fila de lista de pendências for esgotada. Um desenvolvedor de aplicativos deve equilibrar os requisitos de volume de memória versus escalabilidade ao determinar o valor adequado para MaxCalls.

Quando o computador está configurado para usar a associação seletiva, o retorno bem-sucedido não garante que o servidor tenha criado pontos de extremidade para todos os adaptadores de rede presentes no computador. O tempo de execução do RPC pode não escutar alguns adaptadores de rede, dependendo das configurações de associação seletiva. Além disso, se uma interface ainda não tiver recebido um endereço IP usando DHCP, o servidor RPC não escutará no adaptador de rede até que um endereço DHCP seja atribuído a ele. Um retorno bem-sucedido implica que o servidor está escutando em pelo menos um adaptador de rede; a lista completa dos identificadores de associação sobre os quais chamadas de procedimento remoto podem ser recebidas pode ser obtida com uma chamada para a função RpcServerInqBindings.

Para obter mais informações, consulte Associação do lado do servidor, Associação de cadeia de caracteres, Configurando o registro para alocações de porta e associação seletiva, e Enfileiramento de mensagens RPC e a mensagem de páginas de referência MIDL e ncadg_mq.

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