Funzione WNetGetUniversalNameA (winnetwk.h)

Articolo
11/20/2024

La funzione WNetGetUniversalName accetta un percorso basato su unità per una risorsa di rete e restituisce una struttura di informazioni che contiene una forma più universale del nome.

Sintassi

DWORD WNetGetUniversalNameA(
  [in]      LPCSTR  lpLocalPath,
  [in]      DWORD   dwInfoLevel,
  [out]     LPVOID  lpBuffer,
  [in, out] LPDWORD lpBufferSize
);

Parametri

[in] lpLocalPath

Puntatore a una stringa con terminazione Null costante che rappresenta un percorso basato su unità per una risorsa di rete.

Ad esempio, se l'unità H è stata mappata a una condivisione di unità di rete e la risorsa di rete di interesse è un file denominato Sample.doc nella directory \Win32\Examples in tale condivisione, il percorso basato su unità è H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

Tipo di struttura archiviato dalla funzione nel buffer a cui punta il parametro lpBuffer . Questo parametro può essere uno dei valori seguenti definiti nel file di intestazione Winnetwk.h.

Valore	Significato
UNIVERSAL_NAME_INFO_LEVEL	La funzione archivia una struttura UNIVERSAL_NAME_INFO nel buffer.
REMOTE_NAME_INFO_LEVEL	La funzione archivia una struttura REMOTE_NAME_INFO nel buffer.

La struttura UNIVERSAL_NAME_INFO punta a una stringa di nome UNC (Universal Naming Convention).

La struttura REMOTE_NAME_INFO punta a una stringa di nome UNC e due stringhe di informazioni di connessione aggiuntive. Per altre informazioni, vedere la sezione Osservazioni seguente.

[out] lpBuffer

Puntatore a un buffer che riceve la struttura specificata dal parametro dwInfoLevel.

[in, out] lpBufferSize

Puntatore a una variabile che specifica le dimensioni, in byte, del buffer a cui punta il parametro lpBuffer .

Se la funzione ha esito positivo, imposta la variabile a cui punta lpBufferSize sul numero di byte archiviati nel buffer. Se la funzione ha esito negativo perché il buffer è troppo piccolo, questa posizione riceve le dimensioni del buffer necessarie e la funzione restituisce ERROR_MORE_DATA.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema , ad esempio uno dei valori seguenti.

Codice restituito	Descrizione
ERROR_BAD_DEVICE	La stringa a cui punta il parametro lpLocalPath non è valida.
ERROR_CONNECTION_UNAVAIL	Non esiste una connessione corrente al dispositivo remoto, ma è presente una connessione memorizzata (persistente).
ERROR_EXTENDED_ERROR	Si è verificato un errore specifico della rete. Usare la funzione WNetGetLastError per ottenere una descrizione dell'errore.
ERROR_MORE_DATA	Il buffer a cui punta il parametro lpBuffer è troppo piccolo. La funzione imposta la variabile a cui punta il parametro lpBufferSize sulla dimensione del buffer richiesta. Sono disponibili altre voci con le chiamate successive.
ERROR_NOT_SUPPORTED	Il parametro dwInfoLevel è impostato su UNIVERSAL_NAME_INFO_LEVEL, ma il provider di rete non supporta i nomi UNC. Nessuno dei provider di rete supporta questa funzione.
ERROR_NO_NET_OR_BAD_PATH	Nessuno dei provider di rete riconosce il nome locale come avere una connessione. Tuttavia, la rete non è disponibile per almeno un provider a cui può appartenere la connessione.
ERROR_NO_NETWORK	La rete non è disponibile.
ERROR_NOT_CONNECTED	Il dispositivo specificato dal parametro lpLocalPath non viene reindirizzato.

Osservazioni

Una forma universale di un percorso locale basato su unità identifica una risorsa di rete in modo non ambiguo e indipendente dal computer. Il nome può quindi essere passato ai processi in altri computer, consentendo a tali processi di ottenere l'accesso alla risorsa.

La funzione WNetGetUniversalName supporta attualmente un formato di nome universale: nomi UNC (Universal Naming Convention), simili ai seguenti:

\\servername\sharename\path\file

Usando l'esempio della descrizione precedente del parametro lpLocalPath, se l'unità di rete condivisa si trova in un server denominato COOLSERVER e il nome della condivisione è HOTSHARE, il nome UNC per la risorsa di rete il cui nome basato su unità è H:\Win32\Examples\Sample.doc sarà il seguente:

\\coolserver\hotshare\win32\examples\sample.doc

La struttura UNIVERSAL_NAME_INFO contiene un puntatore a una stringa di nome UNC. La struttura REMOTE_NAME_INFO contiene anche un puntatore a una stringa di nome UNC, nonché puntatori a due altre stringhe utili. Ad esempio, un processo può passare il membro lpszConnectionInfo della struttura REMOTE_NAME_INFO alla funzione WNetAddConnection2 per connettere un dispositivo locale alla risorsa di rete. Il processo può quindi aggiungere la stringa a cui punta il membro lpszRemainingPath alla stringa del dispositivo locale. La stringa risultante può essere passata alle funzioni che richiedono un percorso basato su unità.

Il parametro lpLocalPath non deve specificare un percorso o una risorsa già presente in una risorsa remota. Ad esempio, il parametro lpLocalPath potrebbe specificare e cartella, una gerarchia di cartelle o un file attualmente non esistente. La funzione WNetGetUniversalName restituisce una forma più universale del nome in questi casi.

Le dimensioni del buffer a cui punta il parametro lpBuffer e specificate nel parametro lpBufferSize devono essere molto più grandi delle dimensioni delle strutture REMOTE_NAME_INFO o UNIVERSAL_NAME_INFO. Il buffer a cui punta il parametro lpBuffer deve essere sufficientemente grande per archiviare le stringhe UNC a cui puntano i membri nelle strutture REMOTE_NAME_INFO o UNIVERSAL_NAME_INFO. Se la dimensione del buffer è troppo piccola, la funzione ha esito negativo con ERROR_MORE_DATA e la variabile a cui punta il parametro lpBufferSize indica le dimensioni del buffer necessarie.

Windows Server 2003 e Windows XP: Questa funzione esegue una query sugli spazi dei nomi dei dispositivi MS-DOS associati a una sessione di accesso perché i dispositivi MS-DOS sono identificati da AuthenticationID. AuthenticationID è l'identificatore univoco locale o LUID associato a una sessione di accesso. Ciò può influire sulle applicazioni che chiamano una delle funzioni WNet per creare una lettera di unità di rete con un accesso utente, ma eseguire una query per le lettere di unità di rete esistenti con un accesso utente diverso. Un esempio di questa situazione può essere quando viene creato il secondo accesso di un utente all'interno di una sessione di accesso, ad esempio chiamando la funzione CreateProcessAsUser e il secondo accesso esegue un'applicazione che chiama la funzione GetLogicalDrives. getLogicalDrives non restituisce lettere di unità di rete create da una funzione WNet sotto il primo accesso. Si noti che nell'esempio precedente la prima sessione di accesso esiste ancora e l'esempio può essere applicato a qualsiasi sessione di accesso, inclusa una sessione di Servizi terminal. Per altre informazioni, vedere Definizione di un nome di dispositivo MS-DOS.

Esempi

L'esempio di codice seguente illustra come usare la funzione WNetGetUniversalName per recuperare le stringhe dei nomi UNC universali associate al percorso basato su unità per una risorsa di rete.

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

Nota

L'intestazione winnetwk.h definisce WNetGetUniversalName come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winnetwk.h
libreria	Mpr.lib
dll	Mpr.dll