WNetAddConnection4W-Funktion (winnetwk.h)

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

Die WNetAddConnection4-Funktion ähnelt der WNetAddConnection3-Funktion . Der Hauptunterschied besteht darin, dass WNetAddConnection4 über einen zusätzlichen Parameter verfügt, der es dem Aufrufer ermöglicht, einen erweiterbaren Eigenschaftenbehälter mit Parametern anzugeben. Die Funktionen WNetAddConnection2, WNetAddConnection3 und WNetAddConnection4 ersetzen die WNetAddConnection-Funktion .

Syntax

DWORD WNetAddConnection4W(
  HWND           hwndOwner,
  LPNETRESOURCEW lpNetResource,
  PVOID          pAuthBuffer,
  DWORD          cbAuthBuffer,
  DWORD          dwFlags,
  PBYTE          lpUseOptions,
  DWORD          cbUseOptions
);

Die Parameter

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 WNetAddConnection4 dem Aufrufen der WNetAddConnection2-Funktion .

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 WNetAddConnection4-Funktion ignoriert die anderen Member der NETRESOURCE-Struktur .

pAuthBuffer

Ein Zeiger auf einen Puffer, der Authentifizierungsinformationen für die Netzwerkressource enthält. Das Format dieses Puffers ist anbieterspezifisch. Wenn der Puffer NULL ist, werden die Standardauthentifizierungsinformationen verwendet.

cbAuthBuffer

Die Größe des Authentifizierungsinformationspuffers in Bytes, auf die der pAuthBuffer-Parameter verweist. Wenn pAuthBufferNULL ist, kann dieser Parameter null sein.

dwFlags

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

lpUseOptions

Ein Zeiger auf einen Puffer, der eine Reihe von Optionen für die Verbindung enthält. Das Format dieses Puffers ist anbieterspezifisch. Wenn der Puffer NULL ist, werden die Standardoptionen verwendet.

cbUseOptions

Die Größe des Optionspuffers in Bytes, auf den der lpUseOptions-Parameter verweist. Wenn lpUseOptionsNULL ist, kann dieser Parameter null sein.

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:

Bemerkungen

Die WNetUseConnection-Funktion ähnelt der Funktion WNetAddConnection4 . 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 identifiziert werden (eine lokal eindeutige ID 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 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 WNetAddConnection4-Funktion aufruft, ist das zugeordnete Laufwerk für alle Benutzeranmeldesitzungen sichtbar.

Für Microsoft-Netzwerkanbieter kann das lpRemoteName-Mitglied der NETRESOURCE-Struktur , auf das der lpNetResource-Parameter verweist, 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 das der lpNetResource-Parameter verweist, 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 das 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 WNetAddConnection4-Funktion mit expliziten Benutzeranmeldeinformationen aufgerufen wird, die im pAuthBuffer angegeben sind, um eine Verbindung mit einer Netzwerkressource auf einem bestimmten Server herzustellen und dann erneut mit dem Parameter ALS NULL (zur Verwendung der Standardanmeldeinformationsinformationen) auf demselben Server aufgerufen wird, schlägt der Aufruf fehl. Der zurückgegebene Fehler wird ERROR_BAD_USERNAME oder ERROR_INVALID_PASSWORD.

Anforderungen

Siehe auch

• WNetAddConnection
• WNetAddConnection2
• WNetAddConnection3