LPNSPV2SETSERVICEEX fonction de rappel (ws2spi.h)

Article
03/04/2024

La fonction NSPv2SetServiceEx inscrit ou désinscrit un nom ou un service instance dans un espace de noms d’un fournisseur de services d’espace de noms version-2 (NSPv2).

Syntaxe

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

Paramètres

[in] hAsyncCall

Handle retourné par l’appel précédent à NSPv2LookupServiceBegin utilisé pour les appels asynchrones.

[in] lpProviderId

Pointeur vers le GUID du fournisseur d’espace de noms spécifique dans lequel le nom ou le service est inscrit.

[in] lpqsRegInfo

Informations de propriété à mettre à jour lors de l’inscription.

[in] essOperation

Type d’opération demandé.

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 0	Inscrivez le service. Pour l’espace de noms SAP (Service Advertising Protocol) utilisé dans un environnement NetWare, cela signifie l’envoi d’une diffusion périodique. Il s’agit d’un NOP pour l’espace de noms DNS (Domain Name System). Pour les magasins de données persistants, cela signifie mettre à jour les informations d’adresse.
RNRSERVICE_DEREGISTER 1	Désinscrire le service. Pour l’espace de noms SAP, cela signifie arrêter l’envoi périodique de la diffusion. 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 2	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 SERVICE_MULTIPLE), seule l’adresse fournie est supprimée, ce qui doit correspondre exactement à la structure CSADDR_INFO correspondante fournie lors de l’inscription du service.

[in] dwControlFlags

Ensemble d’indicateurs qui contrôle l’opération demandée.

Les valeurs possibles pour ce paramètre sont définies dans le fichier d’en-tête Winsock2.h .

Valeur	Signification
SERVICE_MULTIPLE 0x00000001	Contrôler l’étendue de l’opération. Lorsque cette valeur est définie, l’action n’est effectuée que sur le jeu d’adresses donné. Une opération d’inscription n’invalide pas les adresses existantes et une opération de désinscription invalide uniquement l’ensemble d’adresses donné. Lorsque cette valeur est absente, les adresses de service sont gérées en tant que groupe. Une inscription ou une désinscription invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné.

Valeur

Signification

SERVICE_MULTIPLE

0x00000001

Contrôler l’étendue de l’opération.

Lorsque cette valeur est définie, l’action n’est effectuée que sur le jeu d’adresses donné. Une opération d’inscription n’invalide pas les adresses existantes et une opération de désinscription invalide uniquement l’ensemble d’adresses donné.

Lorsque cette valeur est absente, les adresses de service sont gérées en tant que groupe. Une inscription ou une désinscription invalide toutes les adresses existantes avant d’ajouter le jeu d’adresses donné.

[in] lpvClientSessionArg

Pointeur vers la session cliente.

Valeur retournée

La fonction doit retourner NO_ERROR (zéro) si la routine réussit. Il doit retourner SOCKET_ERROR (c’est-à-dire 1) si la routine échoue et il doit définir le code d’erreur approprié à l’aide de WSASetLastError.

Code d'erreur	Signification
WSA_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour effectuer cette opération.
WSAEACCES	La routine appelante ne dispose pas des privilèges suffisants pour installer le service.
WSAEINVAL	Un ou plusieurs paramètres n’étaient pas valides ou manquants pour ce fournisseur.
WSAEOPNOTSUPP	L'opération n'est pas prise en charge. Cette erreur est retournée si le fournisseur d’espaces de noms n’implémente pas cette fonction. Cette erreur peut également être retournée si le dwControlCode spécifié est une commande non reconnue.
WSASERVICE_NOT_FOUND	Le service est inconnu. Le service est introuvable dans l’espace de noms spécifié.

Remarques

La fonction NSPv2SetServiceEx est utilisée dans le cadre de l’architecture du fournisseur de services d’espace de noms version 2 (NSPv2) disponible sur Windows Vista et versions ultérieures.

Sur Windows Vista et Windows Server 2008, la fonction NSPv2SetServiceEx ne peut être utilisée que pour les opérations sur NS_EMAIL fournisseurs d’espaces de noms.

La fonction NSPv2Startup est appelée chaque fois qu’un nouveau processus client commence à utiliser le fournisseur d’espaces de noms. Les fournisseurs peuvent utiliser l’argument de session client pointé vers le paramètre ppvClientSessionArg pour stocker des informations sur cette session. Cet argument de session client peut être passé à la fonction NSPv2SetServiceEx dans le paramètre lpvClientSessionArg .

