LPNSPV2LOOKUPSERVICENEXTEX fonction de rappel (ws2spi.h)
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 |
|---|---|
|
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. |
|
|
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. |
|
|
La mémoire tampon |
|
| Un ou plusieurs paramètres ne sont pas valides ou manquants pour ce fournisseur. | |
| Le handle de recherche spécifié n’est pas valide. | |
| Le nom a été trouvé dans la base de données, mais aucune donnée, correspondant aux restrictions données, a été trouvée. | |
| Le service est inconnu. Le service est introuvable dans l’espace de noms spécifié. | |
| 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 |