Interrogation d’un NLA

Pour obtenir la notification des réseaux logiques invalidés, utilisez la fonction WSANSPIoctl pour vous inscrire aux événements de changement d’emplacement réseau. Deux méthodes peuvent être utilisées pour déterminer si un emplacement réseau précédemment valide est devenu non valide : les méthodes d’interrogation ou la notification utilisant des E/S ou une messagerie Windows qui se chevauchent.

Les requêtes sont formées à l’aide des fonctions WSALookupServiceBegin, WSALookupServiceNext et WSALookupServiceEnd pour énumérer tous les réseaux logiques disponibles. L’utilisation de chacune de ces fonctions est expliquée individuellement tout au long du reste de cette section, en commençant par la fonction WSALookupServiceBegin .

Notes

NLA nécessite le fichier d’en-tête Mswsock.h, qui n’est pas inclus par défaut dans le fichier Winsock2.h.

 

Étape 1 : Lancer la requête

Pour une référence rapide, la fonction WSALookupServiceBegin a la syntaxe suivante :

INT WSALookupServiceBegin(
  LPWSAQUERYSET lpqsRestrictions,
  DWORD dwControlFlags,
  LPHANDLE lphLookup
);

NLA prend en charge les indicateurs de recherche dwControlFlags suivants :

LUP\_RETURN\_NAME LUP\_RETURN\_COMMENT LUP\_RETURN\_BLOB LUP\_RETURN\_ALL LUP\_DEEP

Ces indicateurs limitent les jeux de résultats retournés dans les appels suivants à la fonction WSALookupServiceNext aux réseaux qui contiennent des champs du type spécifié. Par exemple, la spécification de LUP_RETURN_BLOB dans le paramètre dwControlFlags de l’appel de fonction WSALookupServiceBegin restreint les jeux de résultats des appels ultérieurs à WSALookupServiceNext aux réseaux qui contiennent des informations BLOB. L’utilisation de l’indicateur LUP_RETURN_ALL revient à spécifier LUP_RETURN_NAME, LUP_RETURN_COMMENT et LUP_RETURN_BLOB, mais pas LUP_DEEP.

Pour obtenir une explication de ces indicateurs de recherche, consultez la page de référence de la fonction WSALookupServiceBegin .

Le handle de recherche retourné par NLA dans le paramètre lphLookup est privé à NLA et ne doit pas être modifié. Étant donné que le handle retourné est privé pour NLA, les fonctions telles que WSAGetOverlappedResult ne sont pas disponibles.

NLA retourne zéro en cas d’achèvement réussi, comme défini dans la page de référence de la fonction WSALookupServiceBegin . Sinon, NLA prend en charge les codes d’erreur suivants.

Error	Signification
WSANOTINITIALISED	Un appel réussi à la fonction WSAStartup pour initialiser NLA n’a pas été effectué.
WSAEINVAL	Un ou plusieurs paramètres n’étaient pas valides ou les paramètres spécifiés dans l’appel de fonction s’appliquent à des protocoles autres qu’IP.
WSASERVICE_NOT_FOUND	Le paramètre lpServiceClassId de la structure WSAQUERYSET passé dans le paramètre lpqsRestrictions contient un GUID non valide.
WSANO_DATA	L’indicateur LUP_CONTAINERS a été spécifié dans le paramètre dwControlFlags .
WSAEFAULT	Une violation d’accès s’est produite lors de la tentative d’accès aux paramètres fournis par l’utilisateur.
WSASYSNOTREADY	Le service NLA n’est pas disponible pour traiter la demande.
WSA_NOT_ENOUGH_MEMORY	NLA ou le service NLA n’a pas pu allouer suffisamment de mémoire pour traiter cette demande.

 

Étape 2 : Exécuter la requête

L’étape suivante de l’interrogation de NLA nécessite l’utilisation de la fonction WSALookupServiceNext . Pour référence rapide, la fonction WSALookupServiceNext a la syntaxe suivante :

INT WSALookupServiceNext(
  HANDLE hLookup,
  DWORD dwControlFlags,
  LPDWORD lpdwBufferLength,
  LPWSAQUERYSET lpqsResults
);

Le paramètre lLookup est le handle de recherche retourné par l’appel précédent à la fonction WSALookupServiceBegin .

Le paramètre dwControlFlags prend en charge les indicateurs suivants :

