Función WSAAddressToStringA (winsock2.h)

La función WSAAddressToString convierte todos los componentes de una estructura de sockaddr en una representación de cadena legible de la dirección.

Esto está pensado para usarse principalmente con fines de visualización. Si el autor de la llamada requiere que un proveedor determinado realice la traducción, debe proporcionar la estructura WSAPROTOCOL_INFO correspondiente en el parámetro lpProtocolInfo .

Sintaxis

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

Parámetros

[in] lpsaAddress

Puntero a la estructura sockaddr que se va a traducir en una cadena.

[in] dwAddressLength

Longitud, en bytes, de la dirección de la estructura sockaddr a la que apunta el parámetro lpsaAddress . El parámetro dwAddressLength puede variar en tamaño con distintos protocolos.

[in, optional] lpProtocolInfo

Puntero a la estructura WSAPROTOCOL_INFO para un proveedor determinado. Si este parámetro es NULL, la llamada se enruta al proveedor del primer protocolo que admite la familia de direcciones indicada en el parámetro lpsaAddress .

[in, out] lpszAddressString

Puntero al búfer que recibe la cadena de dirección legible.

[in, out] lpdwAddressStringLength

En la entrada, este parámetro especifica la longitud del búfer al que apunta el parámetro lpszAddressString . La longitud se representa en bytes para cadenas ANSI y en WCHAR para cadenas Unicode. En la salida, este parámetro devuelve la longitud de la cadena, incluido el terminador NULL copiado realmente en el búfer al que apunta el parámetro lpszAddressString . Si el búfer especificado no es lo suficientemente grande, la función produce un error específico de WSAEFAULT y este parámetro se actualiza con el tamaño necesario.

Valor devuelto

Si no se produce ningún error, WSAAddressToString devuelve un valor de cero. De lo contrario, se devuelve el valor SOCKET_ERROR y se puede recuperar un número de error específico llamando a WSAGetLastError.

Código de error Significado
WSAEFAULT
Los parámetros lpcsAddress, lpProtocolInfo y lpszAddressString especificados apuntan a la memoria que no está todo en el espacio de direcciones del proceso o el búfer al que apunta el parámetro lpszAddressString es demasiado pequeño. Pase un búfer más grande.
WSAEINVAL
Se pasó un parámetro no válido. Este error se devuelve si el parámetro lpsaAddress, dwAddressLength o lpdwAddressStringLength son NULL. Este error también se devuelve si la dirección especificada no es una dirección de socket válida o ningún proveedor de transporte admite la familia de direcciones indicada.
WSAENOBUFS
No hay espacio disponible en el búfer.
WSANOTINITIALISED
El archivo DLL winsock 2 no se ha inicializado. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Sockets.

Comentarios

La función WSAAddressToString proporciona una traducción de direcciones a cadenas independiente del protocolo. La función WSAAddressToString toma una estructura de direcciones de socket a la que apunta el parámetro lpsaAddress y devuelve un puntero a una cadena terminada en NULL que representa la dirección del socket en el parámetro lpszAddressString . Aunque la función inet_ntoa solo funciona con direcciones IPv4, la función WSAAddressToString funciona con cualquier dirección de socket compatible con un proveedor winsock en el equipo local, incluidas las direcciones IPv6.

Si el parámetro lpsaAddress apunta a una dirección de socket IPv4 (la familia de direcciones es AF_INET), la cadena de dirección devuelta en el búfer a la que apunta el parámetro lpszAddressString está en notación decimal con puntos como en "192.168.16.0", un ejemplo de una dirección IPv4 en notación decimal con puntos.

Si el parámetro lpsaAddress apunta a una dirección de socket IPv6 (la familia de direcciones es AF_INET6), la cadena de dirección devuelta en el búfer a la que apunta el parámetro lpszAddressString está en formato estándar de Internet. La representación de cadena básica consta de 8 números hexadecimales separados por dos puntos. Una cadena de números cero consecutivos se reemplaza por dos puntos. Solo puede haber dos puntos en la representación de cadena de la dirección IPv6.

Si la longitud del búfer a la que apunta el parámetro lpszAddressString no es lo suficientemente grande como para recibir la representación de cadena de la dirección del socket, WSAAddressToString devuelve WSAEFAULT.

Se agregó compatibilidad con direcciones IPv6 mediante la función WSAAddressToString en Windows XP con Service Pack 1 (SP1) y versiones posteriores. IPv6 también debe instalarse en el equipo local para que la función WSAAddressToString admita direcciones IPv6.

Windows Phone 8: La función WSAAddressToStringW es compatible con Windows Phone Aplicaciones de la Tienda en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: la función WSAAddressToStringW es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Nota

El encabezado winsock2.h define WSAAddressToString 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado winsock2.h
Library Ws2_32.lib
Archivo DLL Ws2_32.dll

Consulte también

InetNtop

InetPton

RtlIpv4AddressToString

RtlIpv4AddressToStringEx

RtlIpv4StringToAddress

RtlIpv4StringToAddressEx

RtlIpv6AddressToString

RtlIpv6AddressToStringEx

RtlIpv6StringToAddress

RtlIpv6StringToAddressEx

WSAPROTOCOL_INFO

WSAStartup

WSAStringToAddress

inet_addr

inet_ntoa

sockaddr