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 .

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 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.

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.

Requisiti

Vedi anche

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Panoramica di Rete Windows (WNet)

Funzioni di rete Windows