Funzione WNetUseConnectionA (winnetwk.h)

Articolo
08/27/2023

La funzione WNetUseConnection effettua una connessione a una risorsa di rete. La funzione può reindirizzare un dispositivo locale a una risorsa di rete.

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.

Sintassi

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Parametri

[in] hwndOwner

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

[in] lpNetResource

Puntatore a una struttura NETRESOURCE che specifica i dettagli della connessione proposta. La struttura contiene 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	Specifica il tipo di risorsa a cui connettersi. È più efficiente specificare un tipo di risorsa in questo membro, ad esempio RESOURCETYPE_DISK o RESOURCETYPE_PRINT. Tuttavia, se il membro lpLocalName è NULL o se punta a una stringa vuota e CONNECT_REDIRECT non è impostato, dwType può essere RESOURCETYPE_ANY. Questo metodo funziona solo se la funzione non sceglie automaticamente un dispositivo per reindirizzare alla risorsa di rete. Anche se questo membro è obbligatorio, le informazioni potrebbero 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 in modo senza distinzione tra maiuscole e minuscole. Se la stringa è vuota o se lpLocalName è NULL, si verifica una connessione alla rete senza reindirizzamento. Se il valore CONNECT_REDIRECT è impostato nel parametro dwFlags o se la rete richiede un dispositivo locale reindirizzato, la funzione sceglie un dispositivo locale per reindirizzare e restituisce il nome del dispositivo nel parametro lpAccessName .
lpRemoteName	Puntatore a una stringa con terminazione null che specifica la risorsa di rete a cui connettersi. La stringa può essere fino a MAX_PATH caratteri in lunghezza 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 puntata dal membro lpRemoteName . Se questo membro non è NULL, il sistema operativo tenta di eseguire 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 quale provider esegue il mapping del nome di rete.

La funzione WNetUseConnection ignora gli altri membri della struttura NETRESOURCE . Per altre informazioni, vedere le descrizioni seguenti per il parametro dwFlags .

[in] lpPassword

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

Se lpPassword è NULL, la funzione usa la password predefinita corrente associata all'utente specificato da lpUserID.

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

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

[in] lpUserId

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

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

Il parametro lpUserID 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.

[in] dwFlags

Set di flag di bit che descrivono la connessione. Questo parametro può essere una combinazione dei valori seguenti.

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 le impostazioni predefinite per i nomi utente o le password senza offrire all'utente l'opportunità 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 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, un dispositivo locale viene scelto automaticamente per il reindirizzamento solo se la rete richiede il reindirizzamento di un dispositivo locale. 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 unità di accesso (ad esempio lettere unità di rete) e lettere di unità globali (ad esempio unità disco). Si noti che le versioni precedenti assegnate lettere di unità iniziano con C: e terminano con Z:.
CONNECT_UPDATE_PROFILE	Questo flag indica al sistema operativo di archiviare la connessione alla risorsa di rete. Se questo flag di bit è impostato, il sistema operativo tenta automaticamente di ripristinare la connessione quando l'utente accede. Il sistema ricorda 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 lpLocalName è NULL o quando punta a una stringa vuota. Se questo flag di bit è deselezionato, il sistema operativo non ripristina automaticamente la connessione all'accesso.
CONNECT_COMMANDLINE	Se questo flag è impostato, il sistema operativo richiede all'utente di eseguire l'autenticazione usando la riga di comando anziché un'interfaccia utente grafica.If this flag is set, the operating system prompt the user for authentication using the command line invece of a graphics user interface (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 dalla gestione 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 2000/NT e Windows Me/98/95: Questo valore non è supportato.

[out] lpAccessName

Puntatore a un buffer che riceve le richieste di sistema sulla connessione. Questo parametro può essere NULL.

Se questo parametro viene specificato e il membro lpLocalName della struttura NETRESOURCE specifica un dispositivo locale, questo buffer riceve il nome del dispositivo locale. Se lpLocalName non specifica un dispositivo e la rete richiede un reindirizzamento del dispositivo locale o se il valore CONNECT_REDIRECT è impostato, questo buffer riceve il nome del dispositivo locale reindirizzato.

In caso contrario, il nome copiato nel buffer è quello di una risorsa remota. Se specificato, questo buffer deve essere almeno pari alla stringa a cui punta il membro lpRemoteName .

[in, out] lpBufferSize

Puntatore a una variabile che specifica le dimensioni del buffer lpAccessName , in caratteri. Se la chiamata ha esito negativo perché il buffer non è abbastanza grande, la funzione restituisce le dimensioni del buffer necessarie in questa posizione. Per altre informazioni, vedere le descrizioni del parametro lpAccessName e il codice di errore ERROR_MORE_DATA nella sezione Valori restituiti.

[out] lpResult

Puntatore a una variabile che riceve informazioni aggiuntive sulla connessione. Questo parametro può essere il valore seguente.

Valore	Significato
CONNECT_LOCALDRIVE	Se questo flag è impostato, la connessione è stata eseguita usando un reindirizzamento del dispositivo locale. Se il parametro lpAccessName punta a un buffer, il nome del dispositivo locale viene copiato nel buffer.

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 locale specificato dal membro lpLocalName è già connesso a una risorsa di rete.
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_PROVIDER	Il valore specificato dal membro lpProvider non corrisponde ad alcun provider.
ERROR_CANCELLED	Il tentativo di stabilire 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_EXTENDED_ERROR	Si è verificato un errore specifico della rete. Per ottenere una descrizione dell'errore, chiamare la funzione WNetGetLastError .
ERROR_INVALID_ADDRESS	Il chiamante passato in un puntatore a un buffer a cui non è stato possibile accedere.
ERROR_INVALID_PARAMETER	Questo errore è il risultato di una delle condizioni seguenti: Il membro lpRemoteName è NULL. Inoltre , lpAccessName non è NULL, ma lpBufferSize è NULL o punta a zero. Il membro dwType non è né RESOURCETYPE_DISK né RESOURCETYPE_PRINT. Inoltre, CONNECT_REDIRECT è impostato in dwFlags e lpLocalName è NULL oppure la connessione è a una rete che richiede il reindirizzamento di un dispositivo locale.
ERROR_INVALID_PASSWORD	La password specificata non è valida e il flag di CONNECT_INTERACTIVE non è impostato.
ERROR_MORE_DATA	Il buffer lpAccessName è troppo piccolo. Se un dispositivo locale viene reindirizzato, il buffer deve essere sufficientemente grande da contenere il nome del dispositivo locale. In caso contrario, il buffer deve essere sufficientemente grande da contenere la stringa a cui punta lpRemoteName o il nome della risorsa connettibile a cui punta lpRemoteName. Se viene restituito questo errore, non è stata stabilita alcuna connessione.
ERROR_NO_MORE_ITEMS	Il sistema operativo non può scegliere automaticamente un reindirizzamento locale perché tutti i dispositivi locali validi sono in uso.
ERROR_NO_NET_OR_BAD_PATH	Impossibile completare l'operazione perché non è stato avviato un componente di rete o perché il nome della risorsa specificato non è riconosciuto.
ERROR_NO_NETWORK	La rete non è disponibile.

Commenti

Windows Server 2003 e Windows XP: Le funzioni WNet creano ed eliminano le 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. AuthenticationID è l'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 . GetLogicalDrives non restituisce lettere di unità di rete create da una 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.

Nota

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