Partager via


WSASetServiceA, fonction (winsock2.h)

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é.

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

Voir aussi

Bluetooth et WSASetService

WSAGetLastError

WSAStartup

Fonctions Winsock

Informations de référence sur Winsock