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
L’espace de noms, ou un 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 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] 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
[in] lpServiceName
Pointeur vers une chaîne sans fin qui représente de manière unique le nom du service. Par exemple, « MY SNA SERVER ».
[in] dwProperties
Ensemble d’indicateurs de bits qui spécifient les informations de service récupérées par la fonction. 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 des 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 en fonction des 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 contenues SERVICE_INFO 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 une utilisation ultérieure. Doit être défini sur NULL.
Valeur de retour
Si la fonction réussit, la valeur de retour correspond au 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é n’a pas été trouvé 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
Note
L’en-tête nspapi.h définit GetService 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 |