NetDfsEnum-Funktion (lmdfs.h)

Artikel
08/24/2023

Listet die DFS-Namespaces (Distributed File System) auf, die auf einem Server oder DFS-Links eines von einem Server gehosteten Namespace gehostet werden.

Syntax

NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
  [in]      LPWSTR  DfsName,
  [in]      DWORD   Level,
  [in]      DWORD   PrefMaxLen,
  [out]     LPBYTE  *Buffer,
  [out]     LPDWORD EntriesRead,
  [in, out] LPDWORD ResumeHandle
);

Parameter

[in] DfsName

Zeiger auf eine Zeichenfolge, die den UNC-Pfad (Universal Naming Convention) des DFS-Stamms oder -Links angibt.

Wenn Sie die Informationsebene 200 (DFS_INFO_200) angeben, ist dieser Parameter der Name einer Domäne. Wenn Sie die Informationsebene 300 (DFS_INFO_300) angeben, ist dieser Parameter der Name eines Servers.

Für alle anderen Ebenen kann die Zeichenfolge eine der folgenden vier Formen aufweisen:

Servername\DfsName

oder

Servername\DfsName\link_path

Dabei ist ServerName der Name des Stammzielservers, der den eigenständigen DFS-Namespace hostet; Dfsname ist der Name des DFS-Namespace. und link_path ist ein DFS-Link.

Die Zeichenfolge kann auch folgende Formen aufweisen:

Domänenname\DomainName\DomDfsName

oder

Domänenname\DomDfsName\link_path

Dabei ist DomainName der Name der Domäne, die den domänenbasierten DFS-Stamm hostet; DomDfsName ist der Name des DFS-Namespace. und link_path ist ein DFS-Link.

Sie können der Zeichenfolge mit umgekehrten Schrägstrichen (\) vorangehen, sie sind jedoch nicht erforderlich. Dieser Parameter ist erforderlich.

[in] Level

Gibt die Informationsebene der Anforderung an. Dieser Parameter kann einen der folgenden Werte annehmen.

1

Gibt den Namen des DFS-Stamms und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_1 Strukturen.

2

Gibt den Namen, den Kommentar, status und die Anzahl der Ziele für den DFS-Stamm und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_2 Strukturen.

3

Gibt den Namen, den Kommentar, die status, die Anzahl der Ziele und Informationen zu jedem Ziel für den DFS-Stamm und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_3 Strukturen.

4

Geben Sie den Namen, den Kommentar, die status, die GUID, das Timeout, die Anzahl der Ziele und Informationen zu jedem Ziel für den DFS-Stamm und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_4 Strukturen.

5

Gibt den Namen, status, GUID, Timeout, Eigenschaftsflags, Metadatengröße und Anzahl der Ziele für einen DFS-Stamm und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_5 Strukturen.

6

Gibt den Namen, status, GUID, Timeout, Eigenschaftsflags, Metadatengröße, DFS-Zielinformationen für einen Stamm oder Link und eine Liste der DFS-Ziele zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_6 Strukturen.

8

Geben Sie name, status, GUID, Timeout, Eigenschaftsflags, Metadatengröße, Anzahl der Ziele und Sicherheitsbeschreibungen für den Linkreparsepunkt für einen DFS-Stamm und alle Links unter dem Stamm zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_8 Strukturen.

9

Geben Sie name, status, GUID, Timeout, Eigenschaftsflags, Metadatengröße, DFS-Zielinformationen, Sicherheitsbeschreibungen für Den Analysepunkt von Links und eine Liste der DFS-Ziele für einen Stamm oder Link zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_9 Strukturen.

200

Gibt die Liste der domänenbasierten DFS-Namespaces in der Domäne zurück. Der Parameter Buffer verweist auf ein Array von DFS_INFO_200 Strukturen.

300

Gibt die eigenständigen und domänenbasierten DFS-Namespaces zurück, die von einem Server gehostet werden. Der Parameter Buffer verweist auf ein Array von DFS_INFO_300 Strukturen.

[in] PrefMaxLen

Gibt die Anzahl der Bytes an, die von dieser Funktion im Informationsstrukturpuffer zurückgegeben werden sollen. Wenn dieser Parameter MAX_PREFERRED_LENGTH ist, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Parameter wird ignoriert, wenn Sie Ebene 200 oder Ebene 300 angeben.

[out] Buffer

Zeiger auf einen Puffer, der die angeforderten Informationsstrukturen empfängt. Das Format dieser Daten hängt vom Wert des Level-Parameters ab. Dieser Puffer wird vom System zugeordnet und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden.

[out] EntriesRead

