WNetUseConnectionA-Funktion (winnetwk.h)

Artikel
11/20/2024

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 funktion WNetAddConnection3. Der Hauptunterschied 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

Zeigen Sie 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 Element anzugeben, z. B. RESOURCETYPE_DISK oder RESOURCETYPE_PRINT. Wenn der lpLocalName Member jedoch NULL-ist oder wenn es auf eine leere Zeichenfolge zeigt 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 an die Netzwerkressource umgeleitet werden soll. Obwohl dieses Mitglied erforderlich ist, werden seine Informationen möglicherweise vom Netzwerkdienstanbieter ignoriert.
lpLocalName	Zeigen Sie auf eine NULL--terminated-Zeichenfolge, die den Namen eines lokalen Geräts angibt, das umgeleitet werden soll, z. B. "F:" oder "LPT1". Die Zeichenfolge wird ohne Groß-/Kleinschreibung behandelt. Wenn die Zeichenfolge leer ist oder lpLocalNameNULL-ist, tritt eine Verbindung mit dem Netzwerk ohne Umleitung auf. Wenn der CONNECT_REDIRECT Wert im dwFlags Parameter festgelegt wird oder wenn für das Netzwerk ein umgeleitetes lokales Gerät erforderlich ist, wählt die Funktion ein lokales Gerät aus, umzuleiten und den Namen des Geräts im parameter lpAccessName zurück.
lpRemoteName	Zeiger auf eine null-terminated string, 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--terminated string, die den Netzwerkanbieter angibt, mit dem eine Verbindung hergestellt werden soll. Wenn lpProvider-NULL-ist oder wenn sie auf eine leere Zeichenfolge zeigt, versucht das Betriebssystem, den richtigen Anbieter zu ermitteln, indem die Zeichenfolge analysiert wird, auf die vom lpRemoteName Member verwiesen wird. Wenn dieses Element nicht NULL-ist, versucht das Betriebssystem, nur eine Verbindung mit dem benannten Netzwerkanbieter herzustellen. Sie sollten dieses Mitglied nur festlegen, wenn Sie den Netzwerkanbieter kennen, den Sie verwenden möchten. Lassen Sie andernfalls das Betriebssystem bestimmen, welchem Anbieter der Netzwerkname zugeordnet ist.

Die WNetUseConnection--Funktion ignoriert die anderen Elemente der NETRESOURCE--Struktur. Weitere Informationen finden Sie in den Folgenden Beschreibungen für den parameter dwFlags.

[in] lpPassword

Zeiger auf eine Konstante 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 durch lpUserIDangegebenen 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.

[in] lpUserId

Zeigen Sie auf eine Konstante NULL--terminated-Zeichenfolge, die einen Benutzernamen zum Herstellen der Verbindung angibt.

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

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

[in] dwFlags

Satz von Bitkennzeichnungen, die die Verbindung beschreiben. Dieser Parameter kann eine beliebige Kombination der folgenden Werte sein.

Wert	Bedeutung
CONNECT_INTERACTIVE	Wenn dieses Kennzeichen festgelegt ist, kann das Betriebssystem für Authentifizierungszwecke mit dem Benutzer interagieren.
CONNECT_PROMPT	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.
CONNECT_REDIRECT	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 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 vorherigen Versionen Laufwerkbuchstaben zugewiesen wurden, die mit C: beginnen und mit Z:enden.
CONNECT_UPDATE_PROFILE	Dieses Flag weist das Betriebssystem an, die Netzwerkressourcenverbindung zu speichern. Wenn diese Bitkennzeichnung festgelegt ist, versucht das Betriebssystem automatisch, die Verbindung wiederherzustellen, wenn sich der Benutzer anmeldet. Das System 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 lpLocalName-NULL- ist oder wenn sie auf eine leere Zeichenfolge zeigt.) Wenn diese Bitkennzeichnung 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 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.
CONNECT_CMD_SAVECRED	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.

[out] lpAccessName

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

Wenn dieser Parameter angegeben ist und der lpLocalName Member 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 CONNECT_REDIRECT Wert festgelegt ist, empfängt dieser Puffer den Namen des umgeleiteten lokalen Geräts.

Andernfalls ist der name, der in den Puffer kopiert wurde, der einer Remoteressource entspricht. Wenn angegeben, muss dieser Puffer mindestens so groß sein wie die Zeichenfolge, auf die vom lpRemoteName Member verwiesen wird.

[in, out] lpBufferSize

Zeiger auf eine Variable, die die Größe des lpAccessName- Puffers in Zeichen angibt. Wenn der Aufruf fehlschlägt, da 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 des ERROR_MORE_DATA Fehlercodes 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 Kennzeichen festgelegt ist, wurde die Verbindung mit einer lokalen Geräteumleitung hergestellt. Wenn der lpAccessName Parameter auf einen Puffer verweist, wird der name des lokalen Geräts 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 durch lpLocalName angegebene Wert ist ungültig.
ERROR_BAD_NET_NAME	Der vom lpRemoteName Member angegebene Wert ist für einen Netzwerkressourcenanbieter nicht zulässig, da der Ressourcenname ungültig ist oder weil die benannte Ressource nicht gefunden werden kann.
ERROR_BAD_PROVIDER	Der vom lpProvider Member angegebene Wert stimmt nicht mit einem Anbieter überein.
ERROR_CANCELLED	Der Versuch, die Verbindung herzustellen, wurde vom Benutzer über ein Dialogfeld von einem der Netzwerkressourcenanbieter oder von einer aufgerufenen Ressource abgebrochen.
ERROR_EXTENDED_ERROR	Es ist ein netzwerkspezifischer Fehler aufgetreten. Rufen Sie zum Abrufen einer Beschreibung des Fehlers die WNetGetLastError--Funktion auf.
ERROR_INVALID_ADDRESS	Der Aufrufer, der in einem Zeiger an einen Puffer übergeben wurde, auf den nicht zugegriffen werden konnte.
ERROR_INVALID_PARAMETER	Dieser Fehler ist ein Ergebnis einer der folgenden Bedingungen: Das element lpRemoteName ist NULL-. Darüber hinaus ist lpAccessName nicht NULL-, aber lpBufferSize- ist entweder NULL- oder Punkt auf Null. Das dwType Member ist weder RESOURCETYPE_DISK noch RESOURCETYPE_PRINT. Darüber hinaus wird entweder CONNECT_REDIRECT in dwFlags- festgelegt, und lpLocalName- ist NULL-, oder die Verbindung ist mit einem Netzwerk verbunden, 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 lpAccessName Puffer 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 lpRemoteNameverweist, oder den Namen der verbindungsfähigen Ressource, auf deren Alias durch lpRemoteNameverweist. Wenn dieser Fehler zurückgegeben wird, wurde keine Verbindung hergestellt.
ERROR_NO_MORE_ITEMS	Das Betriebssystem kann keine lokale Umleitung automatisch 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 wird oder weil der angegebene Ressourcenname nicht erkannt wird.
ERROR_NO_NETWORK	Das Netzwerk ist nicht verfügbar.

Bemerkungen

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 die 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. 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 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.

Anmerkung

Der winnetwk.h-Header definiert WNetUseConnection als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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