Función RtlIpv4StringToAddressW (ip2string.h)

Artículo
11/20/2024

La función RtlIpv4StringToAddress convierte una representación de cadena de una dirección IPv4 en una dirección IPv4 binaria.

Sintaxis

NTSYSAPI NTSTATUS RtlIpv4StringToAddressW(
  [in]  PCWSTR  S,
  [in]  BOOLEAN Strict,
  [out] LPCWSTR *Terminator,
  [out] in_addr *Addr
);

Parámetros

[in] S

Puntero a un búfer que contiene la nullrepresentación de cadena terminada en la dirección IPv4.

[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 las cuatro formas posibles, con notación decimal, octal o hexadecimal. Consulte la sección Comentarios para obtener más información.

[out] Terminator

Parámetro que recibe un puntero al carácter que finalizó la cadena convertida. El autor de la llamada puede usar esto para extraer más información de la cadena.

[out] Addr

Puntero donde se va a almacenar la representación binaria de la dirección IPv4.

Valor devuelto

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

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 S 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 S 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 S 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 S 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.

Observaciones

La función RtlIpv4StringToAddress se usa para convertir una representación de cadena de la dirección IPv4 a una dirección IPv4 devuelta en orden de red (bytes ordenados de izquierda a derecha).

rtlIpv4StringToAddress es una función útil que no requiere que el archivo DLL de Windows Sockets se cargue para acceder 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 S debe estar en notación decimal con puntos estrictos. Este formato estricto requiere que se especifiquen cuatro partes. Cada parte se interpreta como un byte decimal de datos y se asigna, 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 parámetro S puede estar en cualquiera de los distintos formatos posibles. Cuando el búfer al que apunta parámetro S contiene una cadena de dirección de tres partes, la última parte se interpreta como una cantidad de 16 bits y se coloca en la derecha más 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 parámetro S 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 derecha más de tres bytes de la dirección de red. Esto facilita el formato de dirección de dos partes para especificar direcciones de red de clase A como "net.host". Cuando el búfer al que apunta parámetro S contiene solo una cadena de dirección de una parte, el valor se almacena directamente en la dirección de red sin reorganizar ningún byte.

Si se ejecuta correctamente, el terminador parámetro apunta al carácter que finalizó la cadena que se convirtió. Esto permite que una aplicación pase una cadena que contenga una dirección IP más información adicional al función RtlIpv4StringToAddress y, a continuación, analice la información restante.

Cuando se define UNICODE o _UNICODE, se define rtlIpv4StringToAddress para RtlIpv4StringToAddressW, la versión Unicode de esta función. El parámetro S se define en el tipo de datos PCWSTR y el parámetro Terminador se define en el tipo de datos LPCWSTR.

Cuando no se definen UNICODE y _UNICODE, rtlIpv4StringToAddress se define en RtlIpv4StringToAddressA, la versión ANSI de esta función. Los parámetros S y Terminator se definen 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 de RtlIpv4StringToAddress no se incluye en el Kit de desarrollo de software (SDK) de Microsoft Windows publicado para Windows Vista. La función rtlIpv4StringToAddress se incluye en la biblioteca de importación de 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.

Nota

El encabezado ip2string.h define RtlIpv4StringToAddress como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2008 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	ip2string.h (incluya Mstcpip.h, Ip2string.h)
biblioteca de	ntdll.lib
DLL de	ntdll.dll