Fonction WNetGetUniversalNameA (winnetwk.h)
La fonction WNetGetUniversalName prend un chemin d’accès basé sur un lecteur pour une ressource réseau et retourne une structure d’informations qui contient une forme plus universelle du nom.
Syntaxe
DWORD WNetGetUniversalNameA(
[in] LPCSTR lpLocalPath,
[in] DWORD dwInfoLevel,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpBufferSize
);
Paramètres
[in] lpLocalPath
Pointeur vers une chaîne null constante qui est un chemin d’accès basé sur un lecteur pour une ressource réseau.
Par exemple, si le lecteur H a été mappé à un partage de lecteur réseau et que la ressource réseau intéressante est un fichier nommé Sample.doc dans le répertoire \Win32\Examples sur ce partage, le chemin d’accès basé sur le lecteur est H:\Win32\Examples\Sample.doc.
[in] dwInfoLevel
Type de structure que la fonction stocke dans la mémoire tampon pointée par le paramètre lpBuffer . Ce paramètre peut être l’une des valeurs suivantes définies dans le fichier d’en-tête Winnetwk.h .
| Valeur | Signification |
|---|---|
|
La fonction stocke une structure UNIVERSAL_NAME_INFO dans la mémoire tampon. |
|
La fonction stocke une structure REMOTE_NAME_INFO dans la mémoire tampon. |
La structure UNIVERSAL_NAME_INFO pointe vers une chaîne de nom UNC (Universal Naming Convention).
La structure REMOTE_NAME_INFO pointe vers une chaîne de nom UNC et deux chaînes d’informations de connexion supplémentaires. Pour plus d'informations, consultez la section Notes qui suit.
[out] lpBuffer
Pointeur vers une mémoire tampon qui reçoit la structure spécifiée par le paramètre dwInfoLevel .
[in, out] lpBufferSize
Pointeur vers une variable qui spécifie la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre lpBuffer .
Si la fonction réussit, elle définit la variable pointée vers lpBufferSize sur le nombre d’octets stockés dans la mémoire tampon. Si la fonction échoue parce que la mémoire tampon est trop petite, cet emplacement reçoit la taille de mémoire tampon requise et la fonction retourne ERROR_MORE_DATA.
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 |
|---|---|
|
La chaîne pointée vers le paramètre lpLocalPath n’est pas valide. |
|
Il n’existe aucune connexion actuelle à l’appareil distant, mais il existe une connexion mémorisées (persistante). |
|
Une erreur spécifique au réseau s’est produite. Utilisez la fonction WNetGetLastError pour obtenir une description de l’erreur. |
|
La mémoire tampon pointée vers le paramètre lpBuffer est trop petite. La fonction définit la variable pointée vers le paramètre lpBufferSize sur la taille de mémoire tampon requise. D’autres entrées sont disponibles avec les appels suivants. |
|
Le paramètre dwInfoLevel a la valeur UNIVERSAL_NAME_INFO_LEVEL, mais le fournisseur réseau ne prend pas en charge les noms UNC. (Aucun des fournisseurs réseau ne prend en charge cette fonction.) |
|
Aucun des fournisseurs réseau 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. |
|
Le réseau n'est pas disponible. |
|
L’appareil spécifié par le paramètre lpLocalPath n’est pas redirigé. |
Remarques
Une forme universelle d’un chemin d’accès basé sur un lecteur local identifie une ressource réseau de manière non ambiguë et indépendante de l’ordinateur. Le nom peut ensuite être transmis aux processus sur d’autres ordinateurs, ce qui permet à ces processus d’obtenir l’accès à la ressource.
La fonction WNetGetUniversalName prend actuellement en charge une forme de nom universel : les noms UNC (Universal Naming Convention), qui se présentent comme suit :
\\servername\sharename\path\file
À l’aide de l’exemple de la description précédente du paramètre lpLocalPath , si le lecteur réseau partagé se trouve sur un serveur nommé COOLSERVER et que le nom du partage est HOTSHARE, le nom UNC de la ressource réseau dont le nom de lecteur est H:\Win32\Examples\Sample.doc est le suivant :
\\coolserver\hotshare\win32\examples\sample.doc
La structure UNIVERSAL_NAME_INFO contient un pointeur vers une chaîne de nom UNC. La structure REMOTE_NAME_INFO contient également un pointeur vers une chaîne de nom UNC, ainsi que des pointeurs vers deux autres chaînes utiles. Par exemple, un processus peut passer le membre lpszConnectionInfo de la structure REMOTE_NAME_INFO à la fonction WNetAddConnection2 pour connecter un appareil local à la ressource réseau. Ensuite, le processus peut ajouter la chaîne pointée par le membre lpszRemainingPath à la chaîne d’appareil locale. La chaîne résultante peut être transmise aux fonctions qui nécessitent un chemin d’accès basé sur un lecteur.
Le paramètre lpLocalPath n’a pas besoin de spécifier un chemin d’accès ou une ressource déjà présent sur une ressource distante. Par exemple, le paramètre lpLocalPath peut spécifier et dossier, une hiérarchie de dossiers ou un fichier qui n’existe pas actuellement. La fonction WNetGetUniversalName retourne une forme plus universelle du nom dans ces cas.
La taille de la mémoire tampon pointée vers le paramètre lpBuffer et spécifiée dans le paramètre lpBufferSize doit être beaucoup plus grande que la taille des structures REMOTE_NAME_INFO ou UNIVERSAL_NAME_INFO . La mémoire tampon pointée vers le paramètre lpBuffer doit être suffisamment grande pour stocker les chaînes UNC pointées par les membres dans les structures REMOTE_NAME_INFO ou UNIVERSAL_NAME_INFO . Si la taille de la mémoire tampon est trop petite, la fonction échoue avec ERROR_MORE_DATA et la variable pointée vers le paramètre lpBufferSize indique la taille de mémoire tampon requise.
Windows Server 2003 et Windows XP : Cette fonction interroge les espaces de noms d’appareil 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 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 . 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
L’exemple de code suivant montre comment utiliser la fonction WNetGetUniversalName pour récupérer les chaînes de nom UNC universelles associées au chemin d’accès basé sur le lecteur pour 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>
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
WCHAR Buffer[1024];
DWORD dwBufferLength = 1024;
UNIVERSAL_NAME_INFO * unameinfo;
REMOTE_NAME_INFO *remotenameinfo;
wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);
unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,
(LPVOID) remotenameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
}
Notes
L’en-tête winnetwk.h définit WNetGetUniversalName 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
| 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
Détermination de l’emplacement d’un partage
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour