Funzione WNetAddConnection2A (winnetwk.h)

La funzione WNetAddConnection2 stabilisce una connessione a una risorsa di rete e può reindirizzare un dispositivo locale alla risorsa di rete.

La funzione WNetAddConnection2 sostituisce la funzione WNetAddConnection . Se è possibile passare un handle a una finestra che il provider di risorse di rete può usare come finestra di proprietario per le finestre di dialogo, chiamare invece la funzione WNetAddConnection3 .

Sintassi

DWORD WNetAddConnection2A(
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Parametri

[in] lpNetResource

Puntatore a una struttura NETRESOURCE che specifica i dettagli della connessione proposta, ad esempio informazioni sulla risorsa di rete, sul dispositivo locale e sul provider di risorse di rete.

È necessario specificare i membri seguenti della struttura NETRESOURCE .

Membro Significato
dwType
Tipo di risorsa di rete a cui connettersi.

Se il membro lpLocalName punta a una stringa nonempty, questo membro può essere uguale a RESOURCETYPE_DISK o RESOURCETYPE_PRINT.

Se lpLocalName è NULL o se punta a una stringa vuota, dwType può essere uguale a RESOURCETYPE_DISK, RESOURCETYPE_PRINT o RESOURCETYPE_ANY.

Anche se questo membro è obbligatorio, le relative informazioni possono essere ignorate dal provider di servizi di rete.

lpLocalName
Puntatore a una stringa con terminazione Null che specifica il nome di un dispositivo locale da reindirizzare, ad esempio "F:" o "LPT1". La stringa viene trattata senza distinzione tra maiuscole e minuscole.

Se la stringa è vuota o se lpLocalName è NULL, la funzione stabilisce una connessione alla risorsa di rete senza reindirizzare un dispositivo locale.

lpRemoteName
Puntatore a una stringa con terminazione Null che specifica la risorsa di rete a cui connettersi. La stringa può contenere fino a MAX_PATH caratteri e deve seguire le convenzioni di denominazione del provider di rete.
lpProvider
Puntatore a una stringa con terminazione Null che specifica il provider di rete a cui connettersi.

Se lpProvider è NULL o se punta a una stringa vuota, il sistema operativo tenta di determinare il provider corretto analizzando la stringa a cui punta il membro lpRemoteName .

Se questo membro non è NULL, il sistema operativo tenta di stabilire una connessione solo al provider di rete denominato.

È consigliabile impostare questo membro solo se si conosce il provider di rete che si vuole usare. In caso contrario, consentire al sistema operativo di determinare il provider a cui viene mappato il nome di rete.

 

La funzione WNetAddConnection2 ignora gli altri membri della struttura NETRESOURCE .

[in] lpPassword

Puntatore a una stringa costante con terminazione Null che specifica una password da usare per stabilire la connessione di rete.

Se lpPassword è NULL, la funzione utilizza la password predefinita corrente associata all'utente specificato dal parametro lpUserName .

Se lpPassword punta a una stringa vuota, la funzione non usa una password.

Se la connessione non riesce a causa di una password non valida e il valore di CONNECT_INTERACTIVE è impostato nel parametro dwFlags , la funzione visualizza una finestra di dialogo che chiede all'utente di digitare la password.

Windows Me/98/95: Questo parametro deve essere NULL o una stringa vuota.

[in] lpUserName

Puntatore a una stringa costante con terminazione Null che specifica un nome utente per stabilire la connessione.

Se lpUserName è NULL, la funzione usa il nome utente predefinito. Il contesto utente per il processo fornisce il nome utente predefinito.

Il parametro lpUserName viene specificato quando gli utenti vogliono connettersi a una risorsa di rete a cui sono stati assegnati un nome utente o un account diverso dal nome utente o dall'account predefinito.

La stringa user-name rappresenta un contesto di sicurezza. Può essere specifico di un provider di rete.

Windows Me/98/95: Questo parametro deve essere NULL o una stringa vuota.

[in] dwFlags

Set di opzioni di connessione. I valori possibili per le opzioni di connessione sono definiti nel file di intestazione Winnetwk.h . Attualmente è possibile usare i valori seguenti.

Valore Significato
CONNECT_UPDATE_PROFILE
0x00000001
La connessione alla risorsa di rete deve essere memorizzata.

Se questo flag di bit è impostato, il sistema operativo tenta automaticamente di ripristinare la connessione quando l'utente accede.

Il sistema operativo ricorda solo le connessioni riuscite che reindirizzano i dispositivi locali. Non ricorda le connessioni non riuscite o senza dispositivo. Si verifica una connessione senza dispositivo quando il membro lpLocalName è NULL o punta a una stringa vuota.

Se questo flag di bit è chiaro, il sistema operativo non tenta di ripristinare la connessione quando l'utente accede.

CONNECT_UPDATE_RECENT
0x00000002
La connessione alla risorsa di rete non deve essere inserita nell'elenco delle connessioni recenti.

Se questo flag è impostato e la connessione viene aggiunta correttamente, la connessione alla risorsa di rete verrà inserita nell'elenco delle connessioni recenti solo se è associato un dispositivo locale reindirizzato.

CONNECT_TEMPORARY
0x00000004
La connessione alla risorsa di rete non deve essere memorizzata.

Se questo flag è impostato, il sistema operativo non tenterà di ripristinare la connessione quando l'utente accede di nuovo.

CONNECT_INTERACTIVE
0x00000008
Se questo flag è impostato, il sistema operativo può interagire con l'utente a scopo di autenticazione.
CONNECT_PROMPT
0x00000010
Questo flag indica al sistema di non usare impostazioni predefinite per nomi utente o password senza offrire all'utente la possibilità di fornire un'alternativa. Questo flag viene ignorato a meno che non sia impostato anche CONNECT_INTERACTIVE.
CONNECT_REDIRECT
0x00000080
Questo flag forza il reindirizzamento di un dispositivo locale quando si effettua la connessione.

Se il membro lpLocalName di NETRESOURCE specifica un dispositivo locale da reindirizzare, questo flag non ha alcun effetto, perché il sistema operativo tenta comunque di reindirizzare il dispositivo specificato. Quando il sistema operativo sceglie automaticamente un dispositivo locale, il membro dwType non deve essere uguale a RESOURCETYPE_ANY.

Se questo flag non è impostato, viene scelto automaticamente un dispositivo locale per il reindirizzamento solo se la rete richiede il reindirizzamento di un dispositivo locale.

Windows Server 2003 e Windows XP: Quando il sistema assegna automaticamente lettere di unità di rete, le lettere vengono assegnate a partire da Z:, quindi Y:, e terminano con C:. Ciò riduce la collisione tra lettere di unità per accesso (ad esempio lettere di unità di rete) e lettere di unità globali (ad esempio unità disco). Si noti che le versioni precedenti delle lettere di unità assegnate da Windows iniziano con C: e terminano con Z:.

CONNECT_CURRENT_MEDIA
0x00000200
Se questo flag è impostato, il sistema operativo non inizia a usare un nuovo supporto per tentare di stabilire la connessione (ad esempio, avviare una nuova connessione remota).
CONNECT_COMMANDLINE
0x00000800
Se questo flag è impostato, il sistema operativo richiede all'utente l'autenticazione usando la riga di comando anziché un'interfaccia utente grafica (GUI). Questo flag viene ignorato a meno che non sia impostato anche CONNECT_INTERACTIVE.

Windows XP: Questo valore è supportato in Windows XP e versioni successive.

CONNECT_CMD_SAVECRED
0x00001000
Se questo flag è impostato e il sistema operativo richiede una credenziale, le credenziali devono essere salvate dal gestore delle credenziali. Se gestione credenziali è disabilitato per la sessione di accesso del chiamante o se il provider di rete non supporta il salvataggio delle credenziali, questo flag viene ignorato. Questo flag viene ignorato a meno che non sia impostato anche CONNECT_INTERACTIVE. Questo flag viene ignorato anche a meno che non si imposti il flag CONNECT_COMMANDLINE.

Windows XP: Questo valore è supportato in Windows XP e versioni successive.

CONNECT_CRED_RESET
0x00002000
Se questo flag è impostato e il sistema operativo richiede una credenziale, la credenziale viene reimpostata dal gestore delle credenziali. Se la gestione credenziali è disabilitata per la sessione di accesso del chiamante o se il provider di rete non supporta il salvataggio delle credenziali, questo flag viene ignorato. Questo flag viene ignorato anche a meno che non si imposta il flag di CONNECT_COMMANDLINE.

Windows Vista: Questo valore è supportato in Windows Vista e versioni successive.

Valore restituito

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

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti o uno dei codici di errore di sistema.

Codice restituito Descrizione
ERROR_ACCESS_DENIED
Il chiamante non ha accesso alla risorsa di rete.
ERROR_ALREADY_ASSIGNED
Il dispositivo locale specificato dal membro lpLocalName è già connesso a una risorsa di rete.
ERROR_BAD_DEV_TYPE
Il tipo di dispositivo locale e il tipo di risorsa di rete non corrispondono.
ERROR_BAD_DEVICE
Il nome del dispositivo specificato non è valido. Questo errore viene restituito se il membro lpLocalName della struttura NETRESOURCE puntato al parametro lpNetResource specifica un dispositivo non reindirizzabile.
ERROR_BAD_NET_NAME
Impossibile trovare il nome della rete. Questo valore viene restituito se il membro lpRemoteName della struttura NETRESOURCE puntato al parametro lpNetResource specifica una risorsa non accettabile per qualsiasi provider di risorse di rete, perché il nome della risorsa è vuoto, non valido o perché la risorsa denominata non può essere posizionata.
ERROR_BAD_PROFILE
Il profilo utente è in formato non corretto.
ERROR_BAD_PROVIDER
Il nome del provider di rete specificato non è valido. Questo errore viene restituito se il membro lpProvider della struttura NETRESOURCE puntato al parametro lpNetResource specifica un valore che non corrisponde a alcun provider di rete.
ERROR_BAD_USERNAME
Il nome utente specificato non è valido.
ERROR_BUSY
Il router o il provider è occupato, possibilmente inizializzando. Il chiamante deve riprovare.
ERROR_CANCELLED
Il tentativo di effettuare la connessione è stato annullato dall'utente tramite una finestra di dialogo da uno dei provider di risorse di rete o da una risorsa chiamata.
ERROR_CANNOT_OPEN_PROFILE
Il sistema non è in grado di aprire il profilo utente per elaborare connessioni persistenti.
ERROR_DEVICE_ALREADY_REMEMBERED
Il nome del dispositivo locale ha una connessione ricordata a un'altra risorsa di rete. Questo errore viene restituito se una voce del dispositivo specificata dal membro lpLocalName della struttura NETRESOURCE puntata al parametro lpNetResource specifica un valore già presente nel profilo utente per una connessione diversa da quella specificata nel parametro lpNetResource .
ERROR_EXTENDED_ERROR
Si è verificato un errore specifico della rete. Chiamare la funzione WNetGetLastError per ottenere una descrizione dell'errore.
ERROR_INVALID_ADDRESS
È stato eseguito un tentativo di accesso a un indirizzo non valido. Questo errore viene restituito se il parametro dwFlags specifica un valore di CONNECT_REDIRECT, ma il membro lpLocalName della struttura NETRESOURCE puntato al parametro lpNetResource non è stato specificato.
ERROR_INVALID_PARAMETER
Un parametro non è corretto. Questo errore viene restituito se il membro dwType della struttura NETRESOURCE puntato al parametro lpNetResource specifica un valore diverso da RESOURCETYPE_DISK, RESOURCETYPE_PRINT o RESOURCETYPE_ANY. Questo errore viene restituito anche se il parametro dwFlags specifica un valore non corretto o sconosciuto.
ERROR_INVALID_PASSWORD
La password specificata non è valida e il flag di CONNECT_INTERACTIVE non è impostato.
ERROR_LOGON_FAILURE
Errore di accesso a causa di un nome utente sconosciuto o di una password non valida.
ERROR_NO_NET_OR_BAD_PATH
Nessun provider di rete ha accettato il percorso di rete specificato. Questo errore viene restituito se nessun provider di rete ha riconosciuto il membro lpRemoteName della struttura NETRESOURCE a cui fa riferimento il parametro lpNetResource .
ERROR_NO_NETWORK
La rete non è disponibile.
Altri
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

In Windows Server 2003 e Windows XP le funzioni WNet creano ed eliminano le lettere di unità di rete nello spazio dei nomi dei dispositivi MS-DOS associate a una sessione di accesso perché i dispositivi MS-DOS sono identificati da AuthenticationID (un
identificatore univoco locale o LUID associato a una sessione di accesso. Ciò può influire sulle applicazioni che chiamano una delle funzioni di rete per creare una lettera di unità di rete con un accesso utente, ma eseguire una query sulle lettere di unità di rete esistenti con un accesso utente diverso. Un esempio di questa situazione potrebbe essere quando il secondo accesso di un utente viene creato 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 . La chiamata alla funzione GetLogicalDrives non restituisce lettere di unità di rete create dalle chiamate di 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 del dispositivo MS-DOS.

In Windows Server 2003 e Windows XP, se un servizio che viene eseguito come LocalSystem chiama la funzione WNetAddConnection2 , l'unità mappata è visibile a tutte le sessioni di accesso utente.

Per i provider di rete Microsoft, il membro lpRemoteName della struttura NETRESOURCE a cui punta il parametro lpNetResource può contenere un indirizzo IPv4 nella notazione decimale punteggiata. Un esempio per una condivisione potrebbe essere il seguente:

\192.168.1.1\share

Per i provider di rete Microsoft in Windows Vista e versioni successive, il membro lpRemoteName della struttura NETRESOURCE a cui punta il parametro lpNetResource può contenere un indirizzo IPv6. Tuttavia, il formato letterale IPv6 deve essere usato in modo che l'indirizzo IPv6 venga analizzato correttamente. Un indirizzo letterale IPv6 è del modulo:

indirizzo ipv6 con i caratteri ':' sostituiti da caratteri '-' seguiti dalla stringa ".ipv6-literal.net".

Ad esempio, per l'indirizzo IPv6 seguente:

2001:4898:9:3:c069:aa97:fe76:2449

un esempio per una condivisione potrebbe essere il seguente:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Altri provider di rete possono supportare il membro lpRemoteName della struttura NETRESOURCE a cui punta il parametro lpNetResource che contiene un indirizzo IPv4 o IPv6, ma si tratta di un provider di rete specifico.

Windows 7 e Windows Server 2008 R2: Se la funzione WNetAddConnection2 viene chiamata con credenziali utente esplicite specificate nel pUsername e lpPassword per stabilire una connessione con una risorsa di rete in un server specifico e quindi chiamata nuovamente con uno di questi parametri come NULL (per usare il nome utente predefinito o la password predefinita) allo stesso server, la chiamata con esito negativo. L'errore restituito verrà ERROR_BAD_USERNAME o ERROR_INVALID_PASSWORD.

Esempio

L'esempio di codice seguente illustra come usare la funzione WNetAddConnection2 per creare la connessione a 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>

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


Per altri esempi di codice che illustrano come creare una connessione a una risorsa di rete usando la funzione WNetAddConnection2 , vedere Aggiunta di una connessione di rete e assegnazione di un'unità a una condivisione.

Nota

L'intestazione winnetwk.h definisce WNetAddConnection2 come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

   
Client minimo supportato Windows 2000 Professional [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione winnetwk.h
Libreria Mpr.lib
DLL Mpr.dll

Vedi anche

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Panoramica di Rete Windows (WNet)

Funzioni di rete Windows