Partager via

GetAddressByNameA, fonction (nspapi.h)

  • Article

[GetAddressByName n’est plus disponible pour une utilisation à partir de Windows Sockets 2. Utilisez plutôt les fonctions détaillées dans Protocol-Independent résolution de noms.]

La fonction GetAddressByName interroge un espace de noms, ou un ensemble d’espaces de noms par défaut, pour récupérer les informations d’adresse réseau d’un service réseau spécifié. Ce processus est appelé résolution de noms de service. Un service réseau peut également utiliser la fonction pour obtenir des informations d’adresse locale qu’elle peut utiliser avec la lier fonction.

Syntaxe

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
);

Paramètres

[in] dwNameSpace

Espace de noms ou ensemble d’espaces de noms par défaut que le système d’exploitation doit interroger pour obtenir des informations d’adresse réseau.

Utilisez l’une des constantes suivantes pour spécifier un espace de noms.

Valeur Signification
NS_DEFAULT
 Ensemble d’espaces de noms par défaut. La fonction interroge chaque espace de noms dans cet ensemble. L’ensemble d’espaces de noms par défaut inclut généralement tous les espaces de noms installés sur le système. Toutefois, les administrateurs système peuvent exclure des espaces de noms particuliers de l’ensemble. Il s’agit de la valeur que la plupart des applications doivent utiliser pour dwNameSpace.
NS_DNS
 Dns (Domain Name System) utilisé dans Internet pour la résolution de noms d’hôte.
NS_NETBT
 NetBIOS sur la couche TCP/IP. Tous les systèmes d’exploitation inscrivent leurs noms d’ordinateurs auprès de NetBIOS. Cet espace de noms est utilisé pour convertir un nom d’ordinateur en adresse IP qui utilise cette inscription. Notez que NS_NETBT pouvez accéder à un serveur WINS pour effectuer la résolution.
NS_SAP
 Protocole de publicité du service NetWare. Cela peut accéder au classeur NetWare le cas échéant. NS_SAP est un espace de noms dynamique qui autorise l’inscription des services.
NS_TCPIP_HOSTS
 Valeur de recherche dans le fichier <systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL
 Mécanismes de résolution de noms TCP/IP locaux, y compris les comparaisons par rapport au nom d’hôte local et recherche les noms d’hôte et les adresses IP dans le cache des mappages d’adresses IP de l’hôte.
 

La plupart des appels à GetAddressByName doivent utiliser la valeur spéciale NS_DEFAULT. Cela permet à un client d’obtenir sans connaître les espaces de noms disponibles sur Internetwork. L’administrateur système détermine l’accès à l’espace de noms. Les espaces de noms peuvent venir et aller sans que le client n’ait à connaître les modifications.

[in] lpServiceType

Pointeur vers un identificateur global unique (GUID) qui spécifie le type du service réseau. Le fichier d’en-tête Svcguid.h inclut des définitions de plusieurs types de services GUID et des macros pour les utiliser.

Le fichier d’en-tête Svcguid.h n’est pas automatiquement inclus par le fichier d’en-tête Winsock2.h.

[in, optional] lpServiceName

Pointeur vers une chaîne sans fin qui représente de manière unique le nom du service. Par exemple, « MY SNA SERVER ».

La définition lpServiceName sur NULL équivaut à définir dwResolution sur RES_SERVICE. La fonction fonctionne en son deuxième mode, obtenant l’adresse locale à laquelle un service du type spécifié doit être lié. La fonction stocke l’adresse locale dans le membre LocalAddr des structures CSADDR_INFO stockées dans *lpCsaddrBuffer.

Si dwResolution est défini sur RES_SERVICE, la fonction ignore le paramètre lpServiceName.

Si dwNameSpace est défini sur NS_DNS, *lpServiceName est le nom de l’hôte.

[in, optional] lpiProtocols

Pointeur vers un tableau d’identificateurs de protocole sans fin zéro. La fonction limite une tentative de résolution de noms aux fournisseurs d’espaces de noms qui offrent ces protocoles. Cela permet à l’appelant de limiter l’étendue de la recherche.

Si lpiProtocols est défini sur NULL, la fonction récupère des informations sur tous les protocoles disponibles.

[in] dwResolution

Ensemble d’indicateurs de bits qui spécifient les aspects du processus de résolution de noms de service. Les indicateurs de bits suivants sont définis.

Valeur Signification
RES_SERVICE
 Si elle est définie, la fonction récupère l’adresse à laquelle un service du type spécifié doit être lié. Il s’agit de l’équivalent de la définition du paramètre lpServiceName sur NULL.

Si cet indicateur est clair, la résolution de noms normale se produit.
RES_FIND_MULTIPLE
 Si cet indicateur est défini, le système d’exploitation effectue une recherche complète de tous les espaces de noms pour le service. Il demande à chaque espace de noms approprié de résoudre le nom du service. Si cet indicateur est clair, le système d’exploitation cesse de rechercher des adresses de service dès qu’un indicateur est trouvé.
RES_SOFT_SEARCH
 Cet indicateur est valide si l’espace de noms prend en charge plusieurs niveaux de recherche.

Si cet indicateur est valide et défini, le système d’exploitation effectue une recherche simple et rapide de l’espace de noms. Cela est utile si une application doit uniquement obtenir des adresses faciles à trouver pour le service.

Si cet indicateur est valide et clair, le système d’exploitation effectue une recherche plus approfondie de l’espace de noms.

