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-beendete Zeichenfolge, bei der es sich um einen laufwerkbasierten Pfad für eine Netzwerkressource handelt.

Wenn z. B. Laufwerk H einer Netzwerklaufwerkfreigabe zugeordnet wurde und die netzwerkressource von Interesse eine Datei mit dem Namen Sample.doc im Verzeichnis \Win32\Examples für diese Freigabe ist, wird der laufwerkbasierte Pfad H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

Der Typ der Struktur, auf die 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.

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 Byte angibt, auf den der lpBuffer-Parameter verweist.

Wenn die Funktion erfolgreich ist, legt sie die Variable fest, auf die durch lpBufferSize auf die Anzahl der im Puffer gespeicherten Bytes verweist. Wenn die Funktion fehlschlägt, da 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.

Bemerkungen

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 ein universelles Namensformular: Namen der universellen Benennungskonvention (UNC), die wie folgt aussehen:

\\servername\sharename\path\file 

Wenn sich das freigegebene Netzlaufwerk auf einem Server mit dem Namen COOLSERVER befindet und der Freigabename HOTSHARE ist, lautet das Beispiel aus der vorherigen Beschreibung des lpLocalPath Parameter, wenn sich das freigegebene Netzlaufwerk auf einem Server mit dem Namen COOLSERVER befindet und der Freigabename HOTSHARE ist, der UNC-Name für die Netzwerkressource, deren Laufwerksname H:\Win32\Examples\Sample.doc ist:

\\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 andere nützliche Zeichenfolgen. Beispielsweise kann ein Prozess die lpszConnectionInfo Element der REMOTE_NAME_INFO Struktur an die WNetAddConnection2--Funktion übergeben, um ein lokales Gerät mit der Netzwerkressource zu verbinden. Anschließend kann der Prozess die Zeichenfolge anfügen, auf die durch die lpszRemainingPath Member an die lokale Gerätezeichenfolge verwiesen wird. Die resultierende Zeichenfolge kann an Funktionen übergeben werden, die einen laufwerkbasierten Pfad erfordern.

Der parameter lpLocalPath muss keinen Pfad oder eine Ressource angeben, die bereits in einer Remoteressource vorhanden ist. Beispielsweise könnte der lpLocalPath Parameter angeben und 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 lpBufferSize Parameter angegeben ist, muss wesentlich 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 durch den parameter lpBufferSize verweist, 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 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.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Sie die funktion WNetGetUniversalName verwenden, um die universellen UNC-Namenszeichenfolgen abzurufen, die dem laufwerkbasierten 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);
    }
}

Anforderungen

Siehe auch

Bestimmen des Speicherorts einer Freigabe-

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2-

übersicht über Windows Networking (WNet)

Windows-Netzwerkfunktionen