LPNSPV2LOOKUPSERVICENEXTEX fonction de rappel (ws2spi.h)

Article
08/28/2023

La fonction NSPv2LookupServiceNextEx est appelée après avoir obtenu un handle à partir d’un appel précédent à NSPv2LookupServiceBegin afin de récupérer les informations demandées à partir d’un fournisseur de services d’espace de noms version 2.

Syntaxe

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Paramètres

[in] hAsyncCall

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

[in] hLookup

Handle retourné par l’appel précédent à NSPv2LookupServiceBegin.

[in] dwControlFlags

Indicateurs utilisés pour contrôler l’opération suivante. Actuellement, seule LUP_FLUSHPREVIOUS est définie comme un moyen de gérer un jeu de résultats trop volumineux. Si une application ne peut pas fournir une mémoire tampon suffisamment grande, la définition de LUP_FLUSHPREVIOUS indique au fournisseur d’ignorer le dernier jeu de résultats, qui était trop volumineux, et de passer à l’ensemble suivant pour cet appel.

[in, out] lpdwBufferLength

Taille, en octets, en entrée, contenue dans la mémoire tampon pointée par lpqsResults. En sortie, si la fonction échoue et que l’erreur est WSAEFAULT, elle contient la taille minimale, en octets à passer, pour que l’objet lpqsResults récupère l’enregistrement.

[out] lpqsResults

Pointeur vers un bloc de mémoire qui contiendra, au retour, un jeu de résultats dans une structure WSAQUERYSET2 .

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_E_CANCELLED	Un appel à NSPv2LookupServiceEnd a été effectué pendant le traitement de cet appel. L’appel a été annulé. Les données dans la mémoire tampon lpqsResults ne sont pas définies. Dans les sockets Windows 2, des codes d’erreur en conflit sont définis pour WSAECANCELLED (10103) et WSA_E_CANCELLED (10111). Le code d’erreur WSAECANCELLED sera supprimé dans une version ultérieure et seuls WSA_E_CANCELLED resteront. Les fournisseurs d’espaces de noms doivent utiliser le code d’erreur WSA_E_CANCELLED pour maintenir la compatibilité avec la plus large gamme d’applications possible.
WSA_E_NO_MORE	Il n’y a plus de données disponibles. Dans les sockets Windows 2, des codes d’erreur en conflit sont définis pour WSAENOMORE (10102) et WSA_E_NO_MORE (10110). Le code d’erreur WSAENOMORE sera supprimé dans une version ultérieure et seuls WSA_E_NO_MORE resteront. Les fournisseurs d’espaces de noms doivent utiliser le code d’erreur WSA_E_NO_MORE pour maintenir la compatibilité avec la plus large gamme d’applications possible.
WSAEFAULT	La mémoire tampon lpqsResults était trop petite pour contenir un ensemble WSAQUERYSET .
WSAEINVAL	Un ou plusieurs paramètres ne sont pas valides ou manquants pour ce fournisseur.
WSA_INVALID_HANDLE	Le handle de recherche spécifié n’est pas valide.
WSANO_DATA	Le nom a été trouvé dans la base de données, mais aucune donnée, correspondant aux restrictions données, n’a été trouvée.
WSASERVICE_NOT_FOUND	Le service est inconnu. Le service est introuvable dans l’espace de noms spécifié.
WSA_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour effectuer cette opération.

Remarques

La fonction NSPv2LookupServiceNextEx 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 NSPv2LookupServiceNextEx ne peut être utilisée que pour les opérations sur NS_EMAIL fournisseurs d’espaces de noms.

Le fournisseur passe une structure WSAQUERYSET2 dans la mémoire tampon lpqsResults . Le client doit appeler la fonction NSPv2LookupServiceNextEx jusqu’à ce qu’elle retourne WSA_E_NOMORE, indiquant que toutes les structures WSAQUERYSET2 ont été retournées.

Les dwControlFlags spécifiés dans cette fonction et ceux spécifiés au moment de NSPv2LookupServiceBegin sont gérés en tant que « restrictions » à des fins de combinaison. Les restrictions sont combinées entre celles à l’heure NSPv2LookupServiceBegin et celles à l’heure NSPv2LookupServiceNextEx . Par conséquent, les indicateurs de NSPv2LookupServiceNextEx ne peuvent jamais augmenter la quantité de données retournées au-delà de ce qui a été demandé dans NSPv2LookupServiceBegin, bien que ce ne soit pas une erreur de spécifier plus ou moins d’indicateurs. Les indicateurs spécifiés dans un NSPv2LookupServiceNextEx donné s’appliquent uniquement à cet appel.

Les LUP_FLUSHPREVIOUS et LUP_RES_SERVICE dwControlFlags sont des exceptions à la règle de restrictions combinées (car il s’agit d’indicateurs de comportement au lieu d’indicateurs de « restriction »). Si l’un des indicateurs est utilisé dans NSPv2LookupServiceNextEx, ils ont leur effet défini, quel que soit le paramètre des mêmes indicateurs sur NSPv2LookupServiceBegin.

Par exemple, si LUP_RETURN_VERSION est spécifié dans NSPv2LookupServiceBegin, le fournisseur de services récupère les enregistrements, y compris la version. Si LUP_RETURN_VERSION n’est pas spécifié dans NSPv2LookupServiceNextEx, les informations retournées n’incluent pas la version, même si elles étaient disponibles. Aucune erreur n’est générée.

Par exemple, si LUP_RETURN_BLOB n’est pas spécifié dans NSPv2LookupServiceBegin, mais est spécifié dans NSPv2LookupServiceNextEx, les informations retournées n’incluent pas les données privées. Aucune erreur n’est générée.