LUP\_RETURN\_NAME LUP\_RETURN\_COMMENT LUP\_RETURN\_BLOB LUP\_RETURN\_ALL LUP\_FLUSHPREVIOUS

Ces indicateurs sont indépendants des indicateurs pris en charge dans l’appel de fonction WSALookupServiceBegin . Notez que les contraintes spécifiées dans l’appel précédent à la fonction WSALookupServiceBegin limitent la recherche ; L’ajout d’indicateurs avec la fonction WSALookupServiceNext pour tenter d’élargir la requête au-delà des contraintes spécifiées dans l’appel WSALookupServiceBegin est ignoré en mode silencieux. Toutefois, la spécification d’un ensemble d’indicateurs plus restrictif que celui spécifié dans l’appel WSALookupServiceBegin est autorisée.

Si le réseau détaillé dans lpqsResults est un réseau actif, une série de structures NLA_BLOB est ajoutée comme spécifié dans le membre lpBlob de la structure WSAQUERYSET retournée dans lpqsResults. Ces structures NLA_BLOB peuvent être chaînées et peuvent être énumérées en parcourant la liste alors que NLA_BLOB.header.nextOffset est différent de zéro. Pour obtenir des résultats pour toutes les informations d’emplacement réseau, continuez à appeler la fonction WSALookupServiceNext jusqu’à ce que l’erreur WSA_E_NO_MORE soit retournée, comme expliqué dans la page de référence WSALookupServiceNext.

La fonction WSALookupServiceNext est également utilisée conjointement avec la fonction WSANSPIoctl pour recevoir une notification des modifications du réseau. Pour plus d’informations, consultez Notification de NLA .

NLA retourne zéro en cas de réussite de l’exécution. Les clients de NLA doivent continuer à appeler la fonction WSALookupServiceNext jusqu’à ce que WSA_E_NO_MORE soit retourné, indiquant que toutes les informations sur les réseaux disponibles ont été retournées.

Sinon, l’appel de la fonction WSALookupServiceNext pour NLA prend en charge les codes d’erreur suivants.

Error	Signification
WSANOTINITIALISED	Un appel réussi à la fonction WSAStartup qui initialisait L’accès réseau n’a pas été effectué.
WSA_INVALID_HANDLE	Le handle de recherche fourni dans le paramètre hLookup n’était pas un handle fournisseur de services NLA valide. Les clients doivent d’abord appeler la fonction WSALookupServiceBegin et recevoir un handle fournisseur de services NLA valide pour obtenir les résultats de la requête.
WSAESYSNOTREADY	Le service NLA n’est pas disponible pour traiter cette demande.
WSAEFAULT	La taille de mémoire tampon spécifiée dans le paramètre lpdwBufferLength était insuffisante pour contenir les résultats pointés par lpqsResults. La mémoire tampon requise est spécifiée dans lpdwBufferLength ; si le client ne peut pas fournir une mémoire tampon suffisamment grande, il peut appeler la fonction WSALookupServiceNext avec dwControlFlags défini sur LUP_FLUSHPREVIOUS pour ignorer l’entrée.
WSA_NOT_ENOUGH_MEMORY	NLA ne peut pas obtenir d’informations réseau auprès du service système NLA en raison d’une mémoire insuffisante dans le processus d’appel.
WSA_E_NO_MORE	Il n’existe aucun réseau supplémentaire à énumérer pour la requête.

 

Étape 3 : Arrêter la requête

Lorsque toutes les requêtes sur NLA sont terminées et qu’une application ne nécessite plus l’utilisation de NLA, un appel à la fonction WSALookupServiceEnd doit être effectué. N’appelez pas WSALookupServiceEnd si l’application reçoit une notification de modification en fonction de la requête envoyée. Pour plus d’informations sur la réception d’une notification, consultez Notification de NLA . Comme la plupart des fournisseurs de services Windows Sockets, NLA gère un nombre de références pour ses clients. L’appel de la fonction WSALookupServiceEnd lorsque les requêtes vers NLA sont terminées permet de libérer les ressources système qui n’ont plus besoin de NLA.

NLA prend en charge les codes d’erreur suivants pour les appels de fonction WSALookupServiceEnd .

Error	Signification
WSANOTINITIALISED	Un appel réussi à la fonction WSAStartup pour initialiser NLA n’a pas été effectué.
WSA_INVALID_HANDLE	Le handle fourni dans le paramètre hLookup n’était pas un handle fournisseur de services NLA valide.