WNetUseConnectionA-Funktion (winnetwk.h)

Artikel
08/27/2023

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

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 zur Netzwerkressource umzuleiten.

Syntax

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Parameter

[in] hwndOwner

Behandeln Sie 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.

[in] lpNetResource

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

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

Mitglied	Bedeutung
dwType	Gibt den Typ der Ressource an, mit der eine Verbindung hergestellt werden soll. Es ist am effizientesten, einen Ressourcentyp in diesem Member anzugeben, z. B. RESOURCETYPE_DISK oder RESOURCETYPE_PRINT. Wenn das lpLocalName-Element jedoch NULL ist oder auf eine leere Zeichenfolge verweist und CONNECT_REDIRECT nicht festgelegt ist, kann dwType RESOURCETYPE_ANY werden. Diese Methode funktioniert nur, wenn die Funktion nicht automatisch ein Gerät auswäht, das zur Netzwerkressource umgeleitet werden soll. Obwohl dieser Member erforderlich ist, werden seine Informationen möglicherweise vom Netzwerkdienstanbieter ignoriert.
lpLocalName	Zeiger auf eine NULL-beendete 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, wird eine Verbindung mit dem Netzwerk ohne Umleitung hergestellt. Wenn der wert CONNECT_REDIRECT im dwFlags-Parameter festgelegt ist oder das Netzwerk ein umgeleitetes lokales Gerät erfordert, wählt die Funktion ein lokales Gerät aus, das umgeleitet werden soll, und gibt den Namen des Geräts im lpAccessName-Parameter zurück.
lpRemoteName	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	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 den Netzwerkanbieter kennen, den Sie verwenden möchten. Lassen Sie andernfalls vom Betriebssystem bestimmen, welchem Anbieter der Netzwerkname zugeordnet ist.

Die WNetUseConnection-Funktion ignoriert die anderen Member der NETRESOURCE-Struktur . Weitere Informationen finden Sie in den folgenden Beschreibungen für den dwFlags-Parameter .

[in] lpPassword

Zeiger auf eine konstante NULL-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 lpUserID 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.

[in] lpUserId

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

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

Der lpUserID-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.

[in] dwFlags

Eine Reihe von Bitflags, die die Verbindung beschreiben. Dieser Parameter kann eine beliebige Kombination der folgenden Werte sein.

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 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 den vorherigen Releases Laufwerkbuchstaben zugewiesen wurden, die mit C: und enden mit Z:.
CONNECT_UPDATE_PROFILE	Dieses Flag weist das Betriebssystem an, die Netzwerkressourcenverbindung zu speichern. Wenn dieses Bitflag festgelegt ist, versucht das Betriebssystem automatisch, die Verbindung wiederherzustellen, wenn sich der Benutzer anmeldet. Das System erinnert sich nur an 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 lpLocalNameNULL 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.

[out] lpAccessName

Zeiger auf einen Puffer, der Systemanforderungen für die Verbindung empfängt. Dieser Parameter kann NULL sein.

Wenn dieser Parameter angegeben ist und das lpLocalName-Element der NETRESOURCE-Struktur ein lokales Gerät angibt, empfängt dieser Puffer den lokalen Gerätenamen. Wenn lpLocalName kein Gerät angibt und das Netzwerk eine lokale Geräteumleitung erfordert, oder wenn der wert CONNECT_REDIRECT festgelegt ist, empfängt dieser Puffer den Namen des umgeleiteten lokalen Geräts.

Andernfalls ist der in den Puffer kopierte Name der einer Remoteressource. Wenn angegeben, muss dieser Puffer mindestens so groß sein wie die Zeichenfolge, auf die das lpRemoteName-Element verweist.

[in, out] lpBufferSize

Zeiger auf eine Variable, die die Größe des puffers lpAccessName in Zeichen angibt. Wenn der Aufruf fehlschlägt, weil der Puffer nicht groß genug ist, gibt die Funktion die erforderliche Puffergröße an diesem Speicherort zurück. Weitere Informationen finden Sie in den Beschreibungen des lpAccessName-Parameters und im ERROR_MORE_DATA Fehlercode im Abschnitt Rückgabewerte.

[out] lpResult

Zeiger auf eine Variable, die zusätzliche Informationen zur Verbindung empfängt. Dieser Parameter kann der folgende Wert sein.

