WSASetServiceA, fonction (winsock2.h)

Article
03/13/2024

La fonction WSASetService inscrit ou supprime du Registre un service instance dans un ou plusieurs espaces de noms.

Syntaxe

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Paramètres

[in] lpqsRegInfo

Pointeur vers les informations de service pour l’inscription ou la désinscription.

[in] essoperation

Valeur qui détermine l’opération demandée. Ce paramètre peut être l’une des valeurs du type d’énumération WSAESETSERVICEOP défini dans le fichier d’en-tête Winsock2.h .

Valeur	Signification
RNRSERVICE_REGISTER	Inscrivez le service. Pour SAP, cela signifie l’envoi d’une diffusion périodique. Il s’agit d’un NOP pour l’espace de noms DNS. Pour les magasins de données persistants, cela signifie la mise à jour des informations d’adresse.
RNRSERVICE_DEREGISTER	Supprimez le service du Registre. Pour SAP, cela signifie arrêter l’envoi de la diffusion périodique. Il s’agit d’un NOP pour l’espace de noms DNS. Pour les magasins de données persistants, cela signifie la suppression des informations d’adresse.
RNRSERVICE_DELETE	Supprimez le service du nom dynamique et des espaces persistants. Pour les services représentés par plusieurs structures de CSADDR_INFO (à l’aide de l’indicateur de SERVICE_MULTIPLE), seule l’adresse spécifiée est supprimée, qui doit correspondre exactement à la structure de CSADDR_INFO correspondante qui a été spécifiée lors de l’inscription du service.

[in] dwControlFlags

Valeur des indicateurs d’installation de service qui contrôle davantage l’opération effectuée de la fonction WSASetService . Les valeurs possibles pour ce paramètre sont définies dans le fichier d’en-tête Winsock2.h .

Indicateur	Signification
SERVICE_MULTIPLE	Contrôle l’étendue de l’opération. Lorsque cet indicateur n’est pas défini, les adresses de service sont gérées en tant que groupe. Un enregistrement ou une suppression du registre invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné. Lorsqu’elle est définie, l’action est effectuée uniquement sur le jeu d’adresses donné. Un registre n’invalide pas les adresses existantes et une suppression du Registre invalide uniquement l’ensemble d’adresses donné.

Indicateur

Signification

SERVICE_MULTIPLE

Contrôle l’étendue de l’opération. Lorsque cet indicateur n’est pas défini, les adresses de service sont gérées en tant que groupe. Un enregistrement ou une suppression du registre invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné. Lorsqu’elle est définie, l’action est effectuée uniquement sur le jeu d’adresses donné. Un registre n’invalide pas les adresses existantes et une suppression du Registre invalide uniquement l’ensemble d’adresses donné.

Valeur retournée

La valeur de retour de WSASetService est égale à zéro si l’opération a réussi. Sinon, la valeur SOCKET_ERROR est retournée et un numéro d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSAEACCES	La routine appelante ne dispose pas des privilèges suffisants pour installer le service.
WSAEINVAL	Un ou plusieurs paramètres requis n’étaient pas valides ou manquants.
WSANOTINITIALISED	Le Ws2_32.dlln’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler les fonctions Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	La mémoire était insuffisante pour effectuer l’opération.

Remarques

La fonction WSASetService peut être utilisée pour affecter un fournisseur d’espaces de noms spécifique, tous les fournisseurs associés à un espace de noms spécifique ou tous les fournisseurs sur tous les espaces de noms.

Les valeurs disponibles pour essOperation et dwControlFlags se combinent pour contrôler le fonctionnement de la fonction WSASetService , comme indiqué dans le tableau suivant.

Opération	Indicateurs	Le service existe déjà	Le service n’existe pas
RNRSERVICE_REGISTER	None	Remplace l’objet . Utilise uniquement les adresses spécifiées. L’objet est REGISTERED.	Crée un objet. Utilise uniquement les adresses spécifiées. L’objet est REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Met à jour l'objet. Ajoute de nouvelles adresses à l’ensemble existant. L’objet est REGISTERED.	Crée un objet. Utilise toutes les adresses spécifiées. L’objet est REGISTERED.
RNRSERVICE_DEREGISTER	None	Supprime toutes les adresses, mais ne supprime pas l’objet de l’espace de noms. L’objet est supprimé du Registre.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Met à jour l'objet. Supprime uniquement les adresses spécifiées. Marque l’objet comme DEREGISTERED uniquement si aucune adresse n’est présente. Ne supprime pas l’objet de l’espace de noms.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	None	Supprime l’objet de l’espace de noms.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Supprime uniquement les adresses spécifiées. Supprime uniquement l’objet de l’espace de noms si aucune adresse n’est conservée.	WSASERVICE_NOT_FOUND

