Función GetAddressByNameA (nspapi.h)

[GetAddressByName ya no está disponible para su uso a partir de Windows Sockets 2. En su lugar, use las funciones detalladas en Protocol-Independent resolución de nombres.]

El GetAddressByName función consulta un espacio de nombres o un conjunto de espacios de nombres predeterminados para recuperar la información de dirección de red de un servicio de red especificado. Este proceso se conoce como resolución de nombres de servicio. Un servicio de red también puede usar la función para obtener información de dirección local que puede usar con la función enlazar.

Sintaxis

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

Parámetros

[in] dwNameSpace

Espacio de nombres, o conjunto de espacios de nombres predeterminados, que el sistema operativo debe consultar para obtener información de dirección de red.

Use una de las siguientes constantes para especificar un espacio de nombres.

Valor	Significado
NS_DEFAULT	Un conjunto de espacios de nombres predeterminados. La función consulta cada espacio de nombres dentro de este conjunto. El conjunto de espacios de nombres predeterminados normalmente incluye todos los espacios de nombres instalados en el sistema. Sin embargo, los administradores del sistema pueden excluir espacios de nombres concretos del conjunto. Este es el valor que la mayoría de las aplicaciones deben usar para dwNameSpace.
NS_DNS	Sistema de nombres de dominio (DNS) usado en Internet para la resolución de nombres de host.
NS_NETBT	NetBIOS a través de la capa TCP/IP. Todos los sistemas operativos registran sus nombres de equipo con NetBIOS. Este espacio de nombres se usa para convertir un nombre de equipo en una dirección IP que usa este registro. Tenga en cuenta que NS_NETBT puede acceder a un servidor WINS para realizar la resolución.
NS_SAP	Protocolo de publicidad del servicio NetWare. Esto puede tener acceso a la enlazadora de NetWare si procede. NS_SAP es un espacio de nombres dinámico que permite el registro de servicios.
NS_TCPIP_HOSTS	Valor de búsqueda en el <systemroot>archivo \system32\drivers\etc\hosts.
NS_TCPIP_LOCAL	Mecanismos de resolución de nombres TCP/IP locales, incluidas las comparaciones con el nombre de host local y busca nombres de host y direcciones IP en la memoria caché del host en asignaciones de direcciones IP.

 

La mayoría de las llamadas a GetAddressByName deben usar el valor especial NS_DEFAULT. Esto permite a un cliente obtener sin conocimiento de qué espacios de nombres están disponibles en un trabajo de Internet. El administrador del sistema determina el acceso al espacio de nombres. Los espacios de nombres pueden venir y pasar sin que el cliente tenga que tener en cuenta los cambios.

[in] lpServiceType

Puntero a un identificador único global (GUID) que especifica el tipo del servicio de red. El archivo de encabezado Svcguid.h incluye definiciones de varios tipos de servicio GUID y macros para trabajar con ellos.

El archivo de encabezado Svcguid.h no se incluye automáticamente en el archivo de encabezado Winsock2.h.

[in, optional] lpServiceName

Puntero a una cadena terminada en cero que representa de forma única el nombre del servicio. Por ejemplo, "MY SNA SERVER".

Establecer lpServiceName en NULL es el equivalente a establecer dwResolution en RES_SERVICE. La función funciona en su segundo modo, obteniendo la dirección local a la que debe enlazarse un servicio del tipo especificado. La función almacena la dirección local dentro del miembro LocalAddr de las estructuras de CSADDR_INFO almacenadas en *lpCsaddrBuffer.

Si dwResolution se establece en RES_SERVICE, la función omite el parámetro lpServiceName .

Si dwNameSpace se establece en NS_DNS, *lpServiceName es el nombre del host.

[in, optional] lpiProtocols

Puntero a una matriz terminada en cero de identificadores de protocolo. La función restringe un intento de resolución de nombres a proveedores de espacios de nombres que ofrecen estos protocolos. Esto permite al autor de la llamada limitar el ámbito de la búsqueda.

Si lpiProtocols se establece en null, la función recupera información sobre todos los protocolos disponibles.

[in] dwResolution

Conjunto de marcas de bits que especifican aspectos del proceso de resolución de nombres de servicio. Se definen las marcas de bits siguientes.

Valor	Significado
RES_SERVICE	Si se establece, la función recupera la dirección a la que debe enlazarse un servicio del tipo especificado. Esto equivale a establecer el parámetro lpServiceName en NULL. Si esta marca está desactivada, se produce una resolución de nombres normal.
RES_FIND_MULTIPLE	Si se establece esta marca, el sistema operativo realiza una búsqueda extensa de todos los espacios de nombres para el servicio. Pide a cada espacio de nombres adecuado que resuelva el nombre del servicio. Si esta marca está clara, el sistema operativo deja de buscar direcciones de servicio en cuanto se encuentra una.
RES_SOFT_SEARCH	Esta marca es válida si el espacio de nombres admite varios niveles de búsqueda. Si esta marca es válida y se establece, el sistema operativo realiza una búsqueda sencilla y rápida del espacio de nombres. Esto resulta útil si una aplicación solo necesita obtener direcciones fáciles de encontrar para el servicio. Si esta marca es válida y desactivada, el sistema operativo realiza una búsqueda más extensa del espacio de nombres.

