Função RtmAddNextHop (rtmv2.h)

Artigo
08/25/2023

A função RtmAddNextHop adiciona uma nova entrada de próximo salto ou atualiza uma entrada de próximo salto existente para a lista de próximo salto de um cliente. Se já existir um próximo salto, o gerenciador de tabela de roteamento retornará um identificador para o próximo salto. Esse identificador pode ser usado para especificar um próximo salto para um destino ao adicionar ou atualizar uma rota.

Sintaxe

DWORD RtmAddNextHop(
  [in]      RTM_ENTITY_HANDLE         RtmRegHandle,
  [in]      PRTM_NEXTHOP_INFO         NextHopInfo,
  [in, out] PRTM_NEXTHOP_HANDLE       NextHopHandle,
  [out]     PRTM_NEXTHOP_CHANGE_FLAGS ChangeFlags
);

Parâmetros

[in] RtmRegHandle

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

[in] NextHopInfo

Ponteiro para uma estrutura que contém informações que identificam o próximo salto para adicionar ou atualizar. Os membros NextHopOwner e State são ignorados; esses membros são definidos pelo gerenciador de tabelas de roteamento. O membro Flags pode ser um dos valores a seguir.

Sinalizador	Significado
RTM_NEXTHOP_FLAGS_REMOTE	Este próximo salto aponta para um destino remoto que não está diretamente acessível. Para obter o caminho completo, o cliente deve executar uma pesquisa recursiva.
RTM_NEXTHOP_FLAGS_DOWN	Esse sinalizador é reservado para uso futuro.

[in, out] NextHopHandle

Se o cliente tiver um identificador (o cliente está atualizando um próximo salto): na entrada, NextHopHandle é um ponteiro para o identificador do próximo salto. Na saída, NextHopHandle permanece inalterado.

Se o cliente não tiver um identificador e um identificador precisar ser retornado (o cliente está adicionando ou atualizando um próximo salto): na entrada, NextHopHandle é um ponteiro para NULL. Na saída, NextHopHandle recebe um ponteiro para o identificador do próximo salto. Os valores em NextHopInfo são usados para identificar o próximo salto a ser atualizado.

Se um identificador não precisar ser retornado (o cliente está adicionando ou atualizando um próximo salto): na entrada, NextHopHandle é NULL. Os valores em NextHopInfo são usados para identificar o próximo salto a ser atualizado.

[out] ChangeFlags

Na entrada, ChangeFlags é um ponteiro para um tipo de dados RTM_NEXTHOP_CHANGE_FLAGS .

Na saída, ChangeFlags recebe um sinalizador que indica se um próximo salto foi adicionado ou atualizado. Se ChangeFlags for zero, um próximo salto será atualizado; se ChangeFlags for RTM_NEXTHOP_CHANGE_NEW, um próximo salto será adicionado.

Valor retornado

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

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

Valor	Significado
ERROR_ACCESS_DENIED	O cliente de chamada não possui este próximo salto.
ERROR_NOT_ENOUGH_MEMORY	Não há memória suficiente para concluir essa operação.

Comentários

Se NextHopHandle apontar para um identificador não NULL , o próximo salto especificado pelo identificador será atualizado. Caso contrário, uma pesquisa será feita para o endereço especificado por NextHopInfo. Se um próximo salto for encontrado, ele será atualizado. Se nenhuma correspondência for encontrada, um novo próximo salto será adicionado.

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

Requisitos


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