WNetAddConnection3A-Funktion (winnetwk.h)

Artikel
08/27/2023

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

Die WNetAddConnection3-Funktion ähnelt der WNetAddConnection2-Funktion . Der Standard Unterschied besteht darin, dass WNetAddConnection3 über einen zusätzlichen Parameter verfügt, ein Handle für ein Fenster, das der Anbieter von Netzwerkressourcen als Besitzerfenster für Dialogfelder verwenden kann. Die WNetAddConnection2-Funktion und die WNetAddConnection3-Funktion ersetzen die WNetAddConnection-Funktion .

Syntax

DWORD WNetAddConnection3A(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Parameter

[in] hwndOwner

Ein 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.

Der hwndOwner-Parameter kann NULL sein. Wenn dies der Grund ist, entspricht ein Aufruf von WNetAddConnection3 dem Aufrufen der WNetAddConnection2-Funktion .

[in] lpNetResource

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

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

Mitglied	Bedeutung
dwType	Der Typ der Netzwerkressource, mit der eine Verbindung hergestellt werden soll. Wenn das lpLocalName-Element auf eine nicht erlösende Zeichenfolge verweist, kann dieses Element gleich RESOURCETYPE_DISK oder RESOURCETYPE_PRINT sein. Wenn lpLocalNameNULL ist oder auf eine leere Zeichenfolge verweist, kann dwType gleich RESOURCETYPE_DISK, RESOURCETYPE_PRINT oder RESOURCETYPE_ANY sein. Obwohl dieser Member erforderlich ist, werden seine Informationen möglicherweise vom Netzwerkdienstanbieter ignoriert.
lpLocalName	Ein Zeiger auf eine 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 leer ist oder lpLocalNameNULL ist, stellt die Funktion eine Verbindung mit der Netzwerkressource her, ohne ein lokales Gerät umzuleiten.
lpRemoteName	Ein Zeiger auf eine NULL-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 Benennungskonventionen des Netzwerkanbieters entsprechen.
lpProvider	Ein Zeiger auf eine NULL-Zeichenfolge, die den Netzwerkanbieter angibt, mit dem eine Verbindung hergestellt werden soll. Wenn lpProviderNULL ist oder auf eine leere Zeichenfolge verweist, versucht das Betriebssystem, den richtigen Anbieter zu ermitteln, indem es die Zeichenfolge analysiert, 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 diesen Member nur festlegen, wenn Sie wissen, welchen Netzwerkanbieter Sie verwenden möchten. Lassen Sie andernfalls vom Betriebssystem bestimmen, welchem Netzwerkanbieter der Netzwerkname zugeordnet ist.

Die WNetAddConnection3-Funktion ignoriert die anderen Member der NETRESOURCE-Struktur .

[in] lpPassword

Ein Zeiger auf eine NULL-beendete 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 den lpUserName-Parameter angegebenen Benutzer zugeordnet ist.

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

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

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

[in] lpUserName

Ein Zeiger auf eine NULL-Zeichenfolge, die einen Benutzernamen für das Herstellen der Verbindung angibt.

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

Der lpUserName-Parameter wird angegeben, wenn Benutzer eine Verbindung mit einer Netzwerkressource herstellen möchten, der ihnen ein anderer Benutzername oder ein anderes Konto als der Standardbenutzername oder das Standardkonto zugewiesen wurde.

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

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

[in] dwFlags

Eine Reihe von Verbindungsoptionen. Die folgenden Werte sind derzeit definiert.

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 zur Verfügung zu stellen. Dieses Flag wird ignoriert, es sei denn, CONNECT_INTERACTIVE wird ebenfalls festgelegt.
CONNECT_REDIRECT	Dieses Flag erzwingt die Umleitung eines lokalen Geräts beim Herstellen der Verbindung. Wenn das lpLocalName-Mitglied von NETRESOURCE ein lokales Umleitungsgerät angibt, hat dieses Flag keine Auswirkungen, da das Betriebssystem weiterhin versucht, das angegebene Gerät umzuleiten. Wenn das Betriebssystem automatisch ein lokales Gerät wählt, darf der dwType-Member nicht gleich RESOURCETYPE_ANY sein. Wenn dieses Flag nicht festgelegt ist, wird ein lokales Gerät automatisch nur dann für die Umleitung ausgewählt, wenn das Netzwerk die Umleitung eines lokalen Geräts erfordert. Windows Server 2003 und Windows XP: Wenn das System automatisch Netzwerklaufwerkbuchstaben zuweist, werden Buchstaben zugewiesen, die mit Z:, dann Y:, und enden mit C:. Dadurch wird die Kollision zwischen Laufwerkbuchstaben pro Anmeldung (z. B. Netzwerklaufwerkbuchstaben) und globalen Laufwerkbuchstaben (z. B. Datenträgern) verringert. Beachten Sie, dass frühere Versionen von Windows Laufwerkbuchstaben zugewiesen haben, die mit C: beginnen und mit Z:enden.
CONNECT_UPDATE_PROFILE	Die Netzwerkressourcenverbindung sollte gespeichert werden. Wenn dieses Bitflag festgelegt ist, versucht das Betriebssystem automatisch, die Verbindung wiederherzustellen, wenn sich der Benutzer anmeldet. Das Betriebssystem merkt sich nur erfolgreiche Verbindungen, die lokale Geräte umleiten. Sie erinnert sich nicht an verbindungen, die nicht erfolgreich oder gerätelos sind. (Eine gerätelose Verbindung tritt auf, wenn das lpLocalName-ElementNULL ist oder wenn es 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 wird 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 CONNECT_COMMANDLINE-Flag fest. Windows 2000/NT und Windows Me/98/95: Dieser Wert wird nicht unterstützt.

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_DEV_TYPE	Der Typ des lokalen Geräts und der Typ der Netzwerkressource stimmen nicht überein.
ERROR_BAD_DEVICE	Der von lpLocalName angegebene Wert ist ungültig.
ERROR_BAD_NET_NAME	Der vom lpRemoteName-Member angegebene Wert ist für keinen Netzwerkressourcenanbieter akzeptabel, da der Ressourcenname ungültig ist oder weil die benannte Ressource nicht gefunden werden kann.
ERROR_BAD_PROFILE	Das Benutzerprofil weist ein falsches Format auf.
ERROR_BAD_PROVIDER	Der vom lpProvider-Member angegebene Wert stimmt mit keinem Anbieter überein.
ERROR_BUSY	Der Router oder Anbieter ist ausgelastet, möglicherweise initialisiert. Der Aufrufer sollte den Vorgang wiederholen.
ERROR_CANCELLED	Der Versuch, die Verbindung herzustellen, wurde vom Benutzer über ein Dialogfeld von einem der Netzwerkressourcenanbieter oder von einer aufgerufenen Ressource abgebrochen.
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 vom lpLocalName-Element 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, und das flag CONNECT_INTERACTIVE ist nicht festgelegt.
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

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.

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 WNetAddConnection3-Funktion aufruft, ist das zugeordnete Laufwerk für alle Benutzeranmeldesitzungen sichtbar.

Bei Microsoft-Netzwerkanbietern kann das lpRemoteName-Element der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, eine IPv4-Adresse in punktierter dezimaler Notation enthalten. Ein Beispiel für eine Freigabe kann wie folgt sein:

\192.168.1.1\share

Bei Microsoft-Netzwerkanbietern unter Windows Vista und höher kann der lpRemoteName-Member der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, eine IPv6-Adresse enthalten. Allerdings muss das IPv6-Literalformat verwendet werden, damit die IPv6-Adresse ordnungsgemäß analysiert wird. Eine IPv6-Literaladresse hat folgendes Format:

ipv6-address mit den Zeichen ":", die durch "-"-Zeichen gefolgt von der Zeichenfolge ".ipv6-literal.net" ersetzt werden.

Beispielsweise für die folgende IPv6-Adresse:

2001:4898:9:3:c069:aa97:fe76:2449

Ein Beispiel für eine Freigabe kann wie folgt sein:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Andere Netzwerkanbieter unterstützen möglicherweise das lpRemoteName-Element der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, der eine IPv4- oder IPv6-Adresse enthält. Dies gilt jedoch für einen bestimmten Netzwerkanbieter.

Windows 7 und Windows Server 2008 R2: Wenn die WNetAddConnection3-Funktion mit expliziten Benutzeranmeldeinformationen aufgerufen wird, die in pUsername und lpPassword angegeben sind, um eine Verbindung mit einer Netzwerkressource auf einem bestimmten Server herzustellen, und dann erneut mit einem dieser Parameter als NULL aufgerufen wird (um den Standardbenutzernamen oder das Standardkennwort zu verwenden) mit demselben Server, schlägt der Aufruf mit fehl. Der zurückgegebene Fehler wird ERROR_BAD_USERNAME oder ERROR_INVALID_PASSWORD.

Hinweis

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