WNetAddConnectionA-Funktion (winnetwk.h)

Artikel
08/27/2023

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

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

Syntax

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

Parameter

[in] lpRemoteName

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

[in] lpPassword

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die das Kennwort angibt, das zum Herstellen einer Verbindung verwendet werden soll. Dieser Parameter ist normalerweise 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-Zeichenfolge, die den Namen eines lokalen Geräts angibt, das umgeleitet werden soll, z. B. "F:" oder "LPT1". Die Zeichenfolge wird ohne Beachtung der 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 parameter lpLocalName angegebene Wert ist ungültig.
ERROR_BAD_NET_NAME	Der im parameter lpRemoteName 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 parameter lpLocalName angegebene Gerät befindet sich bereits im Benutzerprofil.
ERROR_EXTENDED_ERROR	Es ist ein netzwerkspezifischer Fehler 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 wird 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 Netzwerklaufwerkbuchstaben 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 Netzwerklaufwerkbuchstaben unter einer Benutzeranmeldung zu erstellen, aber nach vorhandenen 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 Netzwerklaufwerkbuchstaben zurück, die von WNet-Funktionsaufrufen unter der ersten Anmeldung erstellt wurden. Beachten Sie, dass im vorherigen Beispiel die erste Anmeldesitzung weiterhin vorhanden ist und das Beispiel auf jede Anmeldesitzung, einschließlich einer Terminaldienstesitzung, angewendet werden kann. 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 automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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