WSASetServiceW, fonction (winsock2.h)

Article
11/20/2024

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

Syntaxe

INT WSAAPI WSASetServiceW(
  [in] LPWSAQUERYSETW   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 cette 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 envoyer 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 mettre à jour les informations d’adresse.
RNRSERVICE_DEREGISTER	Supprimez le service du Registre. Pour SAP, cela signifie qu’il est impossible d’envoyer 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 CSADDR_INFO (à l’aide de l’indicateur SERVICE_MULTIPLE), seule l’adresse spécifiée est supprimée, et cela doit correspondre exactement à la structure de CSADDR_INFO correspondante spécifiée lors de l’inscription du service.

[in] dwControlFlags

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

Drapeau	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 registre ou une suppression du Registre invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné. Quand 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é.

Drapeau

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 registre ou une suppression du Registre invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné. Quand 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 de retour

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 n’a pas suffisamment de privilèges pour installer le service.
WSAEINVAL	Un ou plusieurs paramètres requis n’étaient pas valides ou manquants.
WSANOTINITIALISED	Le Ws2_32.dll n’a pas été initialisé. L’application doit d’abord appeler WSAStartup avant d’appeler des 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 de tous les espaces de noms.

Les valeurs disponibles pour essOperation et dwControlFlags combiner pour contrôler l’opération de la fonction WSASetService comme indiqué dans le tableau suivant.

Opération	Drapeaux	Le service existe déjà	Le service n’existe pas
RNRSERVICE_REGISTER	Aucun	Remplace l’objet. Utilise uniquement les adresses spécifiées. L’objet est INSCRIT.	Crée un objet. Utilise uniquement les adresses spécifiées. L’objet est INSCRIT.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Met à jour l’objet. Ajoute de nouvelles adresses au jeu existant. L’objet est INSCRIT.	Crée un objet. Utilise toutes les adresses spécifiées. L’objet est INSCRIT.
RNRSERVICE_DEREGISTER	Aucun	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 uniquement l’objet comme DEREGISTERED si aucune adresse n’est présente. Ne supprime pas l’objet de l’espace de noms.	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Aucun	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 de 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 exemple, 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 est défini sur 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 demande 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.

Remarque Si les chaînes de caractères ANSI sont utilisées, il est possible que les données WSAQUERYSET dans lpqsRegInfo ne contiennent pas de résultats après 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 de l’instance de service.
lpServiceClassId	GUID correspondant à cette classe de service.
lpVersion	(Facultatif) Fournit le numéro de version de l’instance de service.
lpszComment	(Facultatif) Chaîne de commentaire facultative.
dwNameSpace	Voir le tableau suivant.
lpNSProviderId	Voir le tableau suivant.
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 de CSADDR_INFO référencées par lpcsaBuffer.
lpcsaBuffer	Pointeur vers un tableau de structures CSADDR_INFO qui contiennent la ou les adresses sur laquelle le service écoute.
lpBlob	(Facultatif) Il s’agit d’un pointeur vers une entité spécifique au fournisseur.

Comme illustré ci-dessous, la combinaison des dwNameSpace et lpNSProviderId membres déterminent 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 noms spécifié.
Identificateur d’espace de nom valide	Zéro	Tous les fournisseurs d’espace de noms qui prennent en charge l’espace de noms indiqué.
NS_ALL	Zéro	Tous les fournisseurs d’espace de noms.

Windows Phone 8 : la fonction WSASetServiceW est prise en charge pour les applications du Windows Phone Store sur 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.

Note

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