NetFileEnum-Funktion (lmshare.h)

Artikel
08/24/2023

Gibt Je nach den angegebenen Parametern Informationen zu einigen oder allen geöffneten Dateien auf einem Server zurück.

Syntax

NET_API_STATUS NET_API_FUNCTION NetFileEnum(
  [in]      LMSTR      servername,
  [in]      LMSTR      basepath,
  [in]      LMSTR      username,
  [in]      DWORD      level,
  [out]     LPBYTE     *bufptr,
  [in]      DWORD      prefmaxlen,
  [out]     LPDWORD    entriesread,
  [out]     LPDWORD    totalentries,
  [in, out] PDWORD_PTR resume_handle
);

Parameter

[in] servername

Zeiger auf eine Zeichenfolge, die den DNS- oder NetBIOS-Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

Diese Zeichenfolge ist Unicode, wenn _WIN32_WINNT oder FORCE_UNICODE definiert ist.

[in] basepath

Zeiger auf eine Zeichenfolge, die einen Qualifizierer für die zurückgegebenen Informationen angibt. Wenn dieser Parameter NULL ist, werden alle geöffneten Ressourcen aufgelistet. Wenn dieser Parameter nicht NULL ist, listet die Funktion nur Ressourcen auf, die den Wert des Basispfadparameters als Präfix aufweisen. (Ein Präfix ist der Teil eines Pfads, der vor einem umgekehrten Schrägstrich steht.)

Diese Zeichenfolge ist Unicode, wenn _WIN32_WINNT oder FORCE_UNICODE definiert ist.

[in] username

Zeiger auf eine Zeichenfolge, die den Namen des Benutzers oder den Namen der Verbindung angibt. Wenn die Zeichenfolge mit zwei umgekehrten Schrägstrichen ("\") beginnt, gibt sie den Namen der Verbindung an, z. B. "\127.0.0.1" oder "\ClientName". Der Teil des Verbindungsnamens nach den umgekehrten Schrägstrichen ist mit dem Clientnamen in der Sitzungsinformationsstruktur identisch, der von der NetSessionEnum-Funktion zurückgegeben wird. Wenn die Zeichenfolge nicht mit zwei umgekehrten Schrägstrichen beginnt, gibt sie den Namen des Benutzers an. Wenn dieser Parameter nicht NULL ist, dient sein Wert als Qualifizierer für die Enumeration. Die zurückgegebenen Dateien sind auf diejenigen beschränkt, die Benutzernamen oder Verbindungsnamen aufweisen, die mit dem Qualifizierer übereinstimmen. Wenn dieser Parameter NULL ist, wird kein Benutzername-Qualifizierer verwendet.

Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Parameter ist ein Zeiger auf eine Zeichenfolge, die den Namen des Benutzers angibt. Wenn dieser Parameter nicht NULL ist, dient sein Wert als Qualifizierer für die Enumeration. Die zurückgegebenen Dateien sind auf die Dateien beschränkt, die über Benutzernamen verfügen, die dem Qualifizierer entsprechen. Wenn dieser Parameter NULL ist, wird kein Benutzername-Qualifizierer verwendet.

Diese Zeichenfolge ist Unicode, wenn _WIN32_WINNT oder FORCE_UNICODE definiert ist.

[in] level

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

Wert	Bedeutung
2	Geben Sie die Dateiidentifikationsnummer zurück. Der bufptr-Parameter verweist auf ein Array von FILE_INFO_2 Strukturen.
3	Gibt Informationen zur Datei zurück. Der bufptr-Parameter verweist auf ein Array von FILE_INFO_3 Strukturen.

[out] bufptr

Zeiger auf die Adresse des Puffers, der die Informationen empfängt. Das Format dieser Daten hängt vom Wert des Ebenenparameters ab.

Dieser Puffer wird vom System zugewiesen und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden. Beachten Sie, dass Sie den Puffer auch dann freigeben müssen, wenn die Funktion mit ERROR_MORE_DATA fehlschlägt.

[in] prefmaxlen

Gibt die bevorzugte maximale Länge der zurückgegebenen Daten in Bytes an. Wenn Sie MAX_PREFERRED_LENGTH angeben, ordnet die Funktion den für die Daten erforderlichen Arbeitsspeicher zu. Wenn Sie in diesem Parameter einen anderen Wert angeben, kann die Anzahl der Von der Funktion zurückgegebenen Bytes eingeschränkt werden. Wenn die Puffergröße nicht ausreicht, um alle Einträge aufzunehmen, gibt die Funktion ERROR_MORE_DATA zurück. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer und Netzwerkverwaltungsfunktionspufferlängen.

[out] entriesread

Zeiger auf einen Wert, der die Anzahl der tatsächlich aufgelisteten Elemente empfängt.

[out] totalentries

Zeiger auf einen Wert, der die Gesamtanzahl von Einträgen empfängt, die aus der aktuellen Fortsetzenposition aufgezählt worden sein könnten. Beachten Sie, dass Anwendungen diesen Wert nur als Hinweis betrachten sollten.

[in, out] resume_handle

Zeiger auf einen Wert, der ein Resume-Handle enthält, das zum Fortsetzen einer vorhandenen Dateisuche verwendet wird. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn dieser Parameter NULL ist, wird kein Resume-Handle gespeichert.

Rückgabewert

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

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen.
ERROR_INVALID_LEVEL	Der für den Levelparameter angegebene Wert ist ungültig.
ERROR_MORE_DATA	Weitere Einträge sind verfügbar. Geben Sie einen ausreichend großen Puffer an, um alle Einträge zu empfangen.
ERROR_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar.
NERR_BufTooSmall	Der bereitgestellte Puffer ist zu klein.

Hinweise

Nur Mitglieder der lokalen Gruppe Administratoren oder Serveroperatoren können die NetFileEnum-Funktion erfolgreich ausführen.

Sie können die NetFileGetInfo-Funktion aufrufen, um Informationen zu einer bestimmten Öffnung einer Serverressource abzurufen.

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um die gleiche Funktionalität zu erzielen, die Sie durch aufrufen von NetFileEnum erreichen können. Weitere Informationen finden Sie unter IADsResource und IADsFileServiceOperations.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmshare.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll