Função RpcServerRegisterIf2 (rpcdce.h)

Artigo
03/15/2023

A função RpcServerRegisterIf2 registra uma interface com a biblioteca de tempo de execução RPC.

Sintaxe

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

Parâmetros

IfSpec

Estrutura gerada por MIDL que indica a interface a ser registrada.

MgrTypeUuid

Ponteiro para um UUID de tipo a ser associado ao parâmetro MgrEpv . Especificar um valor de parâmetro nulo (ou um UUID nulo) registra IfSpec com um UUID de tipo nulo.

MgrEpv

EPV (vetor de ponto de entrada) das rotinas do gerente. Para usar o EPV padrão gerado por MIDL, especifique um valor nulo . Para obter mais informações, consulte RPC_MGR_EPV.

Flags

Sinalizadores. Para obter uma lista de valores de sinalizador, consulte Sinalizadores de registro de interface.

MaxCalls

Número máximo de solicitações simultâneas de chamada de procedimento remoto que o servidor pode aceitar em uma interface de escuta automática . O parâmetro MaxCalls só é aplicável em uma interface de escuta automática e é ignorado em interfaces que não são escuta automática. A biblioteca de tempo de execução RPC faz seu melhor esforço para garantir que o servidor não permita solicitações de chamada mais simultâneas do que o número de chamadas especificadas em MaxCalls. O número real pode ser maior e pode variar para cada sequência de protocolo.

As chamadas em outras interfaces são regidas pelo valor do parâmetro MaxCalls em todo o processo especificado na chamada de função RpcServerListen .

Se o número de chamadas simultâneas não for uma preocupação, você poderá obter um desempenho ligeiramente melhor do lado do servidor especificando o valor padrão usando RPC_C_LISTEN_MAX_CALLS_DEFAULT. Isso alivia o ambiente de tempo de execução do RPC de impor uma restrição desnecessária.

MaxRpcSize

Tamanho máximo de blocos de dados de entrada, em bytes. Esse parâmetro pode ser usado para ajudar a evitar ataques mal-intencionados de negação de serviço. Se o bloco de dados de uma chamada de procedimento remoto for maior que MaxRpcSize, a biblioteca de tempo de execução RPC rejeitará a chamada e enviará um erro de RPC_S_ACCESS_DENIED para o cliente. Especificar um valor de (int sem sinal) –1 para esse parâmetro remove o limite do tamanho dos blocos de dados de entrada. Esse parâmetro não tem efeito sobre as chamadas feitas sobre o protocolo ncalrpc .

IfCallbackFn

Função de retorno de chamada de segurança ou NULL para nenhum retorno de chamada. Cada interface registrada pode ter uma função de retorno de chamada diferente. Consulte Observações.

Valor retornado

Retorna RPC_S_OK após o sucesso.

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

Comentários

Os parâmetros e efeitos da função RpcServerRegisterIf2 estendem os da função RpcServerRegisterIf . A diferença é a capacidade de registrar uma interface de escuta automática e especificar uma função de retorno de chamada de segurança.

O código do aplicativo de servidor chama RpcServerRegisterIf2 para registrar uma interface. Para registrar uma interface, o servidor fornece as seguintes informações:

Especificação da interface
A especificação da interface é uma estrutura de dados gerada pelo compilador MIDL.
Tipo de gerenciador UUID e EPV do gerente
O tipo de gerenciador UUID e o EPV do gerente determinam qual rotina de gerente é executada quando um servidor recebe uma solicitação de chamada de procedimento remoto de um cliente. Para cada implementação de uma interface oferecida por um servidor, ela deve registrar um EPV de gerenciador separado.

Observe que, ao especificar um UUID de tipo de gerenciador não nulo, o servidor também deve chamar RpcObjectSetType para registrar objetos desse tipo não nulo.

Especificar os sinalizadores de RPC_IF_AUTOLISTEN marca a interface como uma interface de escuta automática . O tempo de execução começa a escutar chamadas assim que a interface é registrada e para de escutar quando a interface não é registrada. Uma chamada para RpcServerUnregisterIf para essa interface aguarda a conclusão de todas as chamadas pendentes nessa interface. As chamadas para as funções RpcServerListen e RpcMgmtStopServerListening não afetam a interface nem uma chamada para a função RpcServerUnregisterIf com IfSpec definido como o valor NULL. Isso permite que uma DLL registre interfaces RPC ou remova-as do registro sem alterar o estado RPC do aplicativo main.

Especificar uma função de retorno de chamada de segurança permite que o aplicativo de servidor restrinja o acesso a suas interfaces em uma base de cliente individual. Ou seja, por padrão, a segurança é opcional; o tempo de execução do servidor enviará chamadas não gerenciadas mesmo se o servidor tiver chamado a função RpcServerRegisterAuthInfo . Se o servidor quiser aceitar apenas clientes autenticados, uma função de retorno de chamada de interface deverá chamar a função RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient ou RpcServerInqCallAttributes para recuperar o nível de segurança ou tentar representar o cliente com a função RpcImpersonateClient . Ele também pode especificar o sinalizador RPC_IF_ALLOW_SECURE_ONLY nos sinalizadores de interface para rejeitar chamadas não autenticadas.

Quando um aplicativo de servidor especifica uma função de retorno de chamada de segurança para suas interfaces, o tempo de execução do RPC rejeita automaticamente chamadas sem informações de autenticação para essa interface. Além disso, o tempo de execução registra as interfaces usadas por cada cliente. Quando um cliente faz um RPC para uma interface que não foi usada durante a sessão de comunicação atual, a biblioteca de tempo de execução do RPC chama a função de retorno de chamada de segurança da interface. Especificar RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH sinalizador impedirá a rejeição automática de clientes não autenticados. Observe que as chamadas na chamada sessão de segurança NULL podem ter informações de autenticação, mesmo que venham de clientes anônimos. Portanto, a existência de um retorno de chamada por si só não é suficiente para impedir que clientes anônimos se conectem. A função de retorno de chamada de segurança deve marcar para isso ou o sinalizador RPC_IF_ALLOW_SECURE_ONLY deve ser usado. RPC_IF_ALLOW_SECURE_ONLY rejeita chamadas de sessão nulas somente no Windows XP e versões posteriores do Windows.

Para obter a assinatura da função de retorno de chamada, consulte RPC_IF_CALLBACK_FN.

A função de retorno de chamada deverá retornar RPC_S_OK, se o cliente tiver permissão para chamar métodos nessa interface. Qualquer outro código de retorno fará com que o cliente receba a exceção RPC_S_ACCESS_DENIED.

Em alguns casos, o tempo de execução do RPC pode chamar a função de retorno de chamada de segurança mais de uma vez por cliente, por interface. Verifique se a função de retorno de chamada pode lidar com essa possibilidade.

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