Función SetIpInterfaceEntry (netioapi.h)

Artículo
03/15/2023

La función SetIpInterfaceEntry establece las propiedades de una interfaz IP en el equipo local.

Sintaxis

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpInterfaceEntry(
  [in, out] PMIB_IPINTERFACE_ROW Row
);

Parámetros

[in, out] Row

Puntero a una entrada de estructura de MIB_IPINTERFACE_ROW para una interfaz. En la entrada, el miembro Family del MIB_IPINTERFACE_ROW debe establecerse en AF_INET6 o AF_INET y se debe especificar el miembro InterfaceLuid o InterfaceIndex del MIB_IPINTERFACE_ROW . Cuando se devuelve correctamente, el miembro InterfaceLuid del MIB_IPINTERFACE_ROW se rellena si se especificó el miembro InterfaceIndex de la entrada MIB_IPINTERFACE_ROW .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	Acceso denegado. Este error se devuelve en varias condiciones que incluyen lo siguiente: el usuario carece de los privilegios administrativos necesarios en el equipo local o la aplicación no se ejecuta en un shell mejorado como administrador integrado (administrador de RunAs).
ERROR_FILE_NOT_FOUND	El sistema no encuentra el archivo especificado. Este error se devuelve si el luID de interfaz de red o el índice de interfaz especificado por el miembro InterfaceLuid o InterfaceIndex del MIB_IPINTERFACE_ROW señalado por el parámetro Row no era un valor en el equipo local.
ERROR_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si se pasa un puntero NULL en el parámetro Row , el miembro Family del MIB_IPINTERFACE_ROW señalado por el parámetro Row no se especificó como AF_INET o AF_INET6, o los miembros InterfaceLuid o InterfaceIndex del MIB_IPINTERFACE_ROW señalados por el parámetro Row no se especificaron.
ERROR_NOT_FOUND	No se encontró la interfaz especificada. Este error se devuelve si la interfaz de red especificada por el miembro InterfaceLuid o InterfaceIndex del MIB_IPINTERFACE_ROW señalado por el parámetro Row no coincide con la familia de direcciones IP especificada en el miembro Family de la estructura MIB_IPINTERFACE_ROW .
Otros	Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función SetIpInterfaceEntry se define en Windows Vista y versiones posteriores.

La función SetIpInterfaceEntry se puede usar para modificar una entrada de interfaz IP existente.

En la entrada, el miembro Family de la estructura MIB_IPINTERFACE_ROW a la que apunta el parámetro Row debe inicializarse para AF_INET o AF_INET6. Además de la entrada, se debe inicializar al menos uno de los siguientes miembros de la estructura MIB_IPINTERFACE_ROW apuntado al parámetro Row : InterfaceLuid o InterfaceIndex.

Los campos se usan en el orden indicado anteriormente. Por lo tanto, si se especifica InterfaceLuid , este miembro se usa para determinar la interfaz. Si no se estableció ningún valor para el miembro InterfaceLuid (los valores de este miembro se establecieron en cero), el miembro InterfaceIndex se usará a continuación para determinar la interfaz.

En la salida, el miembro InterfaceLuid de la estructura MIB_IPINTERFACE_ROW a la que apunta el parámetro Row se rellena si se especificó InterfaceIndex .

Los miembros MaxReassemblySize, MinRouterAdvertisementInterval, MaxRouterAdvertisementInterval , Connected, SupportsWakeUpPatterns, SupportsNeighborDiscovery, SupportsRouterDiscovery, ReachableTime, TransmitOffload y ReceiveOffload de la estructura de MIB_IPINTERFACE_ROW a la que apunta la fila se omiten cuando se llama a la función SetIpInterfaceEntry. La pila de red establece estos miembros y no se puede cambiar mediante la función SetIpInterfaceEntry .