Wert	Bedeutung
CONNECT_LOCALDRIVE	Wenn dieses Flag festgelegt ist, wurde die Verbindung mithilfe einer lokalen Geräteumleitung hergestellt. Wenn der lpAccessName-Parameter auf einen Puffer verweist, wird der lokale Gerätename in den Puffer kopiert.

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_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 die benannte Ressource nicht gefunden werden kann.
ERROR_BAD_PROVIDER	Der vom lpProvider-Member angegebene Wert stimmt mit keinem Anbieter überein.
ERROR_CANCELLED	Der Versuch, die Verbindung herzustellen, wurde vom Benutzer über ein Dialogfeld von einem der Netzwerkressourcenanbieter oder durch eine aufgerufene Ressource abgebrochen.
ERROR_EXTENDED_ERROR	Es ist ein netzwerkspezifischer Fehler aufgetreten. Rufen Sie die WNetGetLastError-Funktion auf, um eine Beschreibung des Fehlers zu erhalten.
ERROR_INVALID_ADDRESS	Der Aufrufer hat einen Zeiger an einen Puffer übergeben, auf den nicht zugegriffen werden konnte.
ERROR_INVALID_PARAMETER	Dieser Fehler ist auf eine der folgenden Bedingungen zurückzuführen: Das lpRemoteName-Element ist NULL. Darüber hinaus ist lpAccessName nicht NULL, aber lpBufferSize ist entweder NULL oder zeigt auf 0. Das dwType-Element ist weder RESOURCETYPE_DISK noch RESOURCETYPE_PRINT. Darüber hinaus ist entweder CONNECT_REDIRECT in dwFlags festgelegt und lpLocalName ist NULL, oder die Verbindung mit einem Netzwerk, das die Umleitung eines lokalen Geräts erfordert.
ERROR_INVALID_PASSWORD	Das angegebene Kennwort ist ungültig, und das CONNECT_INTERACTIVE Flag ist nicht festgelegt.
ERROR_MORE_DATA	Der puffer lpAccessName ist zu klein. Wenn ein lokales Gerät umgeleitet wird, muss der Puffer groß genug sein, um den lokalen Gerätenamen zu enthalten. Andernfalls muss der Puffer groß genug sein, um entweder die Zeichenfolge zu enthalten, auf die von lpRemoteName verwiesen wird, oder den Namen der verbindenden Ressource, auf deren Alias von lpRemoteName verwiesen wird. Wenn dieser Fehler zurückgegeben wird, wurde keine Verbindung hergestellt.
ERROR_NO_MORE_ITEMS	Das Betriebssystem kann nicht automatisch eine lokale Umleitung auswählen, da alle gültigen lokalen Geräte verwendet werden.
ERROR_NO_NET_OR_BAD_PATH	Der Vorgang konnte nicht abgeschlossen werden, entweder weil eine Netzwerkkomponente nicht gestartet wurde oder weil der angegebene Ressourcenname nicht erkannt wird.
ERROR_NO_NETWORK	Das Netzwerk ist nicht verfügbar.

Hinweise

Windows Server 2003 und Windows XP: Die WNet-Funktionen erstellen und löschen Netzwerklaufwerkbuchstaben im MS-DOS-Gerätenamespace, der einer Anmeldesitzung zugeordnet ist, da MS-DOS-Geräte durch AuthenticationID identifiziert werden. (Eine AuthenticationID ist der lokal eindeutige Bezeichner oder LUID, der einer Anmeldesitzung zugeordnet ist.) Dies kann sich auf Anwendungen auswirken, die eine der WNet-Funktionen aufrufen, um einen Netzwerklaufwerkbuchstaben unter einer Benutzeranmeldung zu erstellen, aber nach vorhandenen 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 . GetLogicalDrives gibt keine Netzwerklaufwerkbuchstaben zurück, die von einer WNet-Funktion unter der ersten Anmeldung erstellt wurden. Beachten Sie, dass im vorherigen Beispiel die erste Anmeldesitzung weiterhin vorhanden ist und das Beispiel auf jede Anmeldesitzung, einschließlich einer Terminaldienstesitzung, angewendet werden kann. Weitere Informationen finden Sie unter Definieren eines MS-DOS-Gerätenamens.

Hinweis

Der winnetwk.h-Header definiert WNetUseConnection 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 nicht codierungsneutralem Code 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