WNetAddConnectionW-Funktion (winnetwk.h)

Artikel
03/04/2024

Die WNetAddConnection-Funktion ermöglicht es der aufrufenden Anwendung, ein lokales Gerät mit einer Netzwerkressource zu verbinden. Eine erfolgreiche Verbindung ist dauerhaft, d. h. das System stellt die Verbindung bei nachfolgenden Anmeldevorgängen automatisch wieder her.

Hinweis Diese Funktion wird nur aus Gründen der Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Andere Windows-basierte Anwendungen sollten die Funktion WNetAddConnection2 oder WNetAddConnection3 aufrufen.

Syntax

DWORD WNetAddConnectionW(
  [in] LPCWSTR lpRemoteName,
  [in] LPCWSTR lpPassword,
  [in] LPCWSTR lpLocalName
);

Parameter

[in] lpRemoteName

Ein Zeiger auf eine konstante NULL-endende Zeichenfolge, die die Netzwerkressource angibt, mit der eine Verbindung hergestellt werden soll.

[in] lpPassword

Ein Zeiger auf eine konstante NULL-endende Zeichenfolge, die das Kennwort angibt, das zum Herstellen einer Verbindung verwendet werden soll. Dieser Parameter ist in der Regel das Kennwort, das dem aktuellen Benutzer zugeordnet ist.

Wenn dieser Parameter NULL ist, wird das Standardkennwort verwendet. Wenn die Zeichenfolge leer ist, wird kein Kennwort verwendet.

Windows Me/98/95: Dieser Parameter muss NULL oder eine leere Zeichenfolge sein.

[in] lpLocalName

Ein Zeiger auf eine konstante 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 NULL ist, wird eine Verbindung mit der Netzwerkressource hergestellt, ohne das lokale Gerät umzuleiten.

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 im lpLocalName-Parameter angegebene Gerät ist bereits verbunden.
ERROR_BAD_DEV_TYPE	Der Gerätetyp und der Ressourcentyp stimmen nicht überein.
ERROR_BAD_DEVICE	Der im lpLocalName-Parameter angegebene Wert ist ungültig.
ERROR_BAD_NET_NAME	Der im lpRemoteName-Parameter angegebene Wert ist ungültig oder kann nicht gefunden werden.
ERROR_BAD_PROFILE	Das Benutzerprofil weist ein falsches Format auf.
ERROR_CANNOT_OPEN_PROFILE	Das System kann das Benutzerprofil nicht öffnen, um persistente Verbindungen zu verarbeiten.
ERROR_DEVICE_ALREADY_REMEMBERED	Ein Eintrag für das im lpLocalName-Parameter angegebene Gerät befindet sich bereits im Benutzerprofil.
ERROR_EXTENDED_ERROR	Ein netzwerkspezifischer Fehler ist aufgetreten. Rufen Sie die WNetGetLastError-Funktion auf, um eine Beschreibung des Fehlers zu erhalten.
ERROR_INVALID_PASSWORD	Das angegebene Kennwort ist ungültig.
ERROR_NO_NET_OR_BAD_PATH	Der Vorgang kann nicht ausgeführt werden, weil eine Netzwerkkomponente nicht gestartet wurde oder ein angegebener Name nicht verwendet werden kann.
ERROR_NO_NETWORK	Das Netzwerk ist nicht verfügbar.

Hinweise

Unter Windows Server 2003 und Windows XP erstellen und löschen die WNet-Funktionen Netzlaufwerkbuchstaben im MS-DOS-Gerätenamespace, der einer Anmeldesitzung zugeordnet ist, da MS-DOS-Geräte durch AuthenticationID (a) identifiziert werden
lokal eindeutiger Bezeichner oder LUID, die 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 . Der Aufruf der GetLogicalDrives-Funktion gibt keine Netzlaufwerkbuchstaben zurück, die von WNet-Funktionsaufrufen 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.

Wenn unter Windows Server 2003 und Windows XP ein Dienst, der als LocalSystem ausgeführt wird, die WNetAddConnection-Funktion aufruft, ist das zugeordnete Laufwerk für alle Benutzeranmeldungssitzungen sichtbar.

Hinweis

Der winnetwk.h-Header definiert WNetAddConnection 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

Anforderung	Wert
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