WNetGetConnectionW, fonction (winnetwk.h)

Article
08/27/2023

La fonction WNetGetConnection récupère le nom de la ressource réseau associée à un appareil local.

Syntaxe

DWORD WNetGetConnectionW(
  [in]      LPCWSTR lpLocalName,
  [out]     LPWSTR  lpRemoteName,
  [in, out] LPDWORD lpnLength
);

Paramètres

[in] lpLocalName

Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom de l’appareil local pour lequel obtenir le nom du réseau.

[out] lpRemoteName

Pointeur vers une chaîne terminée par null qui reçoit le nom distant utilisé pour établir la connexion.

[in, out] lpnLength

Pointeur vers une variable qui spécifie la taille de la mémoire tampon vers laquelle pointe le paramètre lpRemoteName , en caractères. Si la fonction échoue parce que la mémoire tampon n’est pas suffisamment grande, ce paramètre retourne la taille de mémoire tampon requise.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est un code d’erreur système, comme l’une des valeurs suivantes.

Code de retour	Description
ERROR_BAD_DEVICE	La chaîne pointée par le paramètre lpLocalName n’est pas valide.
ERROR_NOT_CONNECTED	L’appareil spécifié par lpLocalName n’est pas un appareil redirigé. Pour plus d'informations, consultez la section Notes qui suit.
ERROR_MORE_DATA	La mémoire tampon est trop petite. Le paramètre lpnLength pointe vers une variable qui contient la taille de mémoire tampon requise. D’autres entrées sont disponibles avec les appels suivants.
ERROR_CONNECTION_UNAVAIL	L’appareil n’est actuellement pas connecté, mais il s’agit d’une connexion persistante. Pour plus d'informations, consultez la section Notes qui suit.
ERROR_NO_NETWORK	Le réseau n'est pas disponible.
ERROR_EXTENDED_ERROR	Une erreur spécifique au réseau s’est produite. Pour obtenir une description de l’erreur, appelez la fonction WNetGetLastError .
ERROR_NO_NET_OR_BAD_PATH	Aucun des fournisseurs ne reconnaît le nom local comme ayant une connexion. Toutefois, le réseau n’est pas disponible pour au moins un fournisseur auquel la connexion peut appartenir.

Remarques

Si la connexion réseau a été établie à l’aide du réseau Microsoft LAN Manager et que l’application appelante s’exécute dans une session de connexion différente de celle de l’application qui a établi la connexion, un appel à la fonction WNetGetConnection pour l’appareil local associé échoue. La fonction échoue avec ERROR_NOT_CONNECTED ou ERROR_CONNECTION_UNAVAIL. En effet, une connexion établie à l’aide de Microsoft LAN Manager n’est visible que pour les applications qui s’exécutent dans la même session d’ouverture de session que l’application qui a créé la connexion. (Pour empêcher l’échec de l’appel à WNetGetConnection , il ne suffit pas que l’application s’exécute dans le compte d’utilisateur qui a créé la connexion.)

Windows Server 2003 et Windows XP : Cette fonction interroge les espaces de noms d’appareils MS-DOS associés à une session d’ouverture de session, car les appareils MS-DOS sont identifiés par AuthenticationID. (Un AuthenticationID est l’identificateur local unique, ou LUID, associé à une session d’ouverture de session.) Cela peut affecter les applications qui appellent l’une des fonctions WNet pour créer une lettre de lecteur réseau sous une ouverture de session utilisateur, mais qui interrogent les lettres de lecteur réseau existantes sous une autre ouverture de session utilisateur. Un exemple de cette situation peut être lorsque la deuxième ouverture de session d’un utilisateur est créée dans une session d’ouverture de session, par exemple, en appelant la fonction CreateProcessAsUser , et que la deuxième ouverture de session exécute une application qui appelle la fonction GetLogicalDrives . GetLogicalDrives ne retourne pas de lettres de lecteur réseau créées par une fonction WNet sous la première ouverture de session. Notez que dans l’exemple précédent, la première session d’ouverture de session existe toujours et que l’exemple peut s’appliquer à n’importe quelle session d’ouverture de session, y compris une session Des services Terminal Server. Pour plus d’informations, consultez Définition d’un nom d’appareil MS-DOS.

Exemples

Pour obtenir un exemple de code illustrant comment utiliser la fonction WNetGetConnection pour récupérer le nom de la ressource réseau associée à un appareil local, consultez Récupération du nom de la connexion.

Notes

L’en-tête winnetwk.h définit WNetGetConnection en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winnetwk.h
Bibliothèque	Mpr.lib
DLL	Mpr.dll