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
Sintassi
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parametri
[in] lpNetResource
Puntatore a una struttura di 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 di NETRESOURCE
La funzione di WNetAddConnection2
[in] lpPassword
Puntatore a una costante nullstringa con terminazione che specifica una password da usare per stabilire la connessione di rete.
Se lpPassword è NULL, la funzione usa 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 CONNECT_INTERACTIVE viene impostato nel parametro dwFlags
Windows Me/98/95: Questo parametro deve essere NULL o una stringa vuota.
[in] lpUserName
Puntatore a una costante nullstringa con terminazione che specifica un nome utente per 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 per cui sono stati assegnati un nome utente o un account diverso dal nome utente o dall'account predefinito.
La stringa nome utente 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 vengono definiti nel file di intestazione
| Valore | Significato |
|---|---|
|
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 memorizza solo le connessioni riuscite che reindirizzano i dispositivi locali. Non ricorda le connessioni non riuscite o senza dispositivo. Una connessione senza dispositivo si verifica 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. |
|
La connessione alla risorsa di rete non deve essere inserita nell'elenco di connessioni recenti.
Se questo flag è impostato e la connessione viene aggiunta correttamente, la connessione alla risorsa di rete verrà inserita nell'elenco di connessioni recente solo se è associato un dispositivo locale reindirizzato. |
|
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 esegue di nuovo l'accesso. |
|
Se questo flag è impostato, il sistema operativo può interagire con l'utente a scopo di autenticazione. |
|
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. |
|
Questo flag forza il reindirizzamento di un dispositivo locale quando si effettua la connessione.
Se il lpLocalName membro 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 Se questo flag non è impostato, un dispositivo locale viene scelto automaticamente 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:. In questo modo si riduce il conflitto tra lettere di unità per accesso (ad esempio lettere di unità di rete) e lettere di unità globali (ad esempio le unità disco). Si noti che le versioni precedenti delle lettere di unità assegnate da Windows che iniziano con C: e terminano con Z:. |
|
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). |
|
Se questo flag è impostato, il sistema operativo chiede all'utente di eseguire 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. |
|
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 di CONNECT_COMMANDLINE.
Windows XP: Questo valore è supportato in Windows XP e versioni successive. |
|
Se questo flag è impostato e il sistema operativo richiede una credenziale, la credenziale viene reimpostata 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 anche a meno che non si imposti 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 |
|---|---|
|
Il chiamante non ha accesso alla risorsa di rete. |
|
Il dispositivo locale specificato dal membro lpLocalName è già connesso a una risorsa di rete. |
|
Il tipo di dispositivo locale e il tipo di risorsa di rete non corrispondono. |
|
Il nome del dispositivo specificato non è valido. Questo errore viene restituito se il membro |
|
Impossibile trovare il nome di rete. Questo valore viene restituito se il |
|
Il profilo utente è in un formato non corretto. |
|
Il nome del provider di rete specificato non è valido. Questo errore viene restituito se il membro |
|
Il nome utente specificato non è valido. |
|
Il router o il provider è occupato, possibilmente inizializzando. Il chiamante deve riprovare. |
|
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. |
|
Il sistema non è in grado di aprire il profilo utente per elaborare connessioni persistenti. |
|
Il nome del dispositivo locale ha una connessione memorizzata a un'altra risorsa di rete. Questo errore viene restituito se una voce per il dispositivo specificato da |
|
Si è verificato un errore specifico della rete. Chiamare la funzione WNetGetLastError |
|
È stato effettuato un tentativo di accesso a un indirizzo non valido. Questo errore viene restituito se il parametro |
|
Un parametro non è corretto. Questo errore viene restituito se il membro dwType |
|
La password specificata non è valida e il flag CONNECT_INTERACTIVE non è impostato. |
|
Errore di accesso a causa di un nome utente sconosciuto o di una password non valida. |
|
Nessun provider di rete ha accettato il percorso di rete specificato. Questo errore viene restituito se nessun provider di rete ha riconosciuto il membro |
|
La rete non è disponibile. |
|
Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito. |
Osservazioni
In Windows Server 2003 e Windows XP, le funzioni WNet creano ed eliminano lettere di unità di rete nello spazio dei nomi dei dispositivi MS-DOS associato a una sessione di accesso perché i dispositivi MS-DOS sono identificati da AuthenticationID (a
identificatore univoco localeo 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. La chiamata alla funzione GetLogicalDrives
In Windows Server 2003 e Windows XP, se un servizio 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
\192.168.1.1\share
Per i provider di rete Microsoft in Windows Vista e versioni successive, il
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
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 chiamare nuovamente con uno di questi parametri come NULL (per usare il nome utente predefinito o la password predefinita) allo stesso server, chiamata con esito negativo. L'errore restituito sarà ERROR_BAD_USERNAME o ERROR_INVALID_PASSWORD.
Esempi
L'esempio di codice seguente illustra come usare la funzione WNetAddConnection2
#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 stabilire una connessione a una risorsa di rete usando la funzione di WNetAddConnection2
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 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 |
Vedere anche
Panoramica rete Windows