Compartir a través de

Función GetAddressByNameA (nspapi.h)

  • Artículo

[GetAddressByName ya no está disponible para su uso a partir de Windows Sockets 2. En su lugar, use las funciones detalladas en Resolución de nombres independiente del protocolo.]

La función GetAddressByName consulta un espacio de nombres, o un conjunto de espacios de nombres predeterminados, para recuperar la información de direcciones 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 bind .

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 direcciones 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 determinados espacios de nombres 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
 El protocolo de publicidad del servicio NetWare. Esto puede acceder 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 <archivo systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL
 Mecanismos de resolución de nombres TCP/IP locales, incluidas 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 aparecer 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 Winsock2.h no incluye automáticamente el archivo de encabezado Svcguid.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 equivale 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 se debe enlazar 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 amplia 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 *lpdwBufferLength y 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 de 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 *lpdwAliasBufferLength y la función es correcta, este es el número de elementos almacenados realmente 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 CSADDR_INFO pertinentes. Llame a la función con un búfer al menos tan grande como el valor devuelto en *lpdwBufferLength.

Comentarios

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 el nombre del servicio.

Muchos servicios de nombres admiten un prefijo o sufijo predeterminados que el proveedor de servicios de nombres tiene en cuenta 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 "millikan", 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 en direcciones de servicio si se especifica por nombre. Un administrador o 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 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 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado nspapi.h
Library Mswsock.lib
Archivo DLL Mswsock.dll

Consulte también

CSADDR_INFO

Funciones winsock

Referencia de Winsock

getaddrinfo

gethostbyname