[in, optional] lpServiceAsyncInfo

Réservé à une utilisation ultérieure ; doit être défini sur NULL .

[out] lpCsaddrBuffer

Pointeur vers une mémoire tampon pour recevoir une ou plusieurs structures de données CSADDR_INFO. Le nombre de structures écrites dans la mémoire tampon dépend de la quantité d’informations trouvées dans la tentative de résolution. Vous devez supposer que plusieurs structures seront écrites, bien que dans de nombreux cas il n’y en aura qu’une.

[in, out] lpdwBufferLength

Pointeur vers une variable qui, lors de l’entrée, spécifie la taille, en octets, de la mémoire tampon pointée par lpCsaddrBuffer.

Lors de la sortie, cette variable contient le nombre total d’octets requis pour stocker le tableau de structures CSADDR_INFO. Si cette valeur est inférieure ou égale à la valeur d’entrée de *lpdwBufferLength, et que la fonction réussit, il s’agit du nombre d’octets réellement stockés dans la mémoire tampon. Si cette valeur est supérieure à la valeur d’entrée de *lpdwBufferLength, la mémoire tampon était trop petite et la valeur de sortie de *lpdwBufferLength est la taille minimale requise de la mémoire tampon.

[in, out] lpAliasBuffer

Pointeur vers une mémoire tampon pour recevoir des informations d’alias pour le service réseau.

Si un espace de noms prend en charge les alias, la fonction stocke un tableau de chaînes de noms sans fin dans la mémoire tampon pointée par lpAliasBuffer. Il existe un double terminateur zéro à la fin de la liste. Le prénom du tableau est le nom principal du service. Les noms suivants sont des alias. Un exemple d’espace de noms qui prend en charge les alias est DNS.

Si un espace de noms ne prend pas en charge les alias, il stocke un double terminateur zéro dans la mémoire tampon.

Ce paramètre est facultatif et peut être défini sur NULL.

[in, out] lpdwAliasBufferLength

Pointeur vers une variable qui, lors de l’entrée, spécifie la taille, dans les éléments (caractères), de la mémoire tampon pointée par lpAliasBuffer.

Lors de la sortie, cette variable contient le nombre total d’éléments (caractères) requis pour stocker le tableau de chaînes de noms. Si cette valeur est inférieure ou égale à la valeur d’entrée de *lpdwAliasBufferLength, et que la fonction réussit, il s’agit du nombre d’éléments réellement stockés dans la mémoire tampon. Si cette valeur est supérieure à la valeur d’entrée de *lpdwAliasBufferLength, la mémoire tampon était trop petite et la valeur de sortie de *lpdwAliasBufferLength est la taille de mémoire tampon minimale requise.

Si lpAliasBuffer est NULL, lpdwAliasBufferLength est sans signification et peut également être NULL.

Valeur de retour

Si la fonction réussit, la valeur de retour est le nombre de structures de données CSADDR_INFO écrites dans la mémoire tampon pointée par lpCsaddrBuffer.

Si la fonction échoue, la valeur de retour est SOCKET_ERROR( –1). Pour obtenir des informations d’erreur étendues, appelez GetLastError, qui retourne la valeur d’erreur étendue suivante.

Code d’erreur Signification
ERROR_INSUFFICIENT_BUFFER
 La mémoire tampon pointée par lpCsaddrBuffer était trop petite pour recevoir toutes les structures CSADDR_INFO pertinentes. Appelez la fonction avec une mémoire tampon au moins aussi grande que la valeur retournée dans *lpdwBufferLength.

Remarques

Cette fonction est une version plus puissante de la fonction gethostbyname. La fonction GetAddressByName fonctionne avec plusieurs services de noms.

Remarque la fonction gethostbyname a été déconseillée par l’introduction de la fonction getaddrinfo getaddrinfo. Les développeurs créant des applications Windows Sockets 2 sont invités à utiliser la fonction getaddrinfo au lieu de gethostbyname.
 

La fonction GetAddressByName permet à un client d’obtenir une adresse Windows Sockets pour un service réseau. Le client spécifie le service d’intérêt par son type de service et son nom de service.

De nombreux services de noms prennent en charge un préfixe ou un suffixe par défaut que le fournisseur de services de noms prend en compte lors de la résolution des noms de service. Par exemple, dans l’espace de noms DNS, si un domaine est nommé « nt.microsoft.com » et « ftp millikan » est fourni comme entrée, le logiciel DNS ne parvient pas à résoudre « millikan », mais résout correctement « millikan.nt.microsoft.com ».

Notez que la fonction GetAddressByName peut rechercher une adresse de service de deux manières : dans un espace de noms particulier ou dans un ensemble d’espaces de noms par défaut. À l’aide d’un espace de noms par défaut, un administrateur peut spécifier que certains espaces de noms seront recherchés pour les adresses de service uniquement s’ils sont spécifiés par nom. Un administrateur ou un espace de noms : le programme d’installation peut également contrôler l’ordre des recherches d’espaces de noms.

Note

L’en-tête nspapi.h définit GetAddressByName comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence Valeur
client minimum pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge Windows 2000 Server [applications de bureau uniquement]
plateforme cible Windows
d’en-tête nspapi.h
bibliothèque Mswsock.lib
DLL Mswsock.dll

Voir aussi

CSADDR_INFO

fonctions Winsock

de référence Winsock

getaddrinfo

gethostbyname