WNetUseConnectionA, fonction (winnetwk.h)

Article
03/08/2023

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

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

Syntaxe

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Paramètres

[in] hwndOwner

Gérez vers 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.

[in] lpNetResource

Pointeur vers une structure NETRESOURCE qui spécifie les détails de la connexion proposée. La structure contient 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	Spécifie le type de ressource auquel se connecter. Il est plus efficace de spécifier un type de ressource dans ce membre, tel que RESOURCETYPE_DISK ou RESOURCETYPE_PRINT. Toutefois, si le membre lpLocalName est NULL, ou s’il pointe vers une chaîne vide et CONNECT_REDIRECT n’est pas défini, dwType peut être RESOURCETYPE_ANY. Cette méthode fonctionne uniquement si la fonction ne choisit pas automatiquement un appareil pour rediriger vers la ressource réseau. Bien que ce membre soit requis, ses informations peuvent être ignorées par le fournisseur de services réseau.
lpLocalName	Pointeur vers une chaîne null-terminated qui spécifie le nom d’un appareil local à rediriger, tel que « F : » ou « LPT1 ». La chaîne est traitée de manière non sensible à la casse. Si la chaîne est vide ou si lpLocalName est NULL, une connexion au réseau se produit sans redirection. Si la valeur CONNECT_REDIRECT est définie dans le paramètre dwFlags ou si le réseau nécessite un appareil local redirigé, la fonction choisit un appareil local pour rediriger et retourne le nom de l’appareil dans le paramètre lpAccessName.
lpRemoteName	Pointeur vers une chaîne null-terminated qui spécifie la ressource réseau à laquelle se connecter. La chaîne peut être jusqu’à MAX_PATH caractères de longueur, et elle doit suivre les conventions d’affectation de noms du fournisseur de réseau.
lpProvider	Pointeur vers une chaîne null-terminated qui spécifie le fournisseur de réseau auquel se connecter. Si lpProvider est NULL ou s’il pointe vers une chaîne vide, le système d’exploitation tente de déterminer le fournisseur approprié en analysant la chaîne pointée par le membre lpRemoteName. Si ce membre n’est pas NULL, le système d’exploitation tente d’établir une connexion uniquement au fournisseur de réseau nommé. Vous devez définir ce membre uniquement si vous connaissez le fournisseur réseau que vous souhaitez utiliser. Sinon, laissez le système d’exploitation déterminer le fournisseur auquel le nom du réseau est mappé.

La fonction WNetUseConnection ignore les autres membres de la structure NETRESOURCE. Pour plus d’informations, consultez les descriptions suivantes pour le paramètre dwFlags.

[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 lpUserID.

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.

[in] lpUserId

Pointeur vers une constante chaîne null-terminated qui spécifie un nom d’utilisateur pour établir la connexion.

Si lpUserID 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 lpUserID 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.

[in] dwFlags

Ensemble d’indicateurs de bits décrivant la connexion. Ce paramètre peut être n’importe quelle combinaison des valeurs suivantes.

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 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 XP : Lorsque le système affecte automatiquement des lettres de lecteur réseau, les lettres sont attribuées à partir de Z :, puis Y :, et se terminant 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 précédentes ont attribué des lettres de lecteur commençant par C : et se terminant par Z :.
CONNECT_UPDATE_PROFILE	Cet indicateur indique au système d’exploitation de stocker la connexion de ressource réseau. 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 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 quand lpLocalName est NULL ou lorsqu’elle pointe vers une chaîne vide.) Si cet indicateur de bits est clair, le système d’exploitation ne restaure pas automatiquement la connexion au niveau de l’ouverture de session.
CONNECT_COMMANDLINE	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 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.

[out] lpAccessName

Pointeur vers une mémoire tampon qui reçoit les demandes système sur la connexion. Ce paramètre peut être NULL.

Si ce paramètre est spécifié et que le lpLocalName membre de la structure NETRESOURCE spécifie un appareil local, cette mémoire tampon reçoit le nom de l’appareil local. Si lpLocalName ne spécifie pas d’appareil et que le réseau nécessite une redirection d’appareil local, ou si la valeur CONNECT_REDIRECT est définie, cette mémoire tampon reçoit le nom de l’appareil local redirigé.

Sinon, le nom copié dans la mémoire tampon est celui d’une ressource distante. Si elle est spécifiée, cette mémoire tampon doit être au moins aussi grande que la chaîne pointée par le membre lpRemoteName.

[in, out] lpBufferSize

Pointeur vers une variable qui spécifie la taille de la mémoire tampon lpAccessName, en caractères. Si l’appel échoue, car la mémoire tampon n’est pas suffisamment grande, la fonction retourne la taille de mémoire tampon requise à cet emplacement. Pour plus d’informations, consultez les descriptions du paramètre lpAccessName et du code d’erreur ERROR_MORE_DATA dans la section Valeurs renvoyées.

[out] lpResult

Pointeur vers une variable qui reçoit des informations supplémentaires sur la connexion. Ce paramètre peut être la valeur suivante.

Valeur	Signification
CONNECT_LOCALDRIVE	Si cet indicateur est défini, la connexion a été établie à l’aide d’une redirection d’appareil local. Si le paramètre lpAccessName pointe vers une mémoire tampon, le nom de l’appareil local est copié dans la mémoire tampon.

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_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_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 pas acceptable pour un fournisseur de ressources réseau, car le nom de la ressource n’est pas valide ou parce que la ressource nommée ne peut pas être localisée.
ERROR_BAD_PROVIDER	La valeur spécifiée par le membre lpProvider ne correspond à aucun fournisseur.
ERROR_CANCELLED	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.
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_INVALID_ADDRESS	L’appelant a passé un pointeur vers une mémoire tampon qui n’a pas pu être accessible.
ERROR_INVALID_PARAMETER	Cette erreur résulte de l’une des conditions suivantes : Le membre lpRemoteName est NULL. En outre, lpAccessName n’est pas NULL, mais lpBufferSize est NULL ou pointe vers zéro. Le membre dwType n’est ni RESOURCETYPE_DISK ni RESOURCETYPE_PRINT. En outre, CONNECT_REDIRECT est défini dans dwFlags et lpLocalName est NULL, ou la connexion à un réseau qui nécessite la redirection d’un appareil local.
ERROR_INVALID_PASSWORD	Le mot de passe spécifié n’est pas valide et l’indicateur CONNECT_INTERACTIVE n’est pas défini.
ERROR_MORE_DATA	La mémoire tampon lpAccessName est trop petite. Si un appareil local est redirigé, la mémoire tampon doit être suffisamment grande pour contenir le nom de l’appareil local. Sinon, la mémoire tampon doit être suffisamment grande pour contenir la chaîne pointée par lpRemoteName, ou le nom de la ressource pouvant être connectable dont l’alias est pointé par lpRemoteName. Si cette erreur est retournée, aucune connexion n’a été établie.
ERROR_NO_MORE_ITEMS	Le système d’exploitation ne peut pas choisir automatiquement une redirection locale, car tous les appareils locaux valides sont en cours d’utilisation.
ERROR_NO_NET_OR_BAD_PATH	L’opération n’a pas pu être terminée, soit parce qu’un composant réseau n’est pas démarré, soit parce que le nom de ressource spécifié n’est pas reconnu.
ERROR_NO_NETWORK	Le réseau n’est pas disponible.

Remarques

Windows Server 2003 et Windows XP : les fonctions WNet créent et suppriment des lettres de lecteur réseau dans l’espace de noms de l’appareil MS-DOS associé à 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.

Note

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