La publication de services dans des répertoires, tels que les services Active Directory, est limitée en fonction des listes de contrôle d’accès (ACL). Pour plus d’informations, consultez Problèmes de sécurité pour la publication du service.

Lorsque le paramètre dwControlFlags est défini sur SERVICE_MULTIPLE, une application peut gérer ses adresses indépendamment. Cela est utile lorsque l’application souhaite gérer ses protocoles individuellement ou lorsque le service réside sur plusieurs ordinateurs. Par instance, lorsqu’un service utilise plusieurs protocoles, il peut constater qu’un socket d’écoute abandonne, mais que les autres sockets restent opérationnels. Dans ce cas, le service peut supprimer l’adresse abandonnée du Registre sans affecter les autres adresses.

Lorsque le paramètre dwControlFlags a la valeur SERVICE_MULTIPLE, une application ne doit pas laisser les adresses obsolètes rester dans l’objet. Cela peut se produire si l’application abandonne sans émettre de requête DEREGISTER. Lorsqu’un service s’inscrit, il doit stocker ses adresses. Lors de son appel suivant, le service doit supprimer explicitement ces anciennes adresses obsolètes du Registre avant d’inscrire de nouvelles adresses.

Note Si des chaînes de caractères ANSI sont utilisées, il est possible que les données WSAQUERYSET dans lpqsRegInfo ne contiennent aucun résultat après le retour de cette fonction. Cela est dû au fait que la version ANSI de cette méthode, WSASetServiceA, convertit les données ANSI dans WSAQUERYSET en Unicode en interne, mais ne convertit pas les résultats en ANSI. Cela affecte principalement les transports qui retournent un « handle d’enregistrement de service » utilisé pour identifier un enregistrement de manière unique. Pour contourner ce problème, les applications doivent utiliser des données de chaîne Unicode dans WSAQUERYSET lors de l’appel de cette fonction.

Propriétés du service

Le tableau suivant décrit comment les données de propriété de service sont représentées dans une structure WSAQUERYSET . Les champs étiquetés comme (Facultatif) peuvent contenir un pointeur null.

Membre WSAQUERYSET	Description de la propriété de service
dwSize	Doit être défini sur sizeof (WSAQUERYSET). Il s’agit d’un mécanisme de contrôle de version.
dwOutputFlags	Non applicable et ignoré.
lpszServiceInstanceName	La chaîne référencée contient le nom du service instance.
lpServiceClassId	GUID correspondant à cette classe de service.
lpVersion	(Facultatif) Fournit le service instance numéro de version.
lpszComment	(Facultatif) Chaîne de commentaire facultative.
dwNameSpace	Consultez le tableau ci-dessous.
lpNSProviderId	Consultez le tableau ci-dessous.
lpszContext	(Facultatif) Spécifie le point de départ de la requête dans un espace de noms hiérarchique.
dwNumberOfProtocols	Ignoré.
lpafpProtocols	Ignoré.
lpszQueryString	Ignoré.
dwNumberOfCsAddrs	Nombre d’éléments dans le tableau de structures CSADDR_INFO référencées par lpcsaBuffer.
lpcsaBuffer	Pointeur vers un tableau de structures CSADDR_INFO qui contiennent la ou les adresses que le service écoute.
lpBlob	(Facultatif) Il s’agit d’un pointeur vers une entité spécifique au fournisseur.

Comme illustré dans ce qui suit, la combinaison des membres dwNameSpace et lpNSProviderId détermine que les fournisseurs d’espaces de noms sont affectés par cette fonction.

dwNameSpace	lpNSProviderId	Étendue de l’impact
Ignoré	Non null	Fournisseur d’espace de nom spécifié.
Un nom-identificateur d’espace valide	Null	Tous les fournisseurs d’espace de noms qui prennent en charge l’espace de noms indiqué.
NS_ALL	Null	Tous les fournisseurs d’espace de nom.

Windows Phone 8 : la fonction WSASetServiceW est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : la fonction WSASetServiceW est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Notes

L’en-tête winsock2.h définit WSASetService 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 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll