Compartilhar via


Função SetIpForwardEntry (iphlpapi.h)

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

Sintaxe

IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Parâmetros

[in] pRoute

Um ponteiro para uma estrutura MIB_IPFORWARDROW que especifica as novas informações para a rota existente. O chamador deve especificar MIB_IPPROTO_NETMGMT para o membro dwForwardProto dessa estrutura. O chamador também deve especificar valores para os membros dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop e dwForwardPolicy da estrutura.

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.

Código de retorno Descrição
ERROR_ACCESS_DENIED
Acesso 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_FILE_NOT_FOUND
O sistema não pode encontrar o arquivo especificado. Esse erro é retornado no Windows Vista e, posteriormente, se o adaptador de rede especificado pelo membro dwForwardIfIndex da estrutura MIB_IPFORWARDROW apontada pelo parâmetro pRoute não puder ser encontrado.
ERROR_INVALID_PARAMETER
O parâmetro pRoute é NULL ou SetIpForwardEntry não consegue ler da memória apontada pelo pRoute ou um dos membros da estrutura MIB_IPFORWARDROW é inválido.
ERROR_NOT_FOUND
O elemento não foi encontrado. O erro é retornado no Windows Vista e posterior quando a função DeleteIpForwardEntry e, em seguida, a função SetIpForwardEntry são chamadas para a mesma entrada da tabela de rotas IPv4.
ERROR_NOT_SUPPORTED
A solicitação não terá suporte. Esse valor será retornado se o transporte IPv4 não estiver configurado no computador local. Esse erro também é retornado no Windows Server 2003 e anterior se nenhuma pilha TCP/IP estiver configurada no computador local.
Outros
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

O membro dwForwardProto de MIB_IPFORWARDROW estrutura apontada pelo parâmetro de rota deve ser definido como MIB_IPPROTO_NETMGMT caso contrário , SetIpForwardEntry 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 DHCP (Dynamic Host Configuration Protocol), o SNMP (Simple Network Management Protocol) ou chamadas para as funções CreateIpForwardEntry, DeleteIpForwardEntry ou SetIpForwardEntry .

No Windows Vista e no Windows Server 2008, a métrica de rota especificada no membro dwForwardMetric1 da estrutura de MIB_IPFORWARDROW apontada pelo parâmetro pRoute representa uma combinação da métrica de rota adicionada à métrica de interface especificada no membro Métrica da estrutura MIB_IPINTERFACE_ROW da interface associada. Portanto, o membro dwForwardMetric1 da estrutura MIB_IPFORWARDROW deve ser igual ou maior que o membro Metric da estrutura de MIB_IPINTERFACE_ROW associada. Se um aplicativo quiser definir a métrica de rota como 0, o membro dwForwardMetric1 da estrutura MIB_IPFORWARDROW deverá ser definido igual ao valor da métrica de interface especificada no membro Metric da estrutura MIB_IPINTERFACE_ROW associada. Um aplicativo pode recuperar a métrica de interface chamando a função GetIpInterfaceEntry .

No Windows Vista e no Windows Server 2008, a função SetIpForwardEntry 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.

O membro dwForwardAge que a estrutura MIB_IPFORWARDROW apontada pelo parâmetro de rota não é usado atualmente por SetIpForwardEntry. O membro dwForwardAge será usado somente se o RRAS (Serviço de Roteamento e Acesso Remoto) estiver em execução e, em seguida, somente para rotas do tipo MIB_IPPROTO_NETMGMT conforme definido na página de referência identificadores de protocolo . Quando dwForwardAge estiver definido como INFINITE, a rota não será removida com base em um tempo limite

value. Qualquer outro valor para dwForwardAge especifica o número de segundos até que a pilha TCP/IP remova a rota da tabela de roteamento de rede.

Uma rota modificada por SetIpForwardEntry terá automaticamente um valor padrão para dwForwardAge de INFINITE.

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

Para criar uma nova rota na tabela de roteamento de IP, use a função CreateIpForwardEntry . Para recuperar a tabela de roteamento de IP, chame a função GetIpForwardTable .

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

Essa função 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 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 para exigirAdministrator. 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 a seguir demonstra como alterar o gateway padrão para NewGateway. Simplesmente chamar GetIpForwardTable, alterar o gateway e chamar SetIpForwardEntry não alterará a rota, mas apenas adicionará uma nova. Se, por algum motivo, houver vários gateways padrão presentes, esse código os excluirá. Observe que o novo gateway deve ser viável; caso contrário, TCP/IP ignorará a alteração.

Nota A execução desse código alterará as tabelas de roteamento de IP e provavelmente fará com que a atividade de rede falhe.
 

Windows Vista e posterior: Quando a função DeleteIpForwardEntry e a função SetIpForwardEntry são chamadas para a mesma entrada de tabela de rotas no Windows Vista e posteriores, ERROR_NOT_FOUND é retornado. A maneira adequada de replicar este exemplo no Windows Vista e posterior é usar a função CreateIpForwardEntry para criar a nova entrada de tabela de rotas e, em seguida, excluir a entrada antiga da tabela de rotas chamando a função DeleteIpForwardEntry .

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

// #ifndef WIN32_LEAN_AND_MEAN
// #define WIN32_LEAN_AND_MEAN
// #endif

// #pragma warning(push)
// #pragma warning(disable: 4127)

// #include <windows.h>

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */

int main()
{

    // Declare and initialize variables.

    /* variables used for SetIfForwardEntry */

    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
    DWORD i;

// Find out how big our buffer needs to be.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate the memory for the table
        pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize);
        if (pIpForwardTable == NULL) {
            printf("Unable to allocate memory for the IPFORWARDTALE\n");
            exit(1);
        }
        // Now get the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // We have found the default gateway.
            if (!pRow) {
                // Allocate some memory to store the row in. This is easier than filling
                // in the row structure ourselves, and we can be sure to change only the
                // gateway address.
                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 the other properties of the route will
// be the same as they were previously.
    pRow->dwForwardNextHop = NewGateway;

// Create a new route entry for the default gateway.
    dwStatus = SetIpForwardEntry(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 resources.
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);
}


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

Confira também

Createipforwardentry

DeleteIpForwardEntry

GetIpForwardTable

GetIpInterfaceEntry

Referência de função auxiliar de IP

Página Inicial do Auxiliar de IP

MIB_IPFORWARDROW

MIB_IPINTERFACE_ROW