Función WSAAddressToStringA (winsock2.h)

Artículo
11/20/2024

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

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 al estructura sockaddr que se va a traducir en una cadena.

[in] dwAddressLength

Longitud, en bytes, de la dirección del sockaddr estructura 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 de 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, incluida la terminador NULL copiada 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	El lpcsAddress, lpProtocolInfoy lpszAddressString parámetros apuntan a la memoria que no está 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 mayor.
WSAEINVAL	Se pasó un parámetro no válido. Este error se devuelve si el lpsaAddress, dwAddressLength, o parámetro 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 de búfer disponible.
WSANOTINITIALISED	El archivo DLL de Winsock 2 no se ha inicializado. La aplicación debe llamar primero a WSAStartup antes de llamar a cualquier función de Windows Sockets.

Observaciones

La función WSAAddressToString proporciona una traducción de dirección a cadena 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 cadena terminadaNULL que representa la dirección del socket en el parámetro lpszAddressStr ing. Aunque la función inet_ntoa solo funciona con direcciones IPv4, la función de WSAAddressToString funciona con cualquier dirección de socket compatible con un proveedor de 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 al que apunta el lpszAddressString parámetro 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 al 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. Se reemplaza una cadena de cero números consecutivos por dos puntos. Solo puede haber un signo de 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 la función WSAAddressToString para admitir direcciones IPv6.

Windows Phone 8: la función WSAAddressToStringW es compatible con las aplicaciones de la Tienda de Windows Phone 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 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 XP, Windows 8.1 [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	winsock2.h
biblioteca de	Ws2_32.lib
DLL de	Ws2_32.dll