WNetAddConnection2A-Funktion (winnetwk.h)
Die WNetAddConnection2-Funktion stellt eine Verbindung mit einer Netzwerkressource her und kann ein lokales Gerät an die Netzwerkressource umleiten.
Die WNetAddConnection2-Funktion ersetzt die WNetAddConnection-Funktion . Wenn Sie ein Handle an ein Fenster übergeben können, das der Anbieter von Netzwerkressourcen als Besitzerfenster für Dialogfelder verwenden kann, rufen Sie stattdessen die Funktion WNetAddConnection3 auf.
Syntax
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parameter
[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 WNetAddConnection2-Funktion ignoriert die anderen Member der NETRESOURCE-Struktur .
[in] lpPassword
Ein Zeiger auf eine konstante 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 konstante 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 möglichen Werte für die Verbindungsoptionen werden in der Headerdatei Winnetwk.h definiert. Die folgenden Werte können derzeit verwendet werden.
| Wert | Bedeutung |
|---|---|
|
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 entsteht, wenn das lpLocalName-ElementNULL ist oder auf eine leere Zeichenfolge verweist.) Wenn dieses Bitflag eindeutig ist, versucht das Betriebssystem nicht, die Verbindung wiederherzustellen, wenn sich der Benutzer anmeldet. |
|
Die Netzwerkressourcenverbindung sollte nicht in die Liste der zuletzt verwendeten Verbindungen aufgenommen werden.
Wenn dieses Flag festgelegt ist und die Verbindung erfolgreich hinzugefügt wurde, wird die Netzwerkressourcenverbindung nur dann in die Liste der letzten Verbindungen aufgenommen, wenn ihr ein umgeleitetes lokales Gerät zugeordnet ist. |
|
Die Netzwerkressourcenverbindung sollte nicht gespeichert werden.
Wenn dieses Flag festgelegt ist, versucht das Betriebssystem nicht, die Verbindung wiederherzustellen, wenn sich der Benutzer erneut anmeldet. |
|
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. |
|
Wenn dieses Flag festgelegt ist, beginnt das Betriebssystem nicht, ein neues Medium zu verwenden, um die Verbindung herzustellen (z. B. eine neue DFÜ-Verbindung initiieren). |
|
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 XP: Dieser Wert wird unter Windows XP und höher 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 ignoriert, es sei denn, CONNECT_INTERACTIVE wird ebenfalls festgelegt. Dieses Flag wird ebenfalls ignoriert, es sei denn, Sie legen das CONNECT_COMMANDLINE-Flag fest.
Windows XP: Dieser Wert wird unter Windows XP und höher unterstützt. |
|
Wenn dieses Flag festgelegt ist und das Betriebssystem zur Eingabe von Anmeldeinformationen auffordert, werden die Anmeldeinformationen vom Anmeldeinformations-Manager zurückgesetzt. 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 flag CONNECT_COMMANDLINE fest.
Windows Vista: Dieser Wert wird unter Windows Vista und höher unterstützt. |
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes oder einer der Systemfehlercodes sein.
| 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 angegebene Gerätename ist ungültig. Dieser Fehler wird zurückgegeben, wenn der lpLocalName-Member der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, ein Gerät angibt, das nicht umgeleitet werden kann. |
|
„Der Netzwerkname wurde nicht gefunden.“ Dieser Wert wird zurückgegeben, wenn das lpRemoteName-Element der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, eine Ressource angibt, die für einen Netzwerkressourcenanbieter nicht akzeptabel ist, weil der Ressourcenname entweder leer, ungültig ist oder weil die benannte Ressource nicht gefunden werden kann. |
|
Das Benutzerprofil weist ein falsches Format auf. |
|
Der angegebene Netzwerkanbietername ist ungültig. Dieser Fehler wird zurückgegeben, wenn der lpProvider-Member der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, einen Wert angibt, der keinem Netzwerkanbieter entspricht. |
|
Der angegebene Benutzername ist ungültig. |
|
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. |
|
Der Name des lokalen Geräts verfügt über eine gespeicherte Verbindung mit einer anderen Netzwerkressource. Dieser Fehler wird zurückgegeben, wenn ein Eintrag für das Gerät, das vom lpLocalName-Member der NETRESOURCE-Struktur angegeben wird, auf das der lpNetResource-Parameter verweist, einen Wert angibt, der bereits im Benutzerprofil für eine andere Verbindung als die im lpNetResource-Parameter angegebene ist. |
|
Ein netzwerkspezifischer Fehler ist aufgetreten. Rufen Sie die WNetGetLastError-Funktion auf, um eine Beschreibung des Fehlers zu erhalten. |
|
Es wurde versucht, auf eine ungültige Adresse zuzugreifen. Dieser Fehler wird zurückgegeben, wenn der dwFlags-Parameter einen Wert von CONNECT_REDIRECT angibt, aber der lpLocalName-Member der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, nicht angegeben war. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der dwType-Member der NETRESOURCE-Struktur , auf die der lpNetResource-Parameter verweist, einen anderen Wert als RESOURCETYPE_DISK, RESOURCETYPE_PRINT oder RESOURCETYPE_ANY angibt. Dieser Fehler wird auch zurückgegeben, wenn der dwFlags-Parameter einen falschen oder unbekannten Wert angibt. |
|
Das angegebene Kennwort ist ungültig, und das flag CONNECT_INTERACTIVE ist nicht festgelegt. |
|
Ein Anmeldefehler aufgrund eines unbekannten Benutzernamens oder eines ungültigen Kennworts. |
|
Kein Netzwerkanbieter hat den angegebenen Netzwerkpfad akzeptiert. Dieser Fehler wird zurückgegeben, wenn kein Netzwerkanbieter den lpRemoteName-Member der NETRESOURCE-Struktur erkannt hat, auf die der lpNetResource-Parameter verweist. |
|
Das Netzwerk ist nicht verfügbar. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
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 WNetAddConnection2-Funktion aufruft, ist das zugeordnete Laufwerk für alle Benutzeranmeldungssitzungen 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 WNetAddConnection2-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.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie die WNetAddConnection2-Funktion verwendet wird, um eine Verbindung mit einer Netzwerkressource herzustellen.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
// Need to link with Netapi32.lib and Mpr.lib
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
NETRESOURCE nr;
DWORD dwFlags;
if (argc != 5) {
wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
argv[0]);
wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",
argv[0]);
exit(1);
}
wprintf(L"Calling WNetAddConnection2 with\n");
wprintf(L" lpLocalName = %s\n", argv[1]);
wprintf(L" lpRemoteName = %s\n", argv[2]);
wprintf(L" lpUsername = %s\n", argv[3]);
wprintf(L" lpPassword = %s\n", argv[4]);
// Zero out the NETRESOURCE struct
memset(&nr, 0, sizeof (NETRESOURCE));
// Assign our values to the NETRESOURCE structure.
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];
nr.lpRemoteName = argv[2];
nr.lpProvider = NULL;
// Assign a value to the connection options
dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
// a drive letter to the share.
//
dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
// print the error.
//
if (dwRetVal == NO_ERROR)
wprintf(L"Connection added to %s\n", nr.lpRemoteName);
else
wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);
exit(1);
}
Weitere Codebeispiele, die das Herstellen einer Verbindung mit einer Netzwerkressource mithilfe der WNetAddConnection2-Funktion veranschaulichen, finden Sie unter Hinzufügen einer Netzwerkverbindung und Zuweisen eines Laufwerks zu einer Freigabe.
Hinweis
Der winnetwk.h-Header definiert WNetAddConnection2 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
| 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 |