Função RtmAddRouteToDest (rtmv2.h)

Artigo
03/13/2024

A função RtmAddRouteToDest adiciona uma nova rota à tabela de roteamento ou atualiza uma rota existente na tabela de roteamento. Se a melhor rota for alterada, uma notificação de alteração será gerada.

Sintaxe

DWORD RtmAddRouteToDest(
  [in]      RTM_ENTITY_HANDLE       RtmRegHandle,
  [in, out] PRTM_ROUTE_HANDLE       RouteHandle,
  [in]      PRTM_NET_ADDRESS        DestAddress,
  [in]      PRTM_ROUTE_INFO         RouteInfo,
  [in]      ULONG                   TimeToLive,
  [in]      RTM_ROUTE_LIST_HANDLE   RouteListHandle,
  [in]      RTM_NOTIFY_FLAGS        NotifyType,
  [in]      RTM_NOTIFY_HANDLE       NotifyHandle,
  [in, out] PRTM_ROUTE_CHANGE_FLAGS ChangeFlags
);

Parâmetros

[in] RtmRegHandle

Manipule para o cliente obtido de uma chamada anterior para RtmRegisterEntity.

[in, out] RouteHandle

Se o cliente tiver um identificador (atualizando uma rota): na entrada, RouteHandle será um ponteiro para o identificador de rota. Na saída, RouteHandle permanece inalterado.

Se o cliente não tiver um identificador e um identificador precisar ser retornado (o cliente está adicionando ou atualizando uma rota): Na entrada, RouteHandle será um ponteiro para NULL. Na saída, RouteHandle recebe um ponteiro para o identificador de rota. Os valores em RouteInfo são usados para identificar a rota a ser atualizada.

Se um identificador não precisar ser retornado (o cliente está adicionando ou atualizando uma rota): na entrada, RouteHandle é NULL. Os valores em RouteInfo são usados para identificar a rota a ser atualizada.

[in] DestAddress

Ponteiro para o endereço de rede de destino ao qual a rota está sendo adicionada ou atualizada.

[in] RouteInfo

Ponteiro para as informações de rota a serem adicionadas ou atualizadas.

[in] TimeToLive

Especifica a hora, em milissegundos, após a qual a rota expirou. Especifique INFINITE para impedir que as rotas expirem.

[in] RouteListHandle

Manipule para uma lista de rotas para a qual mover a rota. Esse parâmetro é opcional e pode ser definido como NULL.

[in] NotifyType

Defina esse parâmetro como NULL. Esse parâmetro é reservado para uso futuro.

[in] NotifyHandle

Defina esse parâmetro como NULL. Esse parâmetro é reservado para uso futuro.

[in, out] ChangeFlags

Na entrada, ChangeFlags é um ponteiro para um tipo de dados RTM_ROUTE_CHANGE_FLAGS que indica se o gerenciador de tabelas de roteamento deve adicionar uma nova rota ou atualizar uma existente.

Na saída, ChangeFlags é um ponteiro para um tipo de dados RTM_ROUTE_CHANGE_FLAGS que recebe o sinalizador que indica o tipo de alteração que foi realmente executada e se a melhor rota foi alterada. Os sinalizadores a seguir são usados.

Constante	Significado
RTM_ROUTE_CHANGE_FIRST	Indica que o gerenciador de tabelas de roteamento não deve marcar o membro Neighbor do parâmetro RouteInfo ao determinar se duas rotas são iguais.
RTM_ROUTE_CHANGE_NEW	Retornado pelo gerenciador de tabelas de roteamento para indicar que uma nova rota foi criada.
RTM_ROUTE_CHANGE_BEST	Retornado pelo gerenciador de tabelas de roteamento para indicar que a rota que foi adicionada ou atualizada era a melhor rota ou que, devido à alteração, uma nova rota se tornou a melhor rota.

Retornar valor

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Valor	Significado
ERROR_ACCESS_DENIED	O cliente de chamada não possui essa rota.
ERROR_INVALID_HANDLE	O manipulador é inválido.
ERROR_INVALID_PARAMETER	Um parâmetro contém informações incorretas.
ERROR_NOT_ENOUGH_MEMORY	Não há memória suficiente para concluir essa operação.

Comentários

Duas rotas serão consideradas iguais se os seguintes valores forem iguais:

A rede de destino
O proprietário da rota
O vizinho que forneceu a rota

Quando um cliente está atualizando uma rota, é mais eficiente passar um identificador para a rota a ser atualizada no parâmetro RouteHandle , pois o gerenciador de tabelas de roteamento não precisa executar uma pesquisa para a rota na tabela de roteamento.

Se um identificador tiver sido retornado, libere o identificador quando ele não for mais necessário chamando RtmReleaseRoutes.

Para obter o código de exemplo que usa essa função, consulte Adicionar e atualizar rotas usando RtmAddRouteToDest.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Nenhum compatível
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	rtmv2.h
Biblioteca	Rtm.lib
DLL	Rtm.dll