WNetGetConnectionA, fonction (winnetwk.h)

Article
11/20/2024

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

Syntaxe

DWORD WNetGetConnectionA(
  [in]      LPCSTR  lpLocalName,
  [out]     LPSTR   lpRemoteName,
  [in, out] LPDWORD lpnLength
);

Paramètres

[in] lpLocalName

Pointeur vers une chaîne constante terminée par 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 pointée par le paramètre lpRemoteName, en caractères. Si la fonction échoue, car la mémoire tampon n’est pas suffisamment grande, ce paramètre retourne la taille de mémoire tampon requise.

Valeur de retour

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 , par exemple l’une des valeurs suivantes.

Retourner le code	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 Remarques suivante.
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 pas actuellement connecté, mais il s’agit d’une connexion persistante. Pour plus d’informations, consultez la section Remarques suivante.
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 d’ouverture de session différente de celle de l’application qui a effectué la connexion, un appel à la fonction WNetGetConnection pour l’appareil local associé échoue. La fonction échoue avec ERROR_NOT_CONNECTED ou ERROR_CONNECTION_UNAVAIL. Cela est dû au fait qu’une connexion établie à l’aide de Microsoft LAN Manager est visible uniquement aux applications s’exécutant dans la même session d’ouverture de session que l’application qui a effectué la connexion. (Pour empêcher l’appel à WNetGetConnection d’échouer, il n’est pas suffisant 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. (AuthenticationID est l’identificateur identificateur unique localement, 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 connexion utilisateur, mais interroger les lettres de lecteur réseau existantes sous une autre ouverture de session utilisateur. Par exemple, 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 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 Terminal Services. 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 connexion.

Note

L’en-tête winnetwk.h définit WNetGetConnection comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winnetwk.h
bibliothèque	Mpr.lib
DLL	Mpr.dll