WNetGetUniversalNameA-Funktion (winnetwk.h)
Die WNetGetUniversalName-Funktion verwendet einen laufwerkbasierten Pfad für eine Netzwerkressource und gibt eine Informationsstruktur zurück, die eine universellere Form des Namens enthält.
Syntax
DWORD WNetGetUniversalNameA(
[in] LPCSTR lpLocalPath,
[in] DWORD dwInfoLevel,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpBufferSize
);
Parameter
[in] lpLocalPath
Ein Zeiger auf eine konstante NULL-Zeichenfolge, die ein laufwerksbasierter Pfad für eine Netzwerkressource ist.
Wenn Laufwerk H beispielsweise einer Netzwerklaufwerkfreigabe zugeordnet wurde und die netzwerkbasierte Ressource eine Datei mit dem Namen Sample.doc im Verzeichnis \Win32\Examples auf dieser Freigabe ist, wird der laufwerksbasierte Pfad H:\Win32\Examples\Sample.doc.
[in] dwInfoLevel
Der Strukturtyp, den die Funktion im Puffer speichert, auf den der lpBuffer-Parameter verweist. Dieser Parameter kann einer der folgenden Werte sein, die in der Winnetwk.h-Headerdatei definiert sind.
| Wert | Bedeutung |
|---|---|
|
Die Funktion speichert eine UNIVERSAL_NAME_INFO-Struktur im Puffer. |
|
Die Funktion speichert eine REMOTE_NAME_INFO-Struktur im Puffer. |
Die UNIVERSAL_NAME_INFO-Struktur verweist auf eine UNC-Namenszeichenfolge (Universal Naming Convention).
Die REMOTE_NAME_INFO-Struktur verweist auf eine UNC-Namenszeichenfolge und zwei zusätzliche Verbindungsinformationszeichenfolgen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[out] lpBuffer
Ein Zeiger auf einen Puffer, der die durch den dwInfoLevel-Parameter angegebene Struktur empfängt.
[in, out] lpBufferSize
Ein Zeiger auf eine Variable, der die Größe des Puffers in Bytes angibt, auf den der lpBuffer-Parameter verweist.
Wenn die Funktion erfolgreich ist, legt sie die Variable, auf die von lpBufferSize verwiesen wird, auf die Anzahl der im Puffer gespeicherten Bytes fest. Wenn die Funktion fehlschlägt, weil der Puffer zu klein ist, empfängt dieser Speicherort die erforderliche Puffergröße, und die Funktion gibt ERROR_MORE_DATA zurück.
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 |
|---|---|
|
Die Zeichenfolge, auf die der lpLocalPath-Parameter verweist, ist ungültig. |
|
Es besteht keine aktuelle Verbindung mit dem Remotegerät, es besteht jedoch eine gespeicherte (dauerhafte) Verbindung. |
|
Es ist ein netzwerkspezifischer Fehler aufgetreten. Verwenden Sie die WNetGetLastError-Funktion , um eine Beschreibung des Fehlers abzurufen. |
|
Der Puffer, auf den der lpBuffer-Parameter verweist, ist zu klein. Die Funktion legt die Variable, auf die der parameter lpBufferSize verweist, auf die erforderliche Puffergröße fest. Weitere Einträge sind bei nachfolgenden Aufrufen verfügbar. |
|
Der dwInfoLevel-Parameter ist auf UNIVERSAL_NAME_INFO_LEVEL festgelegt, aber der Netzwerkanbieter unterstützt keine UNC-Namen. (Keiner der Netzwerkanbieter unterstützt diese Funktion.) |
|
Keiner der Netzwerkanbieter erkennt, dass der lokale Name eine Verbindung aufweist. Das Netzwerk ist jedoch nicht für mindestens einen Anbieter verfügbar, zu dem die Verbindung möglicherweise gehört. |
|
Das Netzwerk ist nicht verfügbar. |
|
Das durch den lpLocalPath-Parameter angegebene Gerät wird nicht umgeleitet. |
Hinweise
Eine universelle Form eines lokalen laufwerkbasierten Pfads identifiziert eine Netzwerkressource auf eindeutige, computerunabhängige Weise. Der Name kann dann an Prozesse auf anderen Computern übergeben werden, sodass diese Prozesse Zugriff auf die Ressource erhalten können.
Die WNetGetUniversalName-Funktion unterstützt derzeit eine universelle Namensform: UNC-Namen (Universal Naming Convention), die wie folgt aussehen:
\\servername\sharename\path\file
Wenn sich das freigegebene Netzwerklaufwerk auf einem Server namens COOLSERVER befindet und der Freigabename HOTSHARE ist, lautet der UNC-Name für die Netzwerkressource, deren laufwerksbasierter Name H:\Win32\Examples\Sample.doc ist, anhand des Beispiels aus der vorherigen Beschreibung des parameters lpLocalPath :
\\coolserver\hotshare\win32\examples\sample.doc
Die UNIVERSAL_NAME_INFO-Struktur enthält einen Zeiger auf eine UNC-Namenszeichenfolge. Die REMOTE_NAME_INFO-Struktur enthält auch einen Zeiger auf eine UNC-Namenszeichenfolge sowie Zeiger auf zwei weitere nützliche Zeichenfolgen. Beispielsweise kann ein Prozess den lpszConnectionInfo-Member der REMOTE_NAME_INFO-Struktur an die WNetAddConnection2-Funktion übergeben, um ein lokales Gerät mit der Netzwerkressource zu verbinden. Dann kann der Prozess die Zeichenfolge anfügen, auf die der lpszRemainingPath-Member verweist, an die lokale Gerätezeichenfolge. Die resultierende Zeichenfolge kann an Funktionen übergeben werden, die einen laufwerksbasierten Pfad erfordern.
Der lpLocalPath-Parameter muss keinen Pfad oder eine Ressource angeben, die bereits auf einer Remoteressource vorhanden ist. Der Parameter lpLocalPath könnte beispielsweise einen Ordner, eine Hierarchie von Ordnern oder eine Datei angeben, die derzeit nicht vorhanden ist. Die WNetGetUniversalName-Funktion gibt in diesen Fällen eine universellere Form des Namens zurück.
Die Größe des Puffers, auf den der lpBuffer-Parameter verweist und im parameter lpBufferSize angegeben ist, muss viel größer sein als die Größe der REMOTE_NAME_INFO - oder UNIVERSAL_NAME_INFO-Strukturen . Der Puffer, auf den der lpBuffer-Parameter verweist, muss groß genug sein, um die UNC-Zeichenfolgen zu speichern, auf die die Member in den REMOTE_NAME_INFO - oder UNIVERSAL_NAME_INFO-Strukturen verweisen. Wenn die Puffergröße zu klein ist, schlägt die Funktion mit ERROR_MORE_DATA fehl, und die Variable, auf die vom parameter lpBufferSize verwiesen wird, gibt die erforderliche Puffergröße an.
Windows Server 2003 und Windows XP: Diese Funktion fragt die MS-DOS-Gerätenamespaces ab, die einer Anmeldesitzung zugeordnet sind, 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.
Beispiele
Im folgenden Codebeispiel wird veranschaulicht, wie Sie die WNetGetUniversalName-Funktion verwenden, um die universellen UNC-Namenzeichenfolgen abzurufen, die dem laufwerksbasierten Pfad für eine Netzwerkressource zugeordnet sind.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
WCHAR Buffer[1024];
DWORD dwBufferLength = 1024;
UNIVERSAL_NAME_INFO * unameinfo;
REMOTE_NAME_INFO *remotenameinfo;
wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);
unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,
(LPVOID) remotenameinfo, &dwBufferLength );
//
// If the call succeeds, print the user information.
//
if (dwRetVal == NO_ERROR) {
wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
}
else {
wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
}
}
Hinweis
Der winnetwk.h-Header definiert WNetGetUniversalName 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 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 |
Weitere Informationen
Ermitteln des Speicherorts einer Freigabe
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für