Função CreateIpForwardEntry (iphlpapi.h)
A função CreateIpForwardEntry cria uma rota na tabela de roteamento IPv4 do computador local.
Sintaxe
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Parâmetros
[in] pRoute
Um ponteiro para uma estrutura MIB_IPFORWARDROW que especifica as informações para a nova rota. O chamador deve especificar valores para todos os membros dessa estrutura. O chamador deve especificar MIB_IPPROTO_NETMGMT para o membro dwForwardProto do MIB_IPFORWARDROW.
Valor retornado
A função retornará NO_ERROR (zero) se a função for bem-sucedida.
Se a função falhar, o valor retornado será um dos seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
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). |
|
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 dwForwardProto de MIB_IPFORWARDROW não tiver sido definido como MIB_IPPROTO_NETMGMT, o membro dwForwardMask da estrutura PMIB_IPFORWARDROW não for uma máscara de sub-rede IPv4 válida ou um dos outros membros da estrutura MIB_IPFORWARDROW for inválido. |
|
O transporte IPv4 não está configurado no computador local. |
|
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 , CreateIpForwardEntry 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, o CreateIpForwardEntry 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 de MIB_IPFORWARDROW apontados pelo parâmetro de rota não são usados atualmente por CreateIpForwardEntry. Esses membros incluem dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 e dwForwardMetric5.
Uma nova rota criada por CreateIpForwardEntry terá automaticamente um valor padrão para dwForwardAge de INFINITE.
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 CreateIpForwardEntry só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se CreateIpForwardEntry 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.
A função CreateIpForwardEntry 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.
Exemplos
O exemplo a seguir demonstra como alterar o gateway padrão para NewGateway. Simplesmente chamar GetIpForwardTable, alterar o gateway e, em seguida, 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.
#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 = 0xDDCCBBAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int 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
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\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 we 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 = 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 resources
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
Referência de função auxiliar de IP