Compartilhar via


Função DeleteIpForwardEntry (iphlpapi.h)

A função DeleteIpForwardEntry exclui uma rota existente na tabela de roteamento IPv4 do computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parâmetros

[in] pRoute

Um ponteiro para uma estrutura MIB_IPFORWARDROW . Essa estrutura especifica informações que identificam a rota a ser excluída. O chamador deve especificar valores para os membros dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop e dwForwardProto da estrutura.

Valor retornado

A função retornará NO_ERROR (zero) se a rotina for bem-sucedida.

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

Código do erro Significado
ERROR_ACCESS_DENIED
O acesso foi negado. Esse erro é retornado no Windows Vista e no Windows Server 2008 em várias condições que incluem o seguinte: o usuário não tem os privilégios administrativos necessários no computador local ou o aplicativo não está em execução em um shell aprimorado como administrador interno (administrador RunAs).
ERROR_INVALID_PARAMETER
Um parâmetro de entrada é inválido, nenhuma ação foi tomada. Esse erro será retornado se o parâmetro pRoute for NULL, o membro dwForwardMask da estrutura PMIB_IPFORWARDROW não for uma máscara de sub-rede IPv4 válida, o membro dwForwardIfIndex for NULL ou um dos outros membros da estrutura MIB_IPFORWARDROW for inválido.
ERROR_NOT_FOUND
O parâmetro pRoute aponta para uma entrada de rota que não existe.
ERROR_NOT_SUPPORTED
O transporte IPv4 não está configurado no computador local.
(outro)
A função pode retornar outros códigos de erro.
 

Se a função falhar, use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

O membro dwForwardProto de MIB_IPFORWARDROW ponteiro de estrutura para pelo parâmetro route deve ser definido como MIB_IPPROTO_NETMGMT caso contrário , DeleteIpForwardEntry falhará. Identificadores de protocolo de roteamento são usados para identificar informações de rota para o protocolo de roteamento especificado. Por exemplo, MIB_IPPROTO_NETMGMT é usado para identificar informações de rota para o conjunto de roteamento de IP por meio do gerenciamento de rede, como o protocolo DHCP, o protocolo SNMP ou chamadas para as funções CreateIpForwardEntry, DeleteIpForwardEntry ou SetIpForwardEntry .

No Windows Vista e no Windows Server 2008, o DeleteIpForwardEntry só funciona em interfaces com uma única sub-interface (em que o LUID da interface e o LUID de subinterface são os mesmos). O membro dwForwardIfIndex da estrutura MIB_IPFORWARDROW especifica a interface .

Vários membros da estrutura MIB_IPFORWARDROW apontados pelo parâmetro de rota não são usados atualmente por CreateIpForwardEntry. Esses membros incluem dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.

Para modificar uma rota existente na tabela de roteamento IPv4, use a função SetIpForwardEntry . Para recuperar a tabela de roteamento IPv4, chame a função GetIpForwardTable .

No Windows Vista e posteriores, a função DeleteIpForwardEntry só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se DeleteIpForwardEntry for chamado por um usuário que não seja membro do grupo Administradores, a chamada de função falhará e ERROR_ACCESS_DENIED será retornado.

A função DeleteIpForwardEntry também pode falhar devido ao UAC (controle de conta de usuário) no Windows Vista e posterior. Se um aplicativo que contém essa função for executado por um usuário conectado como um membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido como requireAdministrator. Se o aplicativo não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores diferente do Administrador interno deverá executar o aplicativo em um shell aprimorado como administrador interno (administrador RunAs) para que essa função tenha êxito.

Nota No Windows NT 4.0 e Windows 2000 e posterior, essa função executa uma operação privilegiada. Para que essa função seja executada com êxito, o chamador deve estar conectado como membro do grupo Administradores ou do grupo NetworkConfigurationOperators.
 

Exemplos

O exemplo de código a seguir mostra como alterar o gateway padrão para NewGateway. Ao chamar GetIpForwardTable, alterar o gateway e chamar SetIpForwardEntry não alterará a rota, mas adicionará uma nova. Se houver vários gateways padrão, esse código os excluirá. Lembre-se de que o novo gateway deve ser viável; caso contrário, o TCP/IP ignorará a alteração.

Nota A execução desse código alterará as tabelas de roteamento de IP e provavelmente causará falha na atividade de rede.
 
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

#pragma comment(lib, "iphlpapi.lib")

int main()
{
    // Declare and initialize variables
    PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
    PMIB_IPFORWARDROW pRow = NULL;
    DWORD dwSize = 0;
    BOOL bOrder = FALSE;
    DWORD dwStatus = 0;
    DWORD NewGateway = 0xDDBBCCAA;      // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA

    unsigned int i;

// Identify the required size of the buffer.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate memory for the table.
        if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
            printf("Malloc failed. Out of memory.\n");
            exit(1);
        }
        // Retrieve the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
// 
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // The default gateway was found.
            if (!pRow) {
                // Allocate memory to store the row. This is easier than manually filling
                // the row structure; only the gateway address is changed.
                //
                pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
                if (!pRow) {
                    printf("Malloc failed. Out of memory.\n");
                    exit(1);
                }
                // Copy the row.
                memcpy(pRow, &(pIpForwardTable->table[i]),
                       sizeof (MIB_IPFORWARDROW));
            }
            // Delete the old default gateway entry.
            dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));

            if (dwStatus != ERROR_SUCCESS) {
                printf("Could not delete old gateway\n");
                exit(1);
            }
        }
    }

// Set the nexthop field to our new gateway. All other properties of the route will
// remain the same.
    pRow->dwForwardNextHop = NewGateway;

// Create a new route entry for the default gateway.
    dwStatus = CreateIpForwardEntry(pRow);

    if (dwStatus == NO_ERROR)
        printf("Gateway changed successfully\n");
    else if (dwStatus == ERROR_INVALID_PARAMETER)
        printf("Invalid parameter.\n");
    else
        printf("Error: %d\n", dwStatus);

// Free the memory. 
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);

    exit(0);
}

Requisitos

   
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 iphlpapi.h
Biblioteca Iphlpapi.lib
DLL Iphlpapi.dll

Confira também

Createipforwardentry

FormatMessage

GetIpForwardTable

Referência de função auxiliar de IP

Página Inicial do Auxiliar de IP

MIB_IPFORWARDROW

SetIpForwardEntry