WNetGetUniversalNameA, fonction (winnetwk.h)

Article
11/20/2024

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 constante terminée par null 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 lecteurs réseau et que la ressource réseau d’intérêt 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
UNIVERSAL_NAME_INFO_LEVEL	La fonction stocke une structure UNIVERSAL_NAME_INFO dans la mémoire tampon.
REMOTE_NAME_INFO_LEVEL	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 Remarques suivante.

[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 pointée par le paramètre lpBuffer.

Si la fonction réussit, elle définit la variable pointée par lpBufferSize le nombre d’octets stockés dans la mémoire tampon. Si la fonction échoue, car la mémoire tampon est trop petite, cet emplacement reçoit la taille de la mémoire tampon requise et la fonction retourne ERROR_MORE_DATA.

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 lpLocalPath n’est pas valide.
ERROR_CONNECTION_UNAVAIL	Il n’existe aucune connexion actuelle à l’appareil distant, mais il y a une connexion mémorisé (persistante) à celle-ci.
ERROR_EXTENDED_ERROR	Une erreur spécifique au réseau s’est produite. Utilisez la fonction WNetGetLastError pour obtenir une description de l’erreur.
ERROR_MORE_DATA	La mémoire tampon pointée par le paramètre lpBuffer est trop petite. La fonction définit la variable pointée par le paramètre lpBufferSize sur la taille de mémoire tampon requise. D’autres entrées sont disponibles avec les appels suivants.
ERROR_NOT_SUPPORTED	Le paramètre dwInfoLevel est défini sur UNIVERSAL_NAME_INFO_LEVEL, mais le fournisseur de réseau ne prend pas en charge les noms UNC. (Aucun des fournisseurs de réseau ne prend en charge cette fonction.)
ERROR_NO_NET_OR_BAD_PATH	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.
ERROR_NO_NETWORK	Le réseau n’est pas disponible.
ERROR_NOT_CONNECTED	L’appareil spécifié par le paramètre lpLocalPath n’est pas redirigé.

Remarques

Une forme universelle d’un chemin d’accès local basé sur un lecteur 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 un formulaire de nom universel : les noms UNC (Universal Naming Convention), qui ressemblent à ce qui 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 basé sur le lecteur est H:\Win32\Examples\Sample.doc serait 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 transmettre 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 l'lpszRemainingPath membre à la chaîne d’appareil local. 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 par 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 par 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 par 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’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

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);
    }
}

Note

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