Funzione WNetAddConnection3A (winnetwk.h)

Articolo
11/20/2024

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

La funzione di WNetAddConnection3 è simile alla funzione WNetAddConnection2 . La differenza principale è che WNetAddConnection3 ha un parametro aggiuntivo, un handle per una finestra che il provider di risorse di rete può usare come finestra di proprietario per le finestre di dialogo. La funzione WNetAddConnection2 e la funzione WNetAddConnection3 sostituisce la funzione WNetAddConnection .

Sintassi

DWORD WNetAddConnection3A(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Parametri

[in] hwndOwner

Handle di una finestra che il provider di risorse di rete può usare come finestra di proprietario per le finestre di dialogo. Usare questo parametro se si imposta il valore CONNECT_INTERACTIVE nel parametro dwFlags.

Il parametro hwndOwner può essere NULL. In caso affermativo, una chiamata a WNetAddConnection3 equivale a chiamare la funzione WNetAddConnection2 .

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

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 è NULLo 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 un nullstringa con terminazione 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 un nullstringa con terminazione 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 un nullstringa con terminazione che specifica il provider di rete a cui connettersi. Se lpProvider è nullo 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 da usare. In caso contrario, consentire al sistema operativo di determinare il provider di rete a cui viene mappato il nome di rete.

La funzione WNetAddConnection3 ignora gli altri membri della struttura NETRESOURCE .

[in] lpPassword

Puntatore a un 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 , la funzione visualizza una finestra di dialogo in cui viene chiesto all'utente di digitare la password.

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

[in] lpUserName

Puntatore a un 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 seguenti sono attualmente definiti.

Valore	Significato
CONNECT_INTERACTIVE	Se questo flag è impostato, il sistema operativo può interagire con l'utente a scopo di autenticazione.
CONNECT_PROMPT	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	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 non deve essere uguale a RESOURCETYPE_ANY. 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:.
CONNECT_UPDATE_PROFILE	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 quando punta a una stringa vuota. Se questo flag di bit è chiaro, il sistema operativo non ripristina automaticamente la connessione all'accesso.
CONNECT_COMMANDLINE	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 2000/NT e Windows Me/98/95: Questo valore non è supportato.
CONNECT_CMD_SAVECRED	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 anche a meno che non si imposti il flag di CONNECT_COMMANDLINE. Windows 2000/NT e Windows Me/98/95: Questo valore non è supportato.

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_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 valore specificato da lpLocalName non è valido.
ERROR_BAD_NET_NAME	Il valore specificato dal membro lpRemoteName non è accettabile per alcun provider di risorse di rete, perché il nome della risorsa non è valido o perché la risorsa denominata non può essere individuata.
ERROR_BAD_PROFILE	Il profilo utente è in un formato non corretto.
ERROR_BAD_PROVIDER	Il valore specificato dal membro lpProvider non corrisponde ad alcun provider.
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	Una voce per il dispositivo specificato dal membro lpLocalName è già presente nel profilo utente.
ERROR_EXTENDED_ERROR	Si è verificato un errore specifico della rete. Chiamare la funzione WNetGetLastError per ottenere una descrizione dell'errore.
ERROR_INVALID_PASSWORD	La password specificata non è valida e il flag CONNECT_INTERACTIVE non è impostato.
ERROR_NO_NET_OR_BAD_PATH	Impossibile eseguire l'operazione perché un componente di rete non è avviato o perché non è possibile utilizzare un nome specificato.
ERROR_NO_NETWORK	La rete non è disponibile.

Osservazioni

La funzione WNetUseConnection è simile alla funzione WNetAddConnection3 . La differenza principale è che WNetUseConnection può selezionare automaticamente un dispositivo locale inutilizzato per reindirizzare alla risorsa di rete.

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 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 di dispositivo MS-DOS.

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

Per i provider di rete Microsoft, il lpRemoteName membro 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 lpRemoteName membro della struttura di NETRESOURCE a cui punta il parametro lpNetResource può contenere un indirizzo IPv6. Tuttavia, è necessario usare il formato letterale IPv6 in modo che l'indirizzo IPv6 venga analizzato correttamente. Un indirizzo letterale IPv6 è nel formato:

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 lpRemoteName membro della struttura NETRESOURCE a cui punta il parametro lpNetResource che contiene un indirizzo IPv4 o IPv6, ma questo è fino a un provider di rete specifico.

Windows 7 e Windows Server 2008 R2: Se la funzione WNetAddConnection3 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 chiamato di nuovo 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.

Nota

L'intestazione winnetwk.h definisce WNetAddConnection3 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