Partager via


WNetAddConnection3A, fonction (winnetwk.h)

La fonction WNetAddConnection3 établit une connexion à une ressource réseau. La fonction peut rediriger un appareil local vers la ressource réseau.

La fonction WNetAddConnection3 est similaire à la fonction WNetAddConnection2 . La main différence est que WNetAddConnection3 a un paramètre supplémentaire, un handle pour une fenêtre que le fournisseur de ressources réseau peut utiliser comme fenêtre propriétaire pour les boîtes de dialogue. La fonction WNetAddConnection2 et la fonction WNetAddConnection3 remplacent la fonction WNetAddConnection .

Syntaxe

DWORD WNetAddConnection3A(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Paramètres

[in] hwndOwner

Handle d’une fenêtre que le fournisseur de ressources réseau peut utiliser comme fenêtre propriétaire pour les boîtes de dialogue. Utilisez ce paramètre si vous définissez la valeur CONNECT_INTERACTIVE dans le paramètre dwFlags .

Le paramètre hwndOwner peut être NULL. Si c’est le cas, un appel à WNetAddConnection3 équivaut à appeler la fonction WNetAddConnection2 .

[in] lpNetResource

Pointeur vers une structure NETRESOURCE qui spécifie les détails de la connexion proposée, tels que des informations sur la ressource réseau, l’appareil local et le fournisseur de ressources réseau.

Vous devez spécifier les membres suivants de la structure NETRESOURCE .

Membre Signification
dwType
Type de ressource réseau à laquelle se connecter.

Si le membre lpLocalName pointe vers une chaîne vide, ce membre peut être égal à RESOURCETYPE_DISK ou RESOURCETYPE_PRINT.

Si lpLocalName a la valeur NULL ou s’il pointe vers une chaîne vide, dwType peut être égal à RESOURCETYPE_DISK, RESOURCETYPE_PRINT ou RESOURCETYPE_ANY.

Bien que ce membre soit obligatoire, ses informations peuvent être ignorées par le fournisseur de services réseau.

lpLocalName
Pointeur vers une chaîne terminée par null qui spécifie le nom d’un appareil local à rediriger, par exemple « F : » ou « LPT1 ». La chaîne est traitée de manière non respectant la casse.

Si la chaîne est vide ou si lpLocalName a la valeur NULL, la fonction établit une connexion à la ressource réseau sans rediriger un appareil local.

lpRemoteName
Pointeur vers une chaîne terminée par null qui spécifie la ressource réseau à laquelle se connecter. La chaîne peut contenir jusqu’à MAX_PATH caractères et doit suivre les conventions de nommage du fournisseur de réseau.
lpProvider
Pointeur vers une chaîne terminée par null qui spécifie le fournisseur réseau auquel se connecter.

Si lpProvider a la valeur NULL ou s’il pointe vers une chaîne vide, le système d’exploitation tente de déterminer le fournisseur correct en analysant la chaîne vers laquelle pointe le membre lpRemoteName .

Si ce membre n’a pas la valeur NULL, le système d’exploitation tente d’effectuer une connexion uniquement au fournisseur réseau nommé.

Vous devez définir ce membre uniquement si vous savez quel fournisseur réseau vous souhaitez utiliser. Sinon, laissez le système d’exploitation déterminer à quel fournisseur réseau le nom du réseau est mappé.

 

La fonction WNetAddConnection3 ignore les autres membres de la structure NETRESOURCE .

[in] lpPassword

Pointeur vers une chaîne terminée par null qui spécifie un mot de passe à utiliser pour établir la connexion réseau.

Si lpPassword a la valeur NULL, la fonction utilise le mot de passe par défaut actuel associé à l’utilisateur spécifié par le paramètre lpUserName .

Si lpPassword pointe vers une chaîne vide, la fonction n’utilise pas de mot de passe.

Si la connexion échoue en raison d’un mot de passe non valide et que la valeur CONNECT_INTERACTIVE est définie dans le paramètre dwFlags , la fonction affiche une boîte de dialogue demandant à l’utilisateur de taper le mot de passe.

Windows Me/98/95 : Ce paramètre doit être NULL ou une chaîne vide.

[in] lpUserName

Pointeur vers une chaîne terminée par null qui spécifie un nom d’utilisateur pour établir la connexion.

Si lpUserName a la valeur NULL, la fonction utilise le nom d’utilisateur par défaut. (Le contexte utilisateur du processus fournit le nom d’utilisateur par défaut.)

Le paramètre lpUserName est spécifié lorsque les utilisateurs souhaitent se connecter à une ressource réseau pour laquelle un nom d’utilisateur ou un compte autre que le nom d’utilisateur ou le compte par défaut leur a été attribué.

La chaîne de nom d’utilisateur représente un contexte de sécurité. Il peut être spécifique à un fournisseur de réseau.

Windows Me/98/95 : Ce paramètre doit être NULL ou une chaîne vide.

[in] dwFlags

Ensemble d’options de connexion. Les valeurs suivantes sont actuellement définies.

Valeur Signification
CONNECT_INTERACTIVE
Si cet indicateur est défini, le système d’exploitation peut interagir avec l’utilisateur à des fins d’authentification.
CONNECT_PROMPT
Cet indicateur indique au système de ne pas utiliser de paramètres par défaut pour les noms d’utilisateur ou les mots de passe sans offrir à l’utilisateur la possibilité de fournir une alternative. Cet indicateur est ignoré, sauf si CONNECT_INTERACTIVE est également défini.
CONNECT_REDIRECT
Cet indicateur force la redirection d’un appareil local lors de l’établissement de la connexion.

Si le membre lpLocalName de NETRESOURCE spécifie un appareil local à rediriger, cet indicateur n’a aucun effet, car le système d’exploitation tente toujours de rediriger l’appareil spécifié. Lorsque le système d’exploitation choisit automatiquement un appareil local, le membre dwType ne doit pas être égal à RESOURCETYPE_ANY.

Si cet indicateur n’est pas défini, un appareil local est automatiquement choisi pour la redirection uniquement si le réseau nécessite la redirection d’un appareil local.

Windows Server 2003 et Windows XP : Lorsque le système affecte automatiquement des lettres de lecteur réseau, les lettres commencent par Z :, puis Y :, et se terminent par C :. Cela réduit les collisions entre les lettres de lecteur par ouverture de session (telles que les lettres de lecteur réseau) et les lettres de lecteur global (telles que les lecteurs de disque). Notez que les versions antérieures des lettres de lecteur attribuées par Windows commençant par C : et se terminant par Z :.

CONNECT_UPDATE_PROFILE
La connexion aux ressources réseau doit être mémorisé.

Si cet indicateur de bits est défini, le système d’exploitation tente automatiquement de restaurer la connexion lorsque l’utilisateur se connecte.

Le système d’exploitation mémorise uniquement les connexions réussies qui redirigent les appareils locaux. Il ne se souvient pas des connexions qui échouent ou des connexions sans appareil. (Une connexion sans appareil se produit lorsque le membre lpLocalName a la valeur NULL ou lorsqu’il pointe vers une chaîne vide.)

Si cet indicateur de bits est clair, le système d’exploitation ne restaure pas automatiquement la connexion lors de l’ouverture de session.

CONNECT_COMMANDLINE
Si cet indicateur est défini, le système d’exploitation invite l’utilisateur à l’authentification à l’aide de la ligne de commande au lieu d’une interface utilisateur graphique (GUI). Cet indicateur est ignoré, sauf si CONNECT_INTERACTIVE est également défini.

Windows 2000/NT et Windows Me/98/95 : Cette valeur n’est pas prise en charge.

CONNECT_CMD_SAVECRED
Si cet indicateur est défini et que le système d’exploitation demande des informations d’identification, les informations d’identification doivent être enregistrées par le gestionnaire d’informations d’identification. Si le gestionnaire d’informations d’identification est désactivé pour la session d’ouverture de session de l’appelant ou si le fournisseur réseau ne prend pas en charge l’enregistrement des informations d’identification, cet indicateur est ignoré. Cet indicateur est également ignoré, sauf si vous définissez l’indicateur CONNECT_COMMANDLINE.

Windows 2000/NT et Windows Me/98/95 : Cette valeur n’est pas prise en charge.

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, tel qu’une des valeurs suivantes.

Code de retour Description
ERROR_ACCESS_DENIED
L’appelant n’a pas accès à la ressource réseau.
ERROR_ALREADY_ASSIGNED
L’appareil local spécifié par le membre lpLocalName est déjà connecté à une ressource réseau.
ERROR_BAD_DEV_TYPE
Le type d’appareil local et le type de ressource réseau ne correspondent pas.
ERROR_BAD_DEVICE
La valeur spécifiée par lpLocalName n’est pas valide.
ERROR_BAD_NET_NAME
La valeur spécifiée par le membre lpRemoteName n’est acceptable pour aucun fournisseur de ressources réseau, soit parce que le nom de la ressource n’est pas valide, soit parce que la ressource nommée ne peut pas être trouvée.
ERROR_BAD_PROFILE
Le profil utilisateur est dans un format incorrect.
ERROR_BAD_PROVIDER
La valeur spécifiée par le membre lpProvider ne correspond à aucun fournisseur.
ERROR_BUSY
Le routeur ou le fournisseur est occupé, peut-être à l’initialisation. L’appelant doit réessayer.
ERROR_CANCELLED
La tentative de connexion a été annulée par l’utilisateur via une boîte de dialogue à partir de l’un des fournisseurs de ressources réseau ou par une ressource appelée.
ERROR_CANNOT_OPEN_PROFILE
Le système ne peut pas ouvrir le profil utilisateur pour traiter les connexions persistantes.
ERROR_DEVICE_ALREADY_REMEMBERED
Une entrée pour l’appareil spécifié par le membre lpLocalName se trouve déjà dans le profil utilisateur.
ERROR_EXTENDED_ERROR
Une erreur spécifique au réseau s’est produite. Appelez la fonction WNetGetLastError pour obtenir une description de l’erreur.
ERROR_INVALID_PASSWORD
Le mot de passe spécifié n’est pas valide et l’indicateur CONNECT_INTERACTIVE n’est pas défini.
ERROR_NO_NET_OR_BAD_PATH
L’opération ne peut pas être effectuée parce qu’un composant réseau n’est pas démarré ou parce qu’un nom spécifié ne peut pas être utilisé.
ERROR_NO_NETWORK
Le réseau n'est pas disponible.

Remarques

La fonction WNetUseConnection est similaire à la fonction WNetAddConnection3 . La main différence est que WNetUseConnection peut sélectionner automatiquement un appareil local inutilisé à rediriger vers la ressource réseau.

Sur Windows Server 2003 et Windows XP, les fonctions WNet créent et suppriment des lettres de lecteur réseau dans l’espace de noms d’appareil MS-DOS associé à une session de connexion, car les appareils MS-DOS sont identifiés par AuthenticationID (un
identificateur unique local, 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 au sein d’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 . L’appel à la fonction GetLogicalDrives ne retourne pas les lettres de lecteur réseau créées par les appels de 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.

Sur Windows Server 2003 et Windows XP, si un service qui s’exécute en tant que LocalSystem appelle la fonction WNetAddConnection3 , le lecteur mappé est visible pour toutes les sessions d’ouverture de session utilisateur.

Pour les fournisseurs de réseau Microsoft, le membre lpRemoteName de la structure NETRESOURCE pointée vers le paramètre lpNetResource peut contenir une adresse IPv4 en notation décimale en pointillés. Voici un exemple de partage :

\192.168.1.1\share

Pour les fournisseurs de réseau Microsoft sur Windows Vista et versions ultérieures, le membre lpRemoteName de la structure NETRESOURCE pointée par le paramètre lpNetResource peut contenir une adresse IPv6. Toutefois, le format littéral IPv6 doit être utilisé pour que l’adresse IPv6 soit analysée correctement. Une adresse littérale IPv6 se présente sous la forme suivante :

ipv6-address avec les caractères « : » remplacés par les caractères « - », suivis de la chaîne « ipv6-literal.net ».

Par exemple, pour l’adresse IPv6 suivante :

2001:4898:9:3:c069:aa97:fe76:2449

un exemple pour un partage peut être le suivant :

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

D’autres fournisseurs de réseau peuvent prendre en charge le membre lpRemoteName de la structure NETRESOURCE pointée vers le paramètre lpNetResource qui contient une adresse IPv4 ou IPv6, mais cela appartient à un fournisseur réseau spécifique.

Windows 7 et Windows Server 2008 R2 : Si la fonction WNetAddConnection3 est appelée avec des informations d’identification d’utilisateur explicites spécifiées dans pUsername et lpPassword pour établir une connexion avec une ressource réseau sur un serveur spécifique, puis appelée à nouveau avec l’un de ces paramètres null ( pour utiliser le nom d’utilisateur ou le mot de passe par défaut) sur le même serveur, l’appel avec échec. L’erreur retournée sera ERROR_BAD_USERNAME ou ERROR_INVALID_PASSWORD.

Notes

L’en-tête winnetwk.h définit WNetAddConnection3 comme un 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.

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

Voir aussi

NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Vue d’ensemble de Windows Networking (WNet)

Fonctions de mise en réseau Windows