La fonction NSPv2LookupServiceNextEx est généralement appelée au moins deux fois. La première fois pour obtenir la taille de la mémoire tampon nécessaire pour recevoir le WSAQUERYSET2 pointé vers le paramètre lpqsResults , et la deuxième fois pour obtenir le jeu de résultats de requête réel. Lors du premier appel, le fournisseur NSPv2 doit retourner la taille nécessaire pour le WSAQUERYSET2 résultats.

La structure WSAQUERYSET2 pointée par le paramètre lpqsResults retourné n’est utile que dans le même contexte de processus, car plusieurs des membres de la structure WSAQUERYSET2 contiennent des pointeurs vers les données réelles retournées. Si le résultat de la requête doit être passé à un autre processus (à l’aide de RPC, par exemple), il sera nécessaire de sérialiser et de marshaler les données retournées dans la structure WSAQUERYSET2 pointée vers laquelle le paramètre lpqsResults , y compris les données pointées par les membres de la structure WSAQUERYSET2 . Les données doivent être sérialisées sous une forme qui peut être transmise au-delà des limites du processus. Le simple passage d’une copie de la structure WSAQUERYSET2 est insuffisant, car seuls les pointeurs vers les données seront transmis et les données réelles ne seront pas disponibles pour d’autres processus.

Résultats de la requête

Le tableau suivant répertorie les WSAQUERYSET2 et décrit la façon dont les résultats de la requête sont représentés dans la structure **WSAQUERYSET2**. Pour plus d’informations, consultez Structures de données liées aux requêtes.

WSAQUERYSET2 nom du membre	Interprétation du résultat
dwSize	Taille, en octets, de WSAQUERYSET2 structure. Il est utilisé comme mécanisme de contrôle de version.
lpszServiceInstanceName	Chaîne qui contient le nom du service.
lpVersion	Référence le numéro de version du instance de service particulier.
lpszComment	Chaîne de commentaire fournie par le service instance. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNameSpace	Identificateur d’espace de noms dans lequel le nom ou le service instance a été trouvé.
lpNSProviderId	Fournisseur d’espaces de noms spécifique qui a fourni ce résultat de requête.
lpszContext	Point de contexte dans un espace de noms hiérarchique où se trouve le service.
dwNumberOfProtocols	Ce membre n’est pas défini pour les résultats.
lpafpProtocols	Ce membre n’est pas défini pour les résultats. Toutes les informations de protocole nécessaires se trouve dans les structures CSADDR_INFO .
lpszQueryString	Lorsque dwControlFlags inclut LUP_RETURN_QUERY_STRING, ce membre retourne le reste non évalué du lpszServiceInstanceName spécifié dans la requête d’origine. Par exemple, dans un espace de noms qui identifie les services par des noms hiérarchiques qui spécifient un nom d’hôte et un chemin d’accès de fichier au sein de cet hôte, l’adresse retournée peut être l’adresse de l’hôte et le reste non traité peut être le chemin du fichier. Si le lpszServiceInstanceName est entièrement analysé et que LUP_RETURN_QUERY_STRING est utilisé, ce membre est null ou pointe vers une chaîne de longueur nulle.
dwNumberOfCsAddrs	Nombre d’éléments dans le tableau de structures CSADDR_INFO .
lpcsaBuffer	Pointeur vers un tableau de structures CSADDR_INFO , avec une adresse de transport complète contenue dans chaque élément.
dwOutputFlags	L’indicateur RESULT_IS_ALIAS indique qu’il s’agit d’un résultat d’alias.
lpBlob	Pointeur vers une entité spécifique au fournisseur. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.

Spécifications


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

Voir aussi

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

WSAQUERYSET2 nom du membre	Interprétation du résultat
dwSize	Taille, en octets, de WSAQUERYSET2 structure. Il est utilisé comme mécanisme de contrôle de version.
lpszServiceInstanceName	Chaîne qui contient le nom du service.
lpVersion	Référence le numéro de version du instance de service particulier.
lpszComment	Chaîne de commentaire fournie par le service instance. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.
dwNameSpace	Identificateur d’espace de noms dans lequel le nom ou le service instance a été trouvé.
lpNSProviderId	Fournisseur d’espaces de noms spécifique qui a fourni ce résultat de requête.
lpszContext	Point de contexte dans un espace de noms hiérarchique où se trouve le service.
dwNumberOfProtocols	Ce membre n’est pas défini pour les résultats.
lpafpProtocols	Ce membre n’est pas défini pour les résultats. Toutes les informations de protocole nécessaires se trouve dans les structures CSADDR_INFO .
lpszQueryString	Lorsque dwControlFlags inclut LUP_RETURN_QUERY_STRING, ce membre retourne le reste non évalué du lpszServiceInstanceName spécifié dans la requête d’origine. Par exemple, dans un espace de noms qui identifie les services par des noms hiérarchiques qui spécifient un nom d’hôte et un chemin d’accès de fichier au sein de cet hôte, l’adresse retournée peut être l’adresse de l’hôte et le reste non traité peut être le chemin du fichier. Si le lpszServiceInstanceName est entièrement analysé et que LUP_RETURN_QUERY_STRING est utilisé, ce membre est null ou pointe vers une chaîne de longueur nulle.
dwNumberOfCsAddrs	Nombre d’éléments dans le tableau de structures CSADDR_INFO .
lpcsaBuffer	Pointeur vers un tableau de structures CSADDR_INFO , avec une adresse de transport complète contenue dans chaque élément.
dwOutputFlags	L’indicateur RESULT_IS_ALIAS indique qu’il s’agit d’un résultat d’alias.
lpBlob	Pointeur vers une entité spécifique au fournisseur. Ce membre est facultatif, dépendant des exigences du fournisseur de services NSPv2.

Partager via