GetServiceA, fonction (nspapi.h)
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 .
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.
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.
[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 |
|---|---|
|
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. |
|
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 |