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 Résolution de noms indépendantes du protocole.]

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’il peut utiliser avec la fonction de liaison .

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 de ce jeu. L’ensemble des 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é sur Internet pour la résolution de noms d’hôte.
NS_NETBT
 Couche NetBIOS sur 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
 Le protocole NetWare Service Advertising Protocol. Cela peut accéder à la bindery NetWare, le cas échéant. NS_SAP est un espace de noms dynamique qui permet l’inscription de 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, notamment des comparaisons avec le 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 à l’adresse IP.
 

La plupart des appels à GetAddressByName doivent utiliser la valeur spéciale NS_DEFAULT. Cela permet à un client de s’en sortir sans savoir quels espaces de noms sont disponibles sur internetwork. L’administrateur système détermine l’accès à l’espace de noms. Les espaces de noms peuvent aller et venir sans que le client 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 à terminaison zéro qui représente de façon unique le nom du service. Par exemple, « MY SNA SERVER ».

Définir lpServiceName sur NULL revient à définir dwResolution sur RES_SERVICE. La fonction fonctionne dans son deuxième mode, en 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 a la valeur NS_DNS, *lpServiceName est le nom de l’hôte.

[in, optional] lpiProtocols

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

Si lpiProtocols a la valeur NULL, la fonction récupère des informations sur tous les protocoles disponibles.

[in] dwResolution

Ensemble d’indicateurs de bits qui spécifient des 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é. Cela équivaut à définir le 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 approfondie 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’une adresse est trouvée.
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 dans 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é pour une utilisation ultérieure ; doit avoir la valeur 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 ait qu’une seule.

[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 de mémoire tampon minimale requise.

[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 qui suivent sont des alias. DNS est un exemple d’espace de noms qui prend en charge les alias.

Si un espace de noms ne prend pas en charge les alias, il stocke une double marque de fin 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, en é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 a la valeur NULL, lpdwAliasBufferLength n’a aucun sens et peut également être NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour correspond au 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.

Note La fonction gethostbyname a été dépréciée par l’introduction de la fonction getaddrinfo . Les développeurs qui créent 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 de sockets Windows 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 que « ftp millikan » est fourni en tant qu’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 si elles sont spécifiées 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.

Notes

L’en-tête nspapi.h définit GetAddressByName comme un 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.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête nspapi.h
Bibliothèque Mswsock.lib
DLL Mswsock.dll

Voir aussi

CSADDR_INFO

Fonctions Winsock

Informations de référence sur Winsock

getaddrinfo

gethostbyname