WNetAddConnection3A-Funktion (winnetwk.h)
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.
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 |
|---|---|
|
Wenn dieses Flag festgelegt ist, kann das Betriebssystem zu Authentifizierungszwecken mit dem Benutzer interagieren. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 |
|---|---|
|
Der Aufrufer hat keinen Zugriff auf die Netzwerkressource. |
|
Das vom lpLocalName-Member angegebene lokale Gerät ist bereits mit einer Netzwerkressource verbunden. |
|
Der Typ des lokalen Geräts und der Typ der Netzwerkressource stimmen nicht überein. |
|
Der von lpLocalName angegebene Wert ist ungültig. |
|
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. |
|
Das Benutzerprofil weist ein falsches Format auf. |
|
Der vom lpProvider-Member angegebene Wert stimmt mit keinem Anbieter überein. |
|
Der Router oder Anbieter ist ausgelastet, möglicherweise initialisiert. Der Aufrufer sollte den Vorgang wiederholen. |
|
Der Versuch, die Verbindung herzustellen, wurde vom Benutzer über ein Dialogfeld von einem der Netzwerkressourcenanbieter oder von einer aufgerufenen Ressource abgebrochen. |
|
Das System kann das Benutzerprofil nicht öffnen, um persistente Verbindungen zu verarbeiten. |
|
Ein Eintrag für das vom lpLocalName-Element angegebene Gerät befindet sich bereits im Benutzerprofil. |
|
Ein netzwerkspezifischer Fehler ist aufgetreten. Rufen Sie die WNetGetLastError-Funktion auf, um eine Beschreibung des Fehlers zu erhalten. |
|
Das angegebene Kennwort ist ungültig, und das flag CONNECT_INTERACTIVE ist nicht festgelegt. |
|
Der Vorgang kann nicht ausgeführt werden, weil eine Netzwerkkomponente nicht gestartet wurde oder ein angegebener Name nicht verwendet werden kann. |
|
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 |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für