[in, optional] lpServiceAsyncInfo

Reservado para uso futuro; debe establecerse en null.

[out] lpCsaddrBuffer

Puntero a un búfer para recibir una o varias estructuras de datos CSADDR_INFO. El número de estructuras escritas en el búfer depende de la cantidad de información encontrada en el intento de resolución. Debe suponer que se escribirán varias estructuras, aunque en muchos casos solo habrá una.

[in, out] lpdwBufferLength

Puntero a una variable que, tras la entrada, especifica el tamaño, en bytes, del búfer al que apunta lpCsaddrBuffer.

Tras la salida, esta variable contiene el número total de bytes necesarios para almacenar la matriz de estructuras de CSADDR_INFO. Si este valor es menor o igual que el valor de entrada de *lpdwBufferLengthy la función es correcta, este es el número de bytes almacenados realmente en el búfer. Si este valor es mayor que el valor de entrada de *lpdwBufferLength, el búfer era demasiado pequeño y el valor de salida de *lpdwBufferLength es el tamaño mínimo necesario del búfer.

[in, out] lpAliasBuffer

Puntero a un búfer para recibir información de alias para el servicio de red.

Si un espacio de nombres admite alias, la función almacena una matriz de cadenas de nombre terminadas en cero en el búfer al que apunta lpAliasBuffer. Hay un terminador cero doble al final de la lista. El nombre de la matriz es el nombre principal del servicio. Los nombres siguientes son alias. Un ejemplo de un espacio de nombres que admite alias es DNS.

Si un espacio de nombres no admite alias, almacena un terminador cero doble en el búfer.

Este parámetro es opcional y se puede establecer en NULL.

[in, out] lpdwAliasBufferLength

Puntero a una variable que, tras la entrada, especifica el tamaño, en elementos (caracteres), del búfer al que apunta lpAliasBuffer.

Tras la salida, esta variable contiene el número total de elementos (caracteres) necesarios para almacenar la matriz de cadenas de nombre. Si este valor es menor o igual que el valor de entrada de *lpdwAliasBufferLengthy la función es correcta, este es el número de elementos almacenados en el búfer. Si este valor es mayor que el valor de entrada de *lpdwAliasBufferLength, el búfer era demasiado pequeño y el valor de salida de *lpdwAliasBufferLength es el tamaño mínimo necesario del búfer.

Si lpAliasBuffer es NULL, lpdwAliasBufferLength no tiene sentido y también puede ser null.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el número de CSADDR_INFO estructuras de datos escritas en el búfer a las que apunta lpCsaddrBuffer.

Si se produce un error en la función, el valor devuelto es SOCKET_ERROR( –1). Para obtener información de error extendida, llame a GetLastError, que devuelve el siguiente valor de error extendido.

Código de error	Significado
ERROR_INSUFFICIENT_BUFFER	El búfer al que apunta lpCsaddrBuffer era demasiado pequeño para recibir todas las estructuras de CSADDR_INFO pertinentes. Llame a la función con un búfer al menos tan grande como el valor devuelto en *lpdwBufferLength.

Observaciones

Esta función es una versión más eficaz de la función gethostbyname. La función GetAddressByName funciona con varios servicios de nombre.

Nota La función gethostbyname ha quedado en desuso mediante la introducción de la función getaddrinfo. Se insta a los desarrolladores que crean aplicaciones de Windows Sockets 2 a usar la función getaddrinfo en lugar de gethostbyname.

 

La función GetAddressByName permite a un cliente obtener una dirección de Windows Sockets para un servicio de red. El cliente especifica el servicio de interés por su tipo de servicio y nombre de servicio.

Muchos servicios de nombres admiten un prefijo o sufijo predeterminado que el proveedor de servicios de nombres considera al resolver nombres de servicio. Por ejemplo, en el espacio de nombres DNS, si un dominio se denomina "nt.microsoft.com" y "ftp millikan" se proporciona como entrada, el software DNS no puede resolver "milikan", pero resuelve correctamente "millikan.nt.microsoft.com".

Tenga en cuenta que la función GetAddressByName puede buscar una dirección de servicio de dos maneras: dentro de un espacio de nombres determinado o dentro de un conjunto de espacios de nombres predeterminados. Con un espacio de nombres predeterminado, un administrador puede especificar que determinados espacios de nombres se buscarán solo si se especifican por nombre. Un administrador o un espacio de nombres: el programa de instalación también puede controlar el orden de las búsquedas de espacios de nombres.

Nota

El encabezado nspapi.h define GetAddressByName 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 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	nspapi.h
biblioteca de	Mswsock.lib
DLL de	Mswsock.dll

Consulte también

CSADDR_INFO

funciones winsock

de referencia de Winsock

getaddrinfo

gethostbyname