LPNSPV2LOOKUPSERVICENEXTEX fonction de rappel (ws2spi.h)

Article
07/16/2024

La fonction NSPv2LookupServiceNextEx est appelée après avoir obtenu un handle d’un appel précédent pour 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 volumineuse, le paramètre LUP_FLUSHPREVIOUS demande au fournisseur d’ignorer le dernier jeu de résultats, qui était trop volumineux et passez à 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 le lpqsResults récupérer l’enregistrement.

[out] lpqsResults

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

Valeur de retour

La fonction doit retourner NO_ERROR (zéro) si la routine réussit. Elle doit retourner SOCKET_ERROR (autrement dit, 1) si la routine échoue et qu’elle 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 de la mémoire tampon lpqsResults ne sont pas définies. Dans Windows Sockets 2, les 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 possible d’applications.
WSA_E_NO_MORE	Il n’y a plus de données disponibles. Dans Windows Sockets 2, les 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 possible d’applications.
WSAEFAULT	La mémoire tampon lpqsResults était trop petite pour contenir un jeu de 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, 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	Il n’y a pas suffisamment de mémoire disponible 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 transmet une structure de 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ées dans cette fonction et celles spécifiées au moment de NSPv2LookupServiceBegin sont gérées comme des « restrictions » à des fins de combinaison. Les restrictions sont combinées entre celles à NSPv2LookupServiceBegin temps et celles à NSPv2LookupServiceNextEx heure. 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é à NSPv2LookupServiceBegin, bien qu’il ne s’agit pas d’une erreur pour spécifier plus ou moins d’indicateurs. Les indicateurs spécifiés à un NSPv2LookupServiceNextEx s’appliquent uniquement à cet appel.

Les dwControlFlagsLUP_FLUSHPREVIOUS et LUP_RES_SERVICE 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 ou l’autre indicateur est utilisé dans NSPv2LookupServiceNextEx, ils ont leur effet défini, quel que soit le paramètre des mêmes indicateurs à NSPv2LookupServiceBegin.

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

Par exemple, si LUP_RETURN_BLOB n’est pas spécifié à NSPv2LookupServiceBegin, mais qu’elle est spécifiée à 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é par 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 les résultats WSAQUERYSET2.

La structure WSAQUERYSET2 pointée par le paramètre lpqsResults retourné n’est utile que dans le même contexte de processus, car plusieurs 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 par 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 dans un formulaire qui peut être passé entre les limites du processus. La transmission d’une copie de la structure WSAQUERYSET2 est insuffisante, 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 WSAQUERYSET2 et décrit comment les résultats de la requête sont représentés dans la structure **WSAQUERYSET2**. Pour plus d’informations, consultez Query-Related structures de données.

nom du membre WSAQUERYSET2	Interprétation des résultats
dwSize	Taille, en octets, de WSAQUERYSET2 structure. Il s’agit d’un 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 de l’instance de service particulière.
lpszComment	Chaîne de commentaire fournie par l’instance de service. Ce membre est facultatif, en fonction des exigences du fournisseur de services NSPv2.
dwNameSpace	Identificateur d’espace de noms dans lequel le nom ou l’instance de service a été trouvé.
lpNSProviderId	Fournisseur d’espace de noms spécifique qui a fourni ce résultat de requête.
lpszContext	Point de contexte dans un espace de noms hiérarchique auquel 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 situent dans les structures CSADDR_INFO.
lpszQueryString	Lorsque dwControlFlags inclut LUP_RETURN_QUERY_STRING, ce membre retourne le reste non traité 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 dans cet hôte, l’adresse retournée peut être l’adresse de l’hôte et le reste non traité peut être le chemin d’accès au fichier. Si lpszServiceInstanceName est entièrement analysé et 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, en fonction des exigences du fournisseur de services NSPv2.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	ws2spi.h

Voir aussi

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

nom du membre WSAQUERYSET2	Interprétation des résultats
dwSize	Taille, en octets, de WSAQUERYSET2 structure. Il s’agit d’un 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 de l’instance de service particulière.
lpszComment	Chaîne de commentaire fournie par l’instance de service. Ce membre est facultatif, en fonction des exigences du fournisseur de services NSPv2.
dwNameSpace	Identificateur d’espace de noms dans lequel le nom ou l’instance de service a été trouvé.
lpNSProviderId	Fournisseur d’espace de noms spécifique qui a fourni ce résultat de requête.
lpszContext	Point de contexte dans un espace de noms hiérarchique auquel 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 situent dans les structures CSADDR_INFO.
lpszQueryString	Lorsque dwControlFlags inclut LUP_RETURN_QUERY_STRING, ce membre retourne le reste non traité 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 dans cet hôte, l’adresse retournée peut être l’adresse de l’hôte et le reste non traité peut être le chemin d’accès au fichier. Si lpszServiceInstanceName est entièrement analysé et 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, en fonction des exigences du fournisseur de services NSPv2.

Partager via