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 funktion WNetAddConnection2. Der Hauptunterschied besteht darin, dass WNetAddConnection3- über einen zusätzlichen Parameter verfügt, ein Handle zu einem Fenster, das der Anbieter von Netzwerkressourcen als Besitzerfenster für Dialogfelder verwenden kann. Die funktion WNetAddConnection2 und die WNetAddConnection3-Funktion ersetzt 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 ja, 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--terminated-Zeichenfolge, die ein Kennwort angibt, das beim Herstellen der Netzwerkverbindung verwendet werden soll.
Wenn lpPassword-NULL-ist, verwendet die Funktion das aktuelle Standardkennwort, das dem vom lpUserName Parameter angegebenen Benutzer zugeordnet ist.
Wenn lpPassword- auf eine leere Zeichenfolge zeigt, verwendet die Funktion kein Kennwort.
Wenn die Verbindung aufgrund eines ungültigen Kennworts fehlschlägt und der CONNECT_INTERACTIVE Wert im dwFlags Parameter festgelegt wird, zeigt die Funktion ein Dialogfeld an, in das 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--terminated-Zeichenfolge, die einen Benutzernamen zum 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, für die sie einen anderen Benutzernamen oder ein anderes Konto als den Standardbenutzernamen oder -konto zugewiesen haben.
Die Zeichenfolge für den Benutzernamen stellt einen Sicherheitskontextdar. 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 Kennzeichen festgelegt ist, kann das Betriebssystem für Authentifizierungszwecke mit dem Benutzer interagieren. |
|
Dieses Kennzeichen weist das System an, keine Standardeinstellungen für Benutzernamen oder Kennwörter zu verwenden, ohne dem Benutzer die Möglichkeit zu bieten, eine Alternative zu liefern. Dieses Kennzeichen wird ignoriert, es sei denn, CONNECT_INTERACTIVE ist ebenfalls festgelegt. |
|
Diese Kennzeichnung erzwingt die Umleitung eines lokalen Geräts beim Herstellen der Verbindung.
Wenn das lpLocalName Mitglied von NETRESOURCE ein lokales Gerät angibt, das umgeleitet werden soll, hat dieses Flag keine Auswirkung, da das Betriebssystem weiterhin versucht, das angegebene Gerät umzuleiten. Wenn das Betriebssystem automatisch ein lokales Gerät auswäht, darf der dwType Member nicht gleich RESOURCETYPE_ANY sein. Wenn dieses Kennzeichen nicht festgelegt ist, wird automatisch ein lokales Gerät für die Umleitung ausgewählt, wenn für das Netzwerk ein lokales Gerät umgeleitet werden muss. Windows Server 2003 und Windows XP: Wenn das System automatisch Netzlaufwerkbuchstaben zuweist, werden Buchstaben beginnend mit Z:, dann Y:, und enden mit C:. Dadurch wird die Kollision zwischen Den buchstaben pro Anmeldung (z. B. Netzlaufwerkbuchstaben) und globalen Laufwerkbuchstaben (z. B. Festplattenlaufwerken) reduziert. Beachten Sie, dass frühere Versionen von Windows Laufwerkbuchstaben beginnend mit C: und enden mit Z:. |
|
Die Netzwerkressourcenverbindung sollte gespeichert werden.
Wenn diese Bitkennzeichnung 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. Es merkt sich keine Verbindungen, die nicht erfolgreich oder gerätelos sind. (Eine gerätelose Verbindung tritt auf, wenn das lpLocalName Member NULL- ist oder wenn es auf eine leere Zeichenfolge zeigt.) Wenn diese Bitkennzeichnung eindeutig ist, stellt das Betriebssystem die Verbindung bei der Anmeldung nicht automatisch wieder her. |
|
Wenn dieses Flag festgelegt ist, fordert das Betriebssystem den Benutzer mithilfe der Befehlszeile anstelle einer grafischen Benutzeroberfläche (GUI) zur Authentifizierung auf. Dieses Kennzeichen wird ignoriert, es sei denn, CONNECT_INTERACTIVE ist ebenfalls festgelegt.
Windows 2000/NT und Windows Me/98/95: Dieser Wert wird nicht unterstützt. |
|
Wenn dieses Kennzeichen festgelegt ist und das Betriebssystem zur Eingabe einer Anmeldeinformation auffordert, sollten die Anmeldeinformationen vom Anmeldeinformations-Manager gespeichert werden. Wenn der Anmeldeinformations-Manager für die Anmeldesitzung des Anrufers deaktiviert ist oder wenn der Netzwerkanbieter das Speichern von Anmeldeinformationen nicht unterstützt, wird dieses Flag ignoriert. Dieses Kennzeichen wird auch 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 durch lpLocalName angegebene Wert ist ungültig. |
|
Der vom lpRemoteName Member angegebene Wert ist für keinen Netzwerkressourcenanbieter akzeptabel, entweder weil 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 nicht mit einem Anbieter überein. |
|
Der Router oder Anbieter ist ausgelastet, möglicherweise initialisiert. Der Anrufer sollte erneut versuchen. |
|
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 dauerhafte Verbindungen zu verarbeiten. |
|
Ein Eintrag für das durch das lpLocalName Member angegebene Gerät befindet sich bereits im Benutzerprofil. |
|
Es ist ein netzwerkspezifischer Fehler aufgetreten. Rufen Sie die WNetGetLastError--Funktion auf, um eine Beschreibung des Fehlers abzurufen. |
|
Das angegebene Kennwort ist ungültig, und das CONNECT_INTERACTIVE Flag ist nicht festgelegt. |
|
Der Vorgang kann nicht ausgeführt werden, da eine Netzwerkkomponente nicht gestartet wird oder weil kein angegebener Name verwendet werden kann. |
|
Das Netzwerk ist nicht verfügbar. |
Bemerkungen
Die WNetUseConnection--Funktion ähnelt der funktion WNetAddConnection3. Der Hauptunterschied besteht darin, dass WNetUseConnection- automatisch ein nicht verwendetes lokales Gerät auswählen kann, um zur Netzwerkressource umzuleiten.
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 WNetAddConnection3--Funktion aufruft, ist das zugeordnete Laufwerk für alle Benutzeranmeldesitzungen sichtbar.
Für Microsoft-Netzwerkanbieter kann das lpRemoteName- Mitglied der NETRESOURCE- Struktur enthalten, auf die vom lpNetResource-Parameter verwiesen wird, eine IPv4-Adresse in punktierter Dezimalnotation enthalten. Ein Beispiel für eine Freigabe kann folgendes sein:
\192.168.1.1\share
Für Microsoft-Netzwerkanbieter unter Windows Vista und höher kann das lpRemoteName- Mitglied der NETRESOURCE--Struktur, auf die durch den parameter lpNetResource verwiesen wird, eine IPv6-Adresse enthalten. Das IPv6-Literalformat muss jedoch verwendet werden, damit die IPv6-Adresse korrekt analysiert wird. Eine IPv6-Literaladresse weist das Formular auf:
ipv6-address with the ':' characters replaced by '-' charactersfollowed by the ".ipv6-literal.net" string.
For example, for the following IPv6 address:
2001:4898:9:3:c069:aa97:fe76:2449
Ein Beispiel für eine Freigabe kann folgendes sein:
\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share
Andere Netzwerkanbieter unterstützen möglicherweise das lpRemoteName Mitglied der NETRESOURCE- Struktur, auf die durch den lpNetResource-Parameter verwiesen wird, der eine IPv4- oder IPv6-Adresse enthält, dies liegt jedoch an einem bestimmten Netzwerkanbieter.
Windows 7 und Windows Server 2008 R2: Wenn die WNetAddConnection3--Funktion mit expliziten Benutzeranmeldeinformationen aufgerufen wird, die im pUsername- und lpPassword-, um eine Verbindung mit einer Netzwerkressource auf einem bestimmten Server herzustellen und dann erneut mit einem dieser Parameter als NULL- (um den Standardbenutzernamen oder das Standardkennwort zu verwenden) mit demselben Server aufgerufen wird, der Anruf fehlschlägt. Der zurückgegebene Fehler wird ERROR_BAD_USERNAME oder ERROR_INVALID_PASSWORD.
Anmerkung
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 |
|---|---|
| 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 |
Siehe auch
übersicht über Windows Networking (WNet)