Zeiger auf einen Wert, der die tatsächliche Anzahl der in der Antwort zurückgegebenen Einträge empfängt.

[in, out] ResumeHandle

Zeiger auf einen Wert, der ein Handle enthält, das zum Fortsetzen einer Enumeration verwendet werden soll, wenn mehr Daten verfügbar sind, als in einem einzelnen Aufruf dieser Funktion zurückgegeben werden können. Das Handle sollte beim ersten Aufruf null sein und für nachfolgende Aufrufe unverändert bleiben. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn keine weiteren Einträge zum Aufzählen verfügbar sind, wird der Rückgabewert ERROR_NO_MORE_ITEMS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode. Eine Liste der Fehlercodes finden Sie unter Systemfehlercodes.

Hinweise

Für die Verwendung der NetDfsEnum-Funktion ist keine spezielle Gruppenmitgliedschaft erforderlich.

Rufen Sie die NetDfsEnum-Funktion auf, wobei der ResumeHandle-Parameter auf 0 festgelegt ist, um die Enumeration zu beginnen. Um den Enumerationsvorgang fortzusetzen, rufen Sie diese Funktion mit der ResumeHandle auf, die vom vorherigen Aufruf von NetDfsEnum zurückgegeben wurde. Wenn diese Funktion nicht ERROR_NO_MORE_ITEMS zurückgibt, geben nachfolgende Aufrufe dieser API die verbleibenden Links zurück. Sobald ERROR_NO_MORE_ITEMS zurückgegeben wird, wurden alle verfügbaren DFS-Links abgerufen.

Die NetDfsEnum-Funktion weist den für den Informationsstrukturpuffer erforderlichen Arbeitsspeicher zu. Wenn Sie einen Betrag im PrefMaxLen-Parameter angeben, wird der von der Funktion zurückgegebene Arbeitsspeicher eingeschränkt. Die tatsächliche Größe des Arbeitsspeichers, den die NetDfsEnum-Funktion zuordnet, kann jedoch größer sein als der von Ihnen angegebene Betrag. Weitere Informationen finden Sie unter Längen des Netzwerkverwaltungsfunktionspuffers.

Aufgrund der Möglichkeit gleichzeitiger Updates für den DFS-Namespace sollte der Aufrufer nicht von Vollständigkeit oder Eindeutigkeit der ergebnisse ausgehen, die beim Fortsetzen eines Enumerationsvorgangs zurückgegeben werden.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie die DFS-Links in einem benannten DFS-Stamm mit einem Aufruf der NetDfsEnum-Funktion aufgelistet werden. Im Beispiel wird NetDfsEnum aufgerufen, wobei die Informationsebene 3 ( DFS_INFO_3) angegeben wird. Der Beispielcode durchläuft die Einträge und gibt die abgerufenen Daten und die status jedes Hostservers aus, auf den der DFS-Link verweist. Schließlich gibt das Beispiel den für den Informationspuffer zugeordneten Arbeitsspeicher frei.

#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

#pragma comment(lib, "Netapi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
    PDFS_INFO_3 pData, p;
    PDFS_STORAGE_INFO ps;
    DWORD er = 0, hResume = 0, res, i, j;

    if(argc < 2)
        wprintf(L"Syntax: %s \\\\DfsName\n", argv[0]);
    else
    {
        //
        // Call the NetDfsEnum function, specifying level 3.
        //
        res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);

        // Call NetDfsEnum until all available entries are returned.
        // NetDfsEnum will return ERROR_NO_MORE_ITEMS when all entries 
        // have been obtained.
        while (res == ERROR_SUCCESS)
        {
            p = pData;
            //
            // Loop through the entries; print the data.
            //
            for(i = 1; i <= er; i++)
            {
                printf("%-30S%u\n", p->EntryPath, p->NumberOfStorages);
                ps = p->Storage;
                //
                // Loop through each target.
                //
                for(j = 1; j <= p->NumberOfStorages; j++)
                {
                    //
                    // Print the status (Offline/Online) and the name 
                    // of each target referenced by the DFS link.
                    //
                    printf("    %S  ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"):TEXT("Online "));
                    printf("\\\\%S\\%S\n", ps->ServerName, ps->ShareName);
                    ps++;
                }
                p++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(pData);


            res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
        }


        if (res == ERROR_NO_MORE_ITEMS)
        {
            // the last of the entries have been processed.
            res = ERROR_SUCCESS;
            printf("Enumeration done\n");
        } 
        else 
        {
            // an error occurred.
            printf("Error: %u\n", res);
        }
    }
    return;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	lmdfs.h (include LmDfs.h, Lm.h)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll