WNetAddConnectionA-Funktion (winnetwk.h)

Artikel
11/20/2024

Mit der WNetAddConnection--Funktion kann die aufrufende Anwendung ein lokales Gerät mit einer Netzwerkressource 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 zur Kompatibilität mit 16-Bit-Versionen von Windows bereitgestellt. Andere windowsbasierte Anwendungen sollten die WNetAddConnection2- oder die WNetAddConnection3--Funktion aufrufen.

Syntax

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

Parameter

[in] lpRemoteName

Ein Zeiger auf eine Konstante null-terminated string, die die Netzwerkressource angibt, mit der eine Verbindung hergestellt werden soll.

[in] lpPassword

Ein Zeiger auf eine Konstante null-terminated string, 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-terminated string, der den Namen eines lokalen Geräts angibt, das umgeleitet werden soll, z. B. "F:" oder "LPT1". Die Zeichenfolge wird ohne Groß-/Kleinschreibung behandelt. 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 dauerhafte 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	Es ist ein netzwerkspezifischer Fehler aufgetreten. Rufen Sie zum Abrufen einer Beschreibung des Fehlers die WNetGetLastError--Funktion auf.
ERROR_INVALID_PASSWORD	Das angegebene Kennwort ist ungültig.
ERROR_NO_NET_OR_BAD_PATH	Der Vorgang kann nicht ausgeführt werden, da eine Netzwerkkomponente nicht gestartet wird oder weil kein angegebener Name verwendet werden kann.
ERROR_NO_NETWORK	Das Netzwerk ist nicht verfügbar.

Bemerkungen

Unter Windows Server 2003 und Windows XP erstellen und löschen die WNet-Funktionen Netzwerklaufwerkbuchstaben im MS-DOS Gerätenamespace, der einer Anmeldesitzung zugeordnet ist, da MS-DOS Geräte durch AuthenticationID (a
lokal eindeutigen Bezeichnersoder 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 abfragen Sie vorhandene Netzlaufwerkbuchstaben unter einer anderen Benutzeranmeldung. Ein Beispiel für diese Situation könnte sein, wenn die zweite Anmeldung eines Benutzers innerhalb einer Anmeldesitzung erstellt wird, z. B. durch Aufrufen der CreateProcessAsUser--Funktion, und die zweite Anmeldung führt eine Anwendung aus, die die GetLogicalDrives-Funktion aufruft. Der Aufruf der GetLogicalDrives--Funktion gibt keine Netzwerklaufwerkbuchstaben 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 auf jede Anmeldesitzung angewendet werden 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 Benutzeranmeldesitzungen sichtbar.

Anmerkung

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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winnetwk.h
Library	Mpr.lib
DLL-	Mpr.dll