WNetAddConnection2A, fonction (winnetwk.h)
La fonction WNetAddConnection2 établit une connexion à une ressource réseau et peut rediriger un appareil local vers la ressource réseau.
La fonction WNetAddConnection2 remplace la fonction WNetAddConnection. Si vous pouvez passer un handle à une fenêtre que le fournisseur de ressources réseau peut utiliser comme fenêtre propriétaire pour les boîtes de dialogue, appelez la fonction WNetAddConnection3 à la place.
Syntaxe
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Paramètres
[in] lpNetResource
Pointeur vers une structure NETRESOURCE qui spécifie les détails de la connexion proposée, telles 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.
La fonction WNetAddConnection2
[in] lpPassword
Pointeur vers une constante chaîne null-terminated qui spécifie un mot de passe à utiliser pour établir la connexion réseau.
Si lpPassword est 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 constante chaîne null-terminated string qui spécifie un nom d’utilisateur pour établir la connexion.
Si lpUserName est 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 ils ont reçu un nom d’utilisateur ou un compte autre que le nom d’utilisateur ou le compte par défaut.
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 possibles pour les options de connexion sont définies dans le fichier d’en-tête Winnetwk.h. Les valeurs suivantes peuvent actuellement être utilisées.
| Valeur | Signification |
|---|---|
|
La connexion de ressource 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 sans appareil. (Une connexion sans appareil se produit lorsque le membre lpLocalName est NULL ou pointe vers une chaîne vide.) Si cet indicateur de bits est clair, le système d’exploitation n’essaie pas de restaurer la connexion lorsque l’utilisateur se connecte. |
|
La connexion de ressource réseau ne doit pas être placée dans la liste de connexions récente.
Si cet indicateur est défini et que la connexion est correctement ajoutée, la connexion de ressource réseau est placée dans la liste de connexions récente uniquement si un appareil local redirigé lui est associé. |
|
La connexion de ressource réseau ne doit pas être mémorisé.
Si cet indicateur est défini, le système d’exploitation ne tente pas de restaurer la connexion lorsque l’utilisateur se connecte à nouveau. |
|
Si cet indicateur est défini, le système d’exploitation peut interagir avec l’utilisateur à des fins d’authentification. |
|
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. |
|
Cet indicateur force la redirection d’un appareil local lors de la connexion.
Si le lpLocalName membre 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 qu’un appareil local soit redirigé. Windows Server 2003 et Windows XP : Lorsque le système affecte automatiquement des lettres de lecteur réseau, des lettres commencent par Z :, puis Y :, et se terminent par C :. Cela réduit la collision entre les lettres de lecteur par ouverture de session (telles que les lettres de lecteur réseau) et les lettres de lecteur globales (comme 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 :. |
|
Si cet indicateur est défini, le système d’exploitation ne commence pas à utiliser un nouveau média pour essayer d’établir la connexion (lancer une nouvelle connexion d’accès, par exemple). |
|
Si cet indicateur est défini, le système d’exploitation invite l’utilisateur à effectuer l’authentification à l’aide de la ligne de commande au lieu d’une interface graphique utilisateur (GUI). Cet indicateur est ignoré, sauf si CONNECT_INTERACTIVE est également défini.
Windows XP : Cette valeur est prise en charge sur Windows XP et versions ultérieures. |
|
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 ignoré, sauf si CONNECT_INTERACTIVE est également défini. Cet indicateur est également ignoré, sauf si vous définissez l’indicateur CONNECT_COMMANDLINE.
Windows XP : Cette valeur est prise en charge sur Windows XP et versions ultérieures. |
|
Si cet indicateur est défini et que le système d’exploitation demande des informations d’identification, les informations d’identification sont réinitialisé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 Vista : Cette valeur est prise en charge sur Windows Vista et versions ultérieures. |
Valeur de retour
Si la fonction réussit, la valeur de retour est NO_ERROR.
Si la fonction échoue, la valeur de retour peut être l’un des codes d’erreur suivants ou l’un des codes d’erreur système .
| Retourner le code | Description |
|---|---|
|
L’appelant n’a pas accès à la ressource réseau. |
|
L’appareil local spécifié par le membre lpLocalName est déjà connecté à une ressource réseau. |
|
Le type d’appareil local et le type de ressource réseau ne correspondent pas. |
|
Le nom de l’appareil spécifié n’est pas valide. Cette erreur est retournée si le membre |
|
Le nom du réseau est introuvable. Cette valeur est retournée si le membre lpRemoteName de la structure NETRESOURCE pointée par le paramètre lpNetResource spécifie une ressource qui n’est pas acceptable pour un fournisseur de ressources réseau, soit parce que le nom de la ressource est vide, non valide ou parce que la ressource nommée ne peut pas être localisée. |
|
Le profil utilisateur est dans un format incorrect. |
|
Le nom du fournisseur de réseau spécifié n’est pas valide. Cette erreur est retournée si le lpProvider membre de la structure NETRESOURCE pointée par le paramètre lpNetResource spécifie une valeur qui ne correspond à aucun fournisseur réseau. |
|
Le nom d’utilisateur spécifié n’est pas valide. |
|
Le routeur ou le fournisseur est occupé, éventuellement initialisation. L’appelant doit réessayer. |
|
La tentative d’annulation de la 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 d’une ressource appelée. |
|
Le système ne peut pas ouvrir le profil utilisateur pour traiter les connexions persistantes. |
|
Le nom de l’appareil local a une connexion mémorisé à une autre ressource réseau. Cette erreur est retournée si une entrée pour l’appareil spécifié par lpLocalName membre de la structure NETRESOURCE pointée par le paramètre lpNetResource spécifie une valeur déjà dans le profil utilisateur pour une connexion différente de celle spécifiée dans le paramètre lpNetResource. |
|
Une erreur spécifique au réseau s’est produite. Appelez la fonction WNetGetLastError pour obtenir une description de l’erreur. |
|
Une tentative a été effectuée pour accéder à une adresse non valide. Cette erreur est retournée si le paramètre dwFlags spécifie une valeur de CONNECT_REDIRECT, mais que le membre lpLocalName de la structure NETRESOURCE pointée par le paramètre lpNetResource n’a pas été spécifié. |
|
Un paramètre est incorrect. Cette erreur est retournée si le membre dwType |
|
Le mot de passe spécifié n’est pas valide et l’indicateur CONNECT_INTERACTIVE n’est pas défini. |
|
Échec d’ouverture de session en raison d’un nom d’utilisateur inconnu ou d’un mot de passe incorrect. |
|
Aucun fournisseur réseau n’a accepté le chemin d’accès réseau donné. Cette erreur est retournée si aucun fournisseur réseau n’a reconnu le membre |
|
Le réseau n’est pas disponible. |
|
Utilisez formatMessage pour obtenir la chaîne de message pour l’erreur retournée. |
Remarques
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 d’ouverture de session, car les appareils MS-DOS sont identifiés par AuthenticationID (a
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. L’appel à la fonction GetLogicalDrives ne retourne pas de 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 Terminal Services. 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 WNetAddConnection2, 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 par le paramètre lpNetResource peut contenir une adresse IPv4 en notation pointillée décimale. Un exemple de partage peut être le suivant :
\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é afin que l’adresse IPv6 soit analysée correctement. Une adresse littérale IPv6 est de 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 de 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 la lpRemoteName membre de la structure NETRESOURCE pointée par le paramètre lpNetResource qui contient une adresse IPv4 ou IPv6, mais il s’agit d’un fournisseur réseau spécifique.
Exemples
L’exemple de code suivant montre comment utiliser la fonction WNetAddConnection2 pour établir une connexion à une ressource réseau.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
// Need to link with Netapi32.lib and Mpr.lib
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
NETRESOURCE nr;
DWORD dwFlags;
if (argc != 5) {
wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
argv[0]);
wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",
argv[0]);
exit(1);
}
wprintf(L"Calling WNetAddConnection2 with\n");
wprintf(L" lpLocalName = %s\n", argv[1]);
wprintf(L" lpRemoteName = %s\n", argv[2]);
wprintf(L" lpUsername = %s\n", argv[3]);
wprintf(L" lpPassword = %s\n", argv[4]);
// Zero out the NETRESOURCE struct
memset(&nr, 0, sizeof (NETRESOURCE));
// Assign our values to the NETRESOURCE structure.
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];
nr.lpRemoteName = argv[2];
nr.lpProvider = NULL;
// Assign a value to the connection options
dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
// a drive letter to the share.
//
dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
// print the error.
//
if (dwRetVal == NO_ERROR)
wprintf(L"Connection added to %s\n", nr.lpRemoteName);
else
wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);
exit(1);
}
Pour obtenir d’autres exemples de code illustrant comment établir une connexion à une ressource réseau à l’aide de la fonction WNetAddConnection2, consultez Ajout d’une connexion réseau et Affectation d’un lecteur à un partage.
Note
L’en-tête winnetwk.h définit WNetAddConnection2 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 |
Voir aussi
Vue d’ensemble mise en réseau Windows (WNet)