Normalmente, una aplicación llamaría a la función GetIpInterfaceTable para recuperar las entradas de la interfaz IP en el equipo local o llamar a la función GetIpInterfaceEntry para recuperar solo la entrada de la interfaz IP que se va a modificar. La estructura MIB_IPINTERFACE_ROW para la entrada de interfaz IP específica se podría modificar y un puntero a esta estructura pasada a la función SetIpInterfaceEntry en el parámetro Row . Sin embargo, para IPv4, una aplicación no debe intentar modificar el miembro SitePrefixLength de la estructura MIB_IPINTERFACE_ROW . Para IPv4, el miembro SitePrefixLength debe establecerse en 0.

Otro posible método para modificar una entrada de interfaz IP existente es usar la función InitializeIpInterfaceEntry para inicializar los campos de una entrada de estructura de MIB_IPINTERFACE_ROW con valores predeterminados. A continuación, establezca el miembro Family y los miembros InterfaceIndex o InterfaceLuid en la estructura MIB_IPINTERFACE_ROW a la que apunta el parámetro Row para que coincida con la interfaz IP que se va a cambiar. Después, una aplicación puede cambiar los campos de la entrada MIB_IPINTERFACE_ROW que desea modificar y, a continuación, llamar a la función SetIpInterfaceEntry . Sin embargo, para IPv4, una aplicación no debe intentar modificar el miembro SitePrefixLength de la estructura MIB_IPINTERFACE_ROW . Para IPv4, el miembro SitePrefixLength debe establecerse en 0. Se debe tener cuidado con este enfoque porque la única manera de determinar todos los campos que se van a cambiar sería comparar los campos de la MIB_IPINTERFACE_ROW de la entrada de interfaz IP específica con campos establecidos por la función InitializeIpInterfaceEntry cuando se inicializa un MIB_IPINTERFACE_ROW en valores predeterminados.

El acceso simultáneo sin privilegios a varias redes de diferentes requisitos de seguridad crea un agujero de seguridad y permite que una aplicación sin privilegios retransmita accidentalmente los datos entre las dos redes. Un ejemplo típico es el acceso simultáneo a una red privada virtual (VPN) e Internet. Windows Server 2003 y Windows XP usan un modelo de host débil, donde RAS impide ese acceso simultáneo aumentando la métrica de ruta de todas las rutas predeterminadas en otras interfaces. Por lo tanto, todo el tráfico se enruta a través de la interfaz VPN, lo que interrumpe otra conectividad de red.

En Windows Vista y versiones posteriores, se usa un modelo de host seguro de forma predeterminada. Si se especifica una dirección IP de origen en la búsqueda de rutas mediante GetBestRoute2 o GetBestRoute, la búsqueda de rutas está restringida a la interfaz de la dirección IP de origen. La modificación de la métrica de ruta por RAS no tiene ningún efecto, ya que la lista de rutas potenciales ni siquiera tiene la ruta para la interfaz VPN, lo que permite el tráfico a Internet. El miembro DisableDefaultRoutes del MIB_IPINTERFACE_ROW se puede usar para deshabilitar mediante la ruta predeterminada en una interfaz. Los clientes VPN pueden usar este miembro como medida de seguridad para restringir la tunelización dividida cuando el cliente VPN no requiere la tunelización dividida. Un cliente VPN puede llamar a la función SetIpInterfaceEntry para establecer el miembro DisableDefaultRoutes en TRUE cuando sea necesario. Un cliente VPN puede consultar el estado actual del miembro DisableDefaultRoutes llamando a la función GetIpInterfaceEntry .

The

Un usuario que inició sesión como miembro del grupo Administradores solo puede llamar a la función SetIpInterfaceEntry . Si un usuario llama a SetIpInterfaceEntry que no es miembro del grupo Administradores, se producirá un error en la llamada de función y se devolverá ERROR_ACCESS_DENIED . Esta función también puede producir un error debido al control de cuentas de usuario (UAC) en Windows Vista y versiones posteriores. Si un usuario que ha iniciado sesión como miembro del grupo Administradores que no sea el administrador integrado ejecuta esta función, se producirá un error en esta llamada a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores distinto del administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de runas) para que esta función se realice correctamente.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	netioapi.h (include Iphlpapi.h)
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll