Función RtlIpv4StringToAddressA (ip2string.h)

Artículo
08/24/2023

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

Sintaxis

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

Parámetros

[in] S

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

[in] Strict

Valor que indica si la cadena debe ser una dirección IPv4 representada en notación punto-decimal estricta de cuatro partes. 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. Para obtener información detallada, consulte la sección Comentarios.

[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, 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 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 del 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 del error devuelto.

Comentarios

La función RtlIpv4StringToAddress se usa para convertir una representación de cadena de la dirección IPv4 en 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 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 S debe estar en notación punto-decimal estricta. 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 el parámetro S puede estar en cualquiera de los distintos formatos posibles. Cuando el búfer al que apunta el 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 las direcciones de red de clase B como "128.net.host". Cuando el búfer al que apunta el 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 los tres bytes derecho de la dirección de red. Esto hace que el formato de dirección de dos partes sea cómodo para especificar direcciones de red de clase A como "net.host". Cuando el búfer al que apunta el 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 parámetro Terminador apunta al carácter que finalizó la cadena que se convirtió. Esto permite a una aplicación pasar una cadena que contiene una dirección IP más información adicional a la función RtlIpv4StringToAddress y, a continuación, analizar la información restante.

Cuando se define UNICODE o _UNICODE, RtlIpv4StringToAddress se define en 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 Terminator 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 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 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 Convenciones para prototipos de función.

Requisitos


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, Ip2string.h)
Library	ntdll.lib
Archivo DLL	ntdll.dll