La fonction NSPv2SetServiceEx est facultative, dépendant des exigences du fournisseur NSPv2. Si la fonction NSPv2SetServiceEx n’est pas implémentée, le pointeur de la fonction NSPv2 peut être vers une fonction stub qui retourne toujours NO_ERROR.

Le tableau suivant répertorie la combinaison possible de valeurs pour les paramètres essOperation et dwControlFlags .

essOperation	dwControlFlags	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 ENREGISTRÉ.	Crée un objet. Utilise uniquement les adresses spécifiées. L’objet est ENREGISTRÉ.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Mises à jour objet. Ajoute de nouvelles adresses à l’ensemble existant. L’objet est ENREGISTRÉ.	Crée un objet. Utilise toutes les adresses spécifiées. L’objet est ENREGISTRÉ.
RNRSERVICE_DEREGISTER	None	Supprime toutes les adresses, mais ne supprime pas l’objet de l’espace de noms. L’objet est DEREGISTERED.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Mises à jour objet. Supprime uniquement les adresses spécifiées. Marquez uniquement l’objet comme DEREGISTERED si aucune adresse n’est présente. Ne supprime pas 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

Lorsque le paramètre dwControlFlags est défini sur SERVICE_MULTIPLE, cela permet à une application de gérer ses adresses indépendamment. Cela est utile lorsque l’application doit gérer ses protocoles individuellement ou lorsque le service réside sur plusieurs ordinateurs. Par exemple, lorsqu’un service utilise plusieurs protocoles, un socket d’écoute peut abandonner, mais les autres sockets restent opérationnels. Dans cet exemple, le service peut annuler l’inscription de l’adresse abandonnée sans affecter les autres adresses.

Lors de l’utilisation de SERVICE_MULTIPLE, une application ne doit pas laisser les anciennes adresses rester dans l’objet . Cela peut se produire si l’application abandonne sans émettre de demande de RNRSERVICE_DEREGISTER . Lorsqu’un service s’inscrit, il doit stocker ses adresses. Lors de son appel suivant, le service doit explicitement annuler l’inscription de ces anciennes adresses avant d’inscrire de nouvelles adresses.

Si la fonction NSPv2SetServiceEx n’est pas implémentée, les appels à cette fonction doivent être interceptés par une fonction stub qui retourne WSAEOPNOTSUPP. Le pointeur de la fonction NSPv2 vers la fonction NSPv2SetServiceEx non implémentée dans la structure NSPV2_ROUTINE doit pointer vers la fonction stub.

Propriétés du service

Le tableau suivant répertorie WSAQUERYSET2 noms de membres et décrit la façon dont les données de propriété de service sont représentées. Les membres étiquetés comme facultatifs et dépendants des exigences du fournisseur NSPv2 peuvent être fournis en tant que pointeur **NULL** lorsqu’ils ne sont pas utilisés par le fournisseur d’espaces de noms.

WSAQUERYSET2 nom du membre	Description de la propriété de service
dwSize	Définissez sur sizeof(WSAQUERYSET2). Il s’agit d’un mécanisme de contrôle de version.
lpszServiceInstanceName	Chaîne qui contient le nom du service instance.
lpVersion	Numéro de version du service instance. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpszComment	Chaîne de commentaire. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
dwNameSpace	Identificateur de l’espace de noms. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpNSProviderId	Identificateur du fournisseur. Notez que l’identificateur du fournisseur d’espace de noms est également passé dans le paramètre lpProviderId . Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpszContext	Point de départ de la requête dans un espace de noms hiérarchique. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
dwNumberOfProtocols	Taille, en octets, du nombre d’entrées dans le tableau de contraintes de protocole. Ce membre peut être égal à zéro. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpafpProtocols	Tableau de structures AFPROTOCOLS . Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpszQueryString	Certains espaces de noms (comme whois++) prennent en charge les requêtes riches de type SQL contenues dans une chaîne de texte simple. Ce paramètre est utilisé pour spécifier cette chaîne. Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
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 l’adresse ou les adresses que le service écoute.
dwOutputFlags	Ce membre est facultatif et dépend des exigences du fournisseur de services NSPv2.
lpBlob	Pointeur vers une entité spécifique au fournisseur. Ce membre est requis pour l’espace de noms NS_EMAIL. Ce membre est facultatif et dépend de la configuration requise pour les autres fournisseurs de services NSPv2.

**Remarque** Il est acceptable que le membre **iProtocol** de la structure CSADDR_INFO contienne la constante manifeste **IPROTOCOL_ANY**, indiquant une valeur générique. Le fournisseur d’espaces de noms doit remplacer une valeur acceptable par la famille d’adresses et le type de socket donnés.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ws2spi.h