WNetUseConnectionW-Funktion (winnetwk.h)

Artikel
08/27/2023

Die WNetUseConnection-Funktion stellt eine Verbindung mit einer Netzwerkressource her. Die Funktion kann ein lokales Gerät an eine Netzwerkressource umleiten.

Die WNetUseConnection-Funktion ähnelt der WNetAddConnection3-Funktion . Der Standard Unterschied besteht darin, dass WNetUseConnection automatisch ein nicht verwendetes lokales Gerät auswählen kann, um an die Netzwerkressource umzuleiten.

Syntax

DWORD WNetUseConnectionW(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEW lpNetResource,
  [in]      LPCWSTR        lpPassword,
  [in]      LPCWSTR        lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPWSTR         lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Parameter

[in] hwndOwner

Handle für ein Fenster, das der Anbieter von Netzwerkressourcen als Besitzerfenster für Dialogfelder verwenden kann. Verwenden Sie diesen Parameter, wenn Sie den CONNECT_INTERACTIVE-Wert im dwFlags-Parameter festlegen.

[in] lpNetResource

Zeiger auf eine NETRESOURCE-Struktur , die Details der vorgeschlagenen Verbindung angibt. Die -Struktur enthält Informationen zur Netzwerkressource, zum lokalen Gerät und zum Netzwerkressourcenanbieter.

Sie müssen die folgenden Member der NETRESOURCE-Struktur angeben.

Mitglied	Bedeutung
dwType	Gibt den Typ der Ressource an, mit der eine Verbindung hergestellt werden soll. Es ist am effizientesten, einen Ressourcentyp in diesem Member anzugeben, z. B. RESOURCETYPE_DISK oder RESOURCETYPE_PRINT. Wenn der lpLocalName-Member jedoch NULL ist oder auf eine leere Zeichenfolge zeigt und CONNECT_REDIRECT nicht festgelegt ist, kann dwType RESOURCETYPE_ANY werden. Diese Methode funktioniert nur, wenn die Funktion nicht automatisch ein Gerät auswäht, das an die Netzwerkressource umgeleitet werden soll. Obwohl dieser Member erforderlich ist, werden seine Informationen möglicherweise vom Netzwerkdienstanbieter ignoriert.
lpLocalName	Zeiger auf eine NULL-endende Zeichenfolge, die den Namen eines lokalen Geräts angibt, das umgeleitet werden soll, z. B. "F:" oder "LPT1". Bei der Zeichenfolge wird die Groß-/Kleinschreibung nicht beachtet. Wenn die Zeichenfolge leer ist oder lpLocalNameNULL ist, erfolgt eine Verbindung mit dem Netzwerk ohne Umleitung. Wenn der wert CONNECT_REDIRECT im dwFlags-Parameter festgelegt ist oder das Netzwerk ein umgeleitetes lokales Gerät erfordert, wählt die Funktion ein lokales Gerät aus, das umgeleitet werden soll, und gibt den Namen des Geräts im lpAccessName-Parameter zurück.
lpRemoteName	Zeiger auf eine NULL-endende Zeichenfolge, die die Netzwerkressource angibt, mit der eine Verbindung hergestellt werden soll. Die Zeichenfolge kann bis zu MAX_PATH Zeichen lang sein und muss den Namenskonventionen des Netzwerkanbieters entsprechen.
lpProvider	Zeiger auf eine NULL-endende Zeichenfolge, die den Netzwerkanbieter angibt, mit dem eine Verbindung hergestellt werden soll. Wenn lpProviderNULL ist oder auf eine leere Zeichenfolge zeigt, versucht das Betriebssystem, den richtigen Anbieter zu ermitteln, indem die Zeichenfolge analysiert wird, auf die vom lpRemoteName-Member verwiesen wird. Wenn dieser Member nicht NULL ist, versucht das Betriebssystem, nur eine Verbindung mit dem benannten Netzwerkanbieter herzustellen. Sie sollten dieses Element nur festlegen, wenn Sie den Netzwerkanbieter kennen, den Sie verwenden möchten. Lassen Sie andernfalls vom Betriebssystem bestimmen, welchem Anbieter der Netzwerkname zugeordnet ist.

Die WNetUseConnection-Funktion ignoriert die anderen Member der NETRESOURCE-Struktur . Weitere Informationen finden Sie in den folgenden Beschreibungen für den dwFlags-Parameter .

[in] lpPassword

Zeiger auf eine konstante NULL-endende Zeichenfolge, die ein Kennwort angibt, das beim Herstellen der Netzwerkverbindung verwendet werden soll.

Wenn lpPasswordNULL ist, verwendet die Funktion das aktuelle Standardkennwort, das dem durch lpUserID angegebenen Benutzer zugeordnet ist.

Wenn lpPassword auf eine leere Zeichenfolge zeigt, verwendet die Funktion kein Kennwort.

Wenn die Verbindung aufgrund eines ungültigen Kennworts fehlschlägt und der wert CONNECT_INTERACTIVE im dwFlags-Parameter festgelegt ist, zeigt die Funktion ein Dialogfeld an, in dem der Benutzer aufgefordert wird, das Kennwort einzugeben.

[in] lpUserId

Zeiger auf eine konstante NULL-endende Zeichenfolge, die einen Benutzernamen zum Herstellen der Verbindung angibt.

Wenn lpUserIDNULL ist, verwendet die Funktion den Standardbenutzernamen. (Der Benutzerkontext für den Prozess stellt den Standardbenutzernamen bereit.)

Der lpUserID-Parameter wird angegeben, wenn Benutzer eine Verbindung mit einer Netzwerkressource herstellen möchten, der ihnen ein anderer Benutzername oder ein anderes Konto als dem Standardbenutzernamen oder -konto zugewiesen wurde.

Die Benutzernamenzeichenfolge stellt einen Sicherheitskontext dar. Es kann spezifisch für einen Netzwerkanbieter sein.

[in] dwFlags

Eine Reihe von Bitflags, die die Verbindung beschreiben. Dieser Parameter kann eine beliebige Kombination der folgenden Werte sein.

Wert	Bedeutung
CONNECT_INTERACTIVE	Wenn dieses Flag festgelegt ist, kann das Betriebssystem zu Authentifizierungszwecken mit dem Benutzer interagieren.
CONNECT_PROMPT	Dieses Flag weist das System an, keine Standardeinstellungen für Benutzernamen oder Kennwörter zu verwenden, ohne dem Benutzer die Möglichkeit zu bieten, eine Alternative anzugeben. Dieses Flag wird ignoriert, es sei denn, CONNECT_INTERACTIVE ist ebenfalls festgelegt.
CONNECT_REDIRECT	Dieses Flag erzwingt beim Herstellen der Verbindung die Umleitung eines lokalen Geräts. Wenn das lpLocalName-Element von NETRESOURCE ein lokales Umleitungsgerät angibt, hat dieses Flag keine Auswirkung, da das Betriebssystem weiterhin versucht, das angegebene Gerät umzuleiten. Wenn das Betriebssystem automatisch ein lokales Gerät auswährt, darf der dwType-Member nicht gleich RESOURCETYPE_ANY sein. Wenn dieses Flag nicht festgelegt ist, wird ein lokales Gerät nur dann automatisch für die Umleitung ausgewählt, wenn das Netzwerk die Umleitung eines lokalen Geräts erfordert. Windows XP: Wenn das System automatisch Netzlaufwerkbuchstaben zuweist, werden Buchstaben zugewiesen, die mit Z: beginnen, dann Y:, und enden mit C:. Dadurch werden Konflikte zwischen Laufwerkbuchstaben pro Anmeldung (z. B. Netzlaufwerkbuchstaben) und globalen Laufwerkbuchstaben (z. B. Datenträgern) reduziert. Beachten Sie, dass in früheren Versionen Laufwerkbuchstaben zugewiesen wurden, die mit C: beginnen und mit Z:enden.
CONNECT_UPDATE_PROFILE	Dieses Flag weist das Betriebssystem an, die Netzwerkressourcenverbindung zu speichern. Wenn dieses Bitflag festgelegt ist, versucht das Betriebssystem automatisch, die Verbindung wiederherzustellen, wenn sich der Benutzer anmeldet. Das System speichert nur erfolgreiche Verbindungen, die lokale Geräte umleiten. Verbindungen, die nicht erfolgreich oder gerätelos sind, werden nicht gespeichert. (Eine gerätelose Verbindung tritt auf, wenn lpLocalNameNULL ist oder auf eine leere Zeichenfolge zeigt.) Wenn dieses Bitflag eindeutig ist, stellt das Betriebssystem die Verbindung bei der Anmeldung nicht automatisch wieder her.
CONNECT_COMMANDLINE	Wenn dieses Flag festgelegt ist, fordert das Betriebssystem den Benutzer zur Authentifizierung über die Befehlszeile anstelle einer grafischen Benutzeroberfläche (GUI) auf. Dieses Flag wird ignoriert, es sei denn, CONNECT_INTERACTIVE ist ebenfalls festgelegt. Windows 2000/NT und Windows Me/98/95: Dieser Wert wird nicht unterstützt.
CONNECT_CMD_SAVECRED	Wenn dieses Flag festgelegt ist und das Betriebssystem zur Eingabe von Anmeldeinformationen auffordert, sollten die Anmeldeinformationen vom Anmeldeinformations-Manager gespeichert werden. Wenn der Anmeldeinformations-Manager für die Anmeldesitzung des Aufrufers deaktiviert ist oder der Netzwerkanbieter das Speichern von Anmeldeinformationen nicht unterstützt, wird dieses Flag ignoriert. Dieses Flag wird ebenfalls ignoriert, es sei denn, Sie legen das flag CONNECT_COMMANDLINE fest. Windows 2000/NT und Windows Me/98/95: Dieser Wert wird nicht unterstützt.

[out] lpAccessName

Zeiger auf einen Puffer, der Systemanforderungen für die Verbindung empfängt. Dieser Parameter kann NULL sein.

Wenn dieser Parameter angegeben ist und der lpLocalName-Member der NETRESOURCE-Struktur ein lokales Gerät angibt, empfängt dieser Puffer den namen des lokalen Geräts. Wenn lpLocalName kein Gerät angibt und das Netzwerk eine lokale Geräteumleitung erfordert, oder wenn der wert CONNECT_REDIRECT festgelegt ist, empfängt dieser Puffer den Namen des umgeleiteten lokalen Geräts.

Andernfalls wird der In den Puffer kopierte Name einer Remoteressource verwendet. Wenn angegeben, muss dieser Puffer mindestens so groß sein wie die Zeichenfolge, auf die der lpRemoteName-Member verweist.

[in, out] lpBufferSize

Zeiger auf eine Variable, die die Größe des puffers lpAccessName in Zeichen angibt. Wenn der Aufruf fehlschlägt, weil der Puffer nicht groß genug ist, gibt die Funktion die erforderliche Puffergröße an diesem Speicherort zurück. Weitere Informationen finden Sie in den Beschreibungen des lpAccessName-Parameters und im ERROR_MORE_DATA Fehlercode im Abschnitt Rückgabewerte.

[out] lpResult

Zeiger auf eine Variable, die zusätzliche Informationen zur Verbindung empfängt. Dieser Parameter kann der folgende Wert sein.

Wert	Bedeutung
CONNECT_LOCALDRIVE	Wenn dieses Flag festgelegt ist, wurde die Verbindung mithilfe einer lokalen Geräteumleitung hergestellt. Wenn der lpAccessName-Parameter auf einen Puffer zeigt, wird der Name des lokalen Geräts in den Puffer kopiert.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode, z. B. einer der folgenden Werte.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Aufrufer hat keinen Zugriff auf die Netzwerkressource.
ERROR_ALREADY_ASSIGNED	Das vom lpLocalName-Member angegebene lokale Gerät ist bereits mit einer Netzwerkressource verbunden.
ERROR_BAD_DEVICE	Der von lpLocalName angegebene Wert ist ungültig.
ERROR_BAD_NET_NAME	Der vom lpRemoteName-Element angegebene Wert kann für keinen Netzwerkressourcenanbieter akzeptiert werden, da der Ressourcenname ungültig ist oder die benannte Ressource nicht gefunden werden kann.
ERROR_BAD_PROVIDER	Der vom lpProvider-Member angegebene Wert stimmt mit keinem Anbieter überein.
ERROR_CANCELLED	Der Versuch, die Verbindung herzustellen, wurde vom Benutzer über ein Dialogfeld von einem der Netzwerkressourcenanbieter oder von einer aufgerufenen Ressource abgebrochen.
ERROR_EXTENDED_ERROR	Ein netzwerkspezifischer Fehler ist aufgetreten. Rufen Sie die WNetGetLastError-Funktion auf, um eine Beschreibung des Fehlers zu erhalten.
ERROR_INVALID_ADDRESS	Der Aufrufer hat einen Zeiger auf einen Puffer übergeben, auf den nicht zugegriffen werden konnte.
ERROR_INVALID_PARAMETER	Dieser Fehler ist das Ergebnis einer der folgenden Bedingungen: Das lpRemoteName-Element ist NULL. Darüber hinaus ist lpAccessName nicht NULL, aber lpBufferSize ist entweder NULL oder zeigt auf Null. Der dwType-Member ist weder RESOURCETYPE_DISK noch RESOURCETYPE_PRINT. Darüber hinaus ist entweder CONNECT_REDIRECT in dwFlags festgelegt und lpLocalName ist NULL, oder die Verbindung mit einem Netzwerk, das die Umleitung eines lokalen Geräts erfordert.
ERROR_INVALID_PASSWORD	Das angegebene Kennwort ist ungültig, und das flag CONNECT_INTERACTIVE ist nicht festgelegt.
ERROR_MORE_DATA	Der puffer lpAccessName ist zu klein. Wenn ein lokales Gerät umgeleitet wird, muss der Puffer groß genug sein, um den lokalen Gerätenamen zu enthalten. Andernfalls muss der Puffer groß genug sein, um entweder die Zeichenfolge zu enthalten, auf die lpRemoteName verweist, oder den Namen der verbindungsfähigen Ressource, auf deren Alias von lpRemoteName verwiesen wird. Wenn dieser Fehler zurückgegeben wird, wurde keine Verbindung hergestellt.
ERROR_NO_MORE_ITEMS	Das Betriebssystem kann nicht automatisch eine lokale Umleitung auswählen, da alle gültigen lokalen Geräte verwendet werden.
ERROR_NO_NET_OR_BAD_PATH	Der Vorgang konnte nicht abgeschlossen werden, weil eine Netzwerkkomponente nicht gestartet wurde oder weil der angegebene Ressourcenname nicht erkannt wird.
ERROR_NO_NETWORK	Das Netzwerk ist nicht verfügbar.

Hinweise

Windows Server 2003 und Windows XP: Die WNet-Funktionen erstellen und löschen Netzlaufwerkbuchstaben im MS-DOS-Gerätenamespace, der einer Anmeldesitzung zugeordnet ist, da MS-DOS-Geräte durch AuthenticationID identifiziert werden. (Eine AuthenticationID ist der lokal eindeutige Bezeichner (LUID), der einer Anmeldesitzung zugeordnet ist.) Dies kann sich auf Anwendungen auswirken, die eine der WNet-Funktionen aufrufen, um einen Netzlaufwerkbuchstaben unter einer Benutzeranmeldung zu erstellen, aber vorhandene Netzlaufwerkbuchstaben unter einer anderen Benutzeranmeldung abfragen. Ein Beispiel für diese Situation kann sein, wenn die zweite Anmeldung eines Benutzers innerhalb einer Anmeldesitzung erstellt wird, z. B. durch Aufrufen der CreateProcessAsUser-Funktion , und die zweite Anmeldung eine Anwendung ausführt, die die GetLogicalDrives-Funktion aufruft . GetLogicalDrives gibt keine Netzlaufwerkbuchstaben zurück, die von einer WNet-Funktion unter der ersten Anmeldung erstellt wurden. Beachten Sie, dass im vorherigen Beispiel die erste Anmeldesitzung noch vorhanden ist und das Beispiel für jede Anmeldesitzung gelten kann, einschließlich einer Terminaldienste-Sitzung. Weitere Informationen finden Sie unter Definieren eines MS-DOS-Gerätenamens.

Hinweis

Der winnetwk.h-Header definiert WNetUseConnection als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winnetwk.h
Bibliothek	Mpr.lib
DLL	Mpr.dll