Funzione WNetAddConnectionA (winnetwk.h)

Articolo
08/27/2023

La funzione WNetAddConnection consente all'applicazione chiamante di connettere un dispositivo locale a una risorsa di rete. Una connessione riuscita è persistente, ovvero il sistema ripristina automaticamente la connessione durante le operazioni di accesso successive.

Nota Questa funzione viene fornita solo per la compatibilità con le versioni a 16 bit di Windows. Altre applicazioni basate su Windows devono chiamare la funzione WNetAddConnection2 o WNetAddConnection3 .

Sintassi

DWORD WNetAddConnectionA(
  [in] LPCSTR lpRemoteName,
  [in] LPCSTR lpPassword,
  [in] LPCSTR lpLocalName
);

Parametri

[in] lpRemoteName

Puntatore a una stringa costante con terminazione Null che specifica la risorsa di rete a cui connettersi.

[in] lpPassword

Puntatore a una stringa costante con terminazione Null che specifica la password da utilizzare per stabilire una connessione. Questo parametro è in genere la password associata all'utente corrente.

Se questo parametro è NULL, viene usata la password predefinita. Se la stringa è vuota, non viene usata alcuna password.

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

[in] lpLocalName

Puntatore a una stringa costante 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 è NULL, viene stabilita una connessione alla risorsa di rete senza reindirizzare il dispositivo locale.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene 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 specificato nel parametro lpLocalName è già connesso.
ERROR_BAD_DEV_TYPE	Il tipo di dispositivo e il tipo di risorsa non corrispondono.
ERROR_BAD_DEVICE	Il valore specificato nel parametro lpLocalName non è valido.
ERROR_BAD_NET_NAME	Il valore specificato nel parametro lpRemoteName non è valido o non può essere individuato.
ERROR_BAD_PROFILE	Il profilo utente è in un formato non corretto.
ERROR_CANNOT_OPEN_PROFILE	Il sistema non è in grado di aprire il profilo utente per elaborare le connessioni permanenti.
ERROR_DEVICE_ALREADY_REMEMBERED	Una voce per il dispositivo specificato nel parametro lpLocalName è già presente nel profilo utente.
ERROR_EXTENDED_ERROR	Si è verificato un errore specifico della rete. Per ottenere una descrizione dell'errore, chiamare la funzione WNetGetLastError .
ERROR_INVALID_PASSWORD	La password specificata non è valida.
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.

Commenti

In Windows Server 2003 e Windows XP le funzioni WNet creano ed eliminano lettere di unità di rete nello spazio dei nomi del dispositivo MS-DOS associato 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 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 WNetAddConnection , l'unità mappata è visibile a tutte le sessioni di accesso utente.

Nota

L'intestazione winnetwk.h definisce WNetAddConnection 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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