GetServiceA, fonction (nspapi.h)

Article
03/04/2024

La fonction GetService récupère des informations sur un service réseau dans le contexte d’un ensemble d’espaces de noms par défaut ou d’un espace de noms spécifié. Le service réseau est spécifié par son type et son nom. Les informations sur le service sont obtenues sous la forme d’un ensemble de structures de données NS_SERVICE_INFO .

Note La fonction GetService est une extension propre à Microsoft à la spécification Windows Sockets 1.1. Cette fonction est obsolète. Pour la commodité des développeurs Windows Sockets 1.1, ce document de référence est inclus.

Note Les fonctions détaillées dans Résolution de noms indépendantes du protocole fournissent des fonctionnalités équivalentes dans Windows Sockets 2.

Syntaxe

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

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 sur le service réseau spécifié.

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. Le système d’exploitation interroge chaque espace de noms au sein de cet ensemble. 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. NS_DEFAULT est la valeur que la plupart des applications doivent utiliser pour dwNameSpace.
NS_DNS	Système de noms de domaine 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 résoudre un nom d’ordinateur en adresse IP à l’aide de 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	Recherche les noms d’hôte et les adresses IP 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 à GetService doivent utiliser la valeur spéciale NS_DEFAULT. Cela permet à un client de s’en sortir 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 aller et venir sans que le client ait à connaître les modifications.

[in] lpGuid

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 types de service GUID provenant de nombreux services connus au sein des espaces de noms DNS et SAP.

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

[in] 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 ».

[in] dwProperties

Ensemble d’indicateurs de bits qui spécifient les informations de service que la fonction récupère. Chacune de ces constantes d’indicateur de bits, autres que PROP_ALL, correspond à un membre particulier de la structure de données SERVICE_INFO . Si l’indicateur est défini, la fonction place des informations dans le membre correspondant des structures de données stockées dans *lpBuffer. Les indicateurs de bits suivants sont définis.

Valeur	Signification
PROP_COMMENT	Si cet indicateur est défini, la fonction stocke les données dans le membre lpComment des structures de données stockées dans *lpBuffer.
PROP_LOCALE	Si cet indicateur est défini, la fonction stocke les données dans le membre lpLocale des structures de données stockées dans *lpBuffer.
PROP_DISPLAY_HINT	Si cet indicateur est défini, la fonction stocke les données dans le membre dwDisplayHint des structures de données stockées dans *lpBuffer.
PROP_VERSION	Si cet indicateur est défini, la fonction stocke les données dans le membre dwVersion des structures de données stockées dans *lpBuffer.
PROP_START_TIME	Si cet indicateur est défini, la fonction stocke les données dans le membre dwTime des structures de données stockées dans *lpBuffer.
PROP_MACHINE	Si cet indicateur est défini, la fonction stocke les données dans le membre lpMachineName des structures de données stockées dans *lpBuffer.
PROP_ADDRESSES	Si cet indicateur est défini, la fonction stocke les données dans le membre lpServiceAddress des structures de données stockées dans *lpBuffer.
PROP_SD	Si cet indicateur est défini, la fonction stocke les données dans le membre ServiceSpecificInfo des structures de données stockées dans *lpBuffer.
PROP_ALL	Si cet indicateur est défini, la fonction stocke les données dans tous les membres des structures de données stockées dans *lpBuffer.

[out] lpBuffer

Pointeur vers une mémoire tampon pour recevoir un tableau de structures NS_SERVICE_INFO et les informations de service associées. Chaque structure NS_SERVICE_INFO contient des informations de service dans le contexte d’un espace de noms particulier. Notez que si dwNameSpace est NS_DEFAULT, la fonction stocke plusieurs structures dans la mémoire tampon ; sinon, une seule structure est stockée.

Chaque structure NS_SERVICE_INFO contient une structure SERVICE_INFO . Les membres de ces structures SERVICE_INFO contiennent des données valides basées sur les indicateurs de bits définis dans le paramètre dwProperties . Si l’indicateur de bits correspondant d’un membre n’est pas défini dans dwProperties, la valeur du membre n’est pas définie.

La fonction stocke les structures NS_SERVICE_INFO dans un tableau consécutif, en commençant au début de la mémoire tampon. Les pointeurs dans les structures de SERVICE_INFO contenues pointent vers des informations stockées dans la mémoire tampon entre la fin des structures NS_SERVICE_INFO et la fin de la mémoire tampon.

[in, out] lpdwBufferSize

Pointeur vers une variable qui, en entrée, contient la taille, en octets, de la mémoire tampon pointée par lpBuffer. En sortie, cette variable contient le nombre d’octets requis pour stocker les informations demandées. Si cette valeur de sortie est supérieure à la valeur d’entrée, la fonction a échoué en raison d’une taille de mémoire tampon insuffisante.

[in, optional] lpServiceAsyncInfo

Réservé pour un usage futur. Doit être défini sur NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est le nombre de structures NS_SERVICE_INFO stockées dans *lpBuffer. Zéro indique qu’aucune structure n’a été stockée.

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

Code d'erreur	Signification
ERROR_INSUFFICIENT_BUFFER	La mémoire tampon pointée par lpBuffer est trop petite pour recevoir toutes les informations demandées. Appelez la fonction avec une mémoire tampon au moins aussi grande que la valeur retournée dans *lpdwBufferSize.
ERROR_SERVICE_NOT_FOUND	Le service spécifié est introuvable ou l’espace de noms spécifié n’est pas utilisé. La valeur de retour de la fonction est zéro dans ce cas.

Remarques

Notes

L’en-tête nspapi.h définit GetService en tant qu’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. La combinaison 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