Función RtlIpv4StringToAddressExW (ip2string.h)

Artículo
08/24/2023

La función RtlIpv4StringToAddressEx convierte una representación de cadena de una dirección IPv4 y un número de puerto en una dirección y puerto IPv4 binarios.

Sintaxis

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [out] PUSHORT Port
);

Parámetros

[in] AddressString

Puntero a un búfer que contiene la representación de cadena terminada en NULL de la dirección IPv4 seguida de una representación opcional de dos puntos y cadena de un número de puerto.

[in] Strict

Valor que indica si la cadena debe ser una dirección IPv4 representada en notación decimal con puntos de cuatro partes estricta. Si este parámetro es TRUE, la cadena debe tener puntos decimales con cuatro partes. Si este parámetro es FALSE, se permiten cualquiera de cuatro formularios para la representación de cadena de la dirección Ipv4, con notación decimal, octal o hexadecimal. Para obtener información detallada, consulte la sección Comentarios.

[out] Address

Puntero donde se va a almacenar la representación binaria de la dirección IPv4. La dirección IPv4 se almacena en orden de bytes de red.

[out] Port

Puntero donde se va a almacenar la representación binaria del número de puerto. El número de puerto se devuelve en orden de bytes de red. Si no se especificó ningún puerto en la cadena a la que apunta el parámetro AddressString , el parámetro Port se establece en cero.

Valor devuelto

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

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
STATUS_INVALID_PARAMETER	Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro Strict se estableció en TRUE, pero la cadena a la que apunta el parámetro AddressString no contenía una representación de cadena decimal con puntos de cuatro partes de una dirección IPv4. Este error también se devuelve si la cadena a la que apunta el parámetro AddressString no contenía una representación de cadena adecuada de una dirección IPv4. Este código de error se define en el archivo de encabezado Ntstatus.h.
Otros	Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Código devuelto

Descripción

STATUS_INVALID_PARAMETER

Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro Strict se estableció en TRUE, pero la cadena a la que apunta el parámetro AddressString no contenía una representación de cadena decimal con puntos de cuatro partes de una dirección IPv4. Este error también se devuelve si la cadena a la que apunta el parámetro AddressString no contenía una representación de cadena adecuada de una dirección IPv4.

Este código de error se define en el archivo de encabezado Ntstatus.h.

Otros

Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función RtlIpv4StringToAddressEx se usa para convertir una representación de cadena de la dirección iPv4 y el número de puerto en una dirección IPv4 binaria y un número de puerto. La dirección IPv4 se devuelve en orden de red (bytes ordenados de izquierda a derecha). El número de puerto se devuelve en orden de red.

RtlIpv4StringToAddressEx es una función conveniente que no requiere que el archivo DLL de Windows Sockets se cargue para tener acceso a una función proporcionada en Windows Sockets para realizar la conversión de cadena a dirección IP.

Si el parámetro Strict se establece en TRUE, la cadena a la que apunta el parámetro AddressString debe estar en notación decimal de puntos estricta. Este formato estricto requiere que se especifiquen cuatro partes. Cada parte se interpreta como un byte decimal de datos y asignado, de izquierda a derecha, a los cuatro bytes de una dirección IPv4.

Cuando el parámetro Strict se establece en FALSE, la cadena a la que apunta el parámetro AddressString puede estar en cualquiera de los distintos formatos posibles. Cuando el búfer al que apunta el parámetro AddressString contiene una cadena de dirección de tres partes, la última parte se interpreta como una cantidad de 16 bits y se coloca en el extremo derecho de dos bytes de la dirección de red. Esto facilita el formato de dirección de tres partes para especificar direcciones de red de clase B como "128.net.host". Cuando el búfer al que apunta el parámetro AddressString contiene una cadena de dirección de dos partes, la última parte se interpreta como una cantidad de 24 bits y se coloca en la parte derecha más de tres bytes de la dirección de red. Esto facilita el formato de dirección de dos partes para especificar las direcciones de red de clase A como "net.host". Cuando el búfer al que apunta el parámetro AddressString solo contiene una cadena de dirección de una parte, el valor se almacena directamente en la dirección de red sin reorganizar ningún byte.

El búfer al que apunta el parámetro AddressString puede contener la cadena de dirección IPv4 seguida de dos puntos opcionales y la representación de cadena de un número de puerto. Si se incluye una cadena de número de puerto en el búfer al que apunta el parámetro AddressString , la representación binaria del número de puerto se devuelve en el parámetro Port . Si el búfer al que apunta el parámetro AddressString no contiene un número de puerto, se devuelve un cero en el parámetro Port .

Cuando se define UNICODE o _UNICODE, RtlIpv4StringToAddressEx se define en RtlIpv4StringToAddressExW, la versión Unicode de esta función. El parámetro AddressString se define en el tipo de datos PCWSTR.

Cuando no se definen UNICODE y _UNICODE, RtlIpv4StringToAddressEx se define en RtlIpv4StringToAddressExA, la versión ANSI de esta función. El parámetro AddressString se define en el tipo de datos PCSTR.

La estructura IN_ADDR se define en el archivo de encabezado Inaddr.h .

Una biblioteca de importación que contiene la función RtlIpv4StringToAddressEx no se incluye en microsoft Kit de desarrollo de software de Windows (SDK) publicado para Windows Vista. La función RtlIpv4StringToAddressEx se incluye en la biblioteca de importación Ntdll.lib incluida en el Kit de controladores de Windows (WDK). Una aplicación también podría usar las funciones GetModuleHandle y GetProcAddress para recuperar el puntero de función de la Ntdll.dll y llamar a esta función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	ip2string.h (incluya Mstcpip.h)
Library	ntdll.lib
Archivo DLL	ntdll.dll