NetShareEnum-Funktion (lmshare.h)

Artikel
08/24/2023

Ruft Informationen zu jeder freigegebenen Ressource auf einem Server ab.

Sie können auch die WNetEnumResource-Funktion verwenden, um Ressourceninformationen abzurufen. WNetEnumResource listet jedoch keine ausgeblendeten Freigaben oder benutzer auf, die mit einer Freigabe verbunden sind.

Syntax

NET_API_STATUS NET_API_FUNCTION NetShareEnum(
  [in]      LMSTR   servername,
  [in]      DWORD   level,
  [out]     LPBYTE  *bufptr,
  [in]      DWORD   prefmaxlen,
  [out]     LPDWORD entriesread,
  [out]     LPDWORD totalentries,
  [in, out] LPDWORD 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.

[in] level

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

Wert	Bedeutung
0	Gibt Freigabenamen zurück. Der bufptr-Parameter verweist auf ein Array von SHARE_INFO_0 Strukturen.
1	Gibt Informationen zu freigegebenen Ressourcen zurück, einschließlich des Namens und Typs der Ressource und eines Kommentars, der der Ressource zugeordnet ist. Der bufptr-Parameter verweist auf ein Array von SHARE_INFO_1 Strukturen.
2	Gibt Informationen zu freigegebenen Ressourcen zurück, einschließlich Name der Ressource, Typ und Berechtigungen, Kennwort und Anzahl der Verbindungen. Der bufptr-Parameter verweist auf ein Array von SHARE_INFO_2 Strukturen.
502	Gibt Informationen zu freigegebenen Ressourcen zurück, einschließlich Name der Ressource, Typ und Berechtigungen, Anzahl der Verbindungen und andere relevante Informationen. Der bufptr-Parameter verweist auf ein Array von SHARE_INFO_502 Strukturen. Freigaben aus verschiedenen Bereichen werden nicht zurückgegeben. Weitere Informationen zum Bereich finden Sie im Abschnitt Hinweise der Dokumentation für die NetServerTransportAddEx-Funktion .
503	Gibt Informationen zu freigegebenen Ressourcen zurück, einschließlich des Namens der Ressource, des Typs und der Berechtigungen, der Anzahl der Verbindungen und anderer relevanter Informationen. Der bufptr-Parameter verweist auf ein Array von SHARE_INFO_503 Strukturen. Freigaben aus allen Bereichen werden zurückgegeben. Wenn das shi503_servername Member dieser Struktur "" ist, ist kein konfigurierter Servername vorhanden, und die NetShareEnum-Funktion* listet Freigaben für alle namen ohne Bereich auf. Windows Server 2003 und Windows XP: Diese Informationsebene wird nicht unterstützt.

[out] bufptr

Zeiger auf den Puffer, der die Daten 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 hätten aufgezählt werden können. 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 verwendet wird, um eine vorhandene Freigabesuche fortzusetzen. Das Handle sollte beim ersten Aufruf 0 sein und für nachfolgende Aufrufe unverändert bleiben. Wenn resume_handleNULL ist, wird kein Fortsetzungshandle gespeichert.

Rückgabewert

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

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

Hinweise

Diese Funktion gilt nur für SMB-Freigaben (Server Message Block). Verwenden Sie für andere Freigabetypen, z. B. verteiltes Dateisystem (DFS) oder WebDAV-Freigaben, Windows-Netzwerkfunktionen (WNet), die alle Arten von Freigaben unterstützen.

Für interaktive Benutzer (Benutzer, die lokal auf dem Computer angemeldet sind) ist keine spezielle Gruppenmitgliedschaft erforderlich, um die NetShareEnum-Funktion auszuführen. Für nicht interaktive Benutzer ist die Gruppenmitgliedschaft Administrator, Power User, Print Operator oder Server Operator erforderlich, um die NetShareEnum-Funktion auf den Ebenen 2, 502 und 503 erfolgreich auszuführen. Für Aufrufe der Ebene 0 oder Ebene 1 ist keine spezielle Gruppenmitgliedschaft erforderlich.

Windows Server 2022: Für nicht interaktive Benutzer ist administrator, Access Control Assistance Operators oder server operator group membership erforderlich, um die NetShareEnum-Funktion auf den Ebenen 2, 502 und 503 erfolgreich auszuführen.

Windows Server 2003 und Windows XP: Für alle Benutzer ist eine Administrator-, Power User-, Druckoperator- oder Serveroperator-Gruppenmitgliedschaft erforderlich, um die NetShareEnum-Funktion auf den Ebenen 2 und 502 erfolgreich auszuführen.

Um einen Wert abzurufen, der angibt, ob eine Freigabe das Stammvolume in einer DFS-Struktur ist, müssen Sie die NetShareGetInfo-Funktion aufrufen und die Informationsebene 1005 angeben.

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dieselbe Funktionalität zu erzielen, die Sie durch aufrufen der Netzwerkverwaltungsfreigabefunktionen erreichen können. Weitere Informationen finden Sie unter IADsFileShare.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Mithilfe eines Aufrufs der NetShareEnum-Funktion Informationen zu jeder freigegebenen Ressource auf einem Server abgerufen werden. Im Beispiel wird NetShareEnum aufgerufen, wobei die Informationsebene 502 (SHARE_INFO_502) angegeben wird. Wenn der Aufruf erfolgreich ist, durchläuft der Code die Einträge und gibt Informationen zu jeder Freigabe aus. Im Beispiel wird auch die IsValidSecurityDescriptor-Funktion aufgerufen, um den shi502_security_descriptor-Member zu überprüfen. Schließlich gibt das Codebeispiel den Für den Informationspuffer zugewiesenen Arbeitsspeicher frei.

#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>

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

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr,p;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL;
   DWORD er=0,tr=0,resume=0, i;

   switch(argc)
   {
   case 2:
      lpszServer = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareEnum <servername>\n");
      return;
   }
   //
   // Print a report header.
   //
   printf("Share:              Local Path:                   Uses:   Descriptor:\n");
   printf("---------------------------------------------------------------------\n");
   //
   // Call the NetShareEnum function; specify level 502.
   //
   do // begin do
   {
      res = NetShareEnum (lpszServer, 502, (LPBYTE *) &BufPtr, MAX_PREFERRED_LENGTH, &er, &tr, &resume);
      //
      // If the call succeeds,
      //
      if(res == ERROR_SUCCESS || res == ERROR_MORE_DATA)
      {
         p=BufPtr;
         //
         // Loop through the entries;
         //  print retrieved data.
         //
         for(i=1;i<=er;i++)
         {
            printf("%-20S%-30S%-8u",p->shi502_netname, p->shi502_path, p->shi502_current_uses);
            //
            // Validate the value of the 
            //  shi502_security_descriptor member.
            //
            if (IsValidSecurityDescriptor(p->shi502_security_descriptor))
               printf("Yes\n");
            else
               printf("No\n");
            p++;
         }
         //
         // Free the allocated buffer.
         //
         NetApiBufferFree(BufPtr);
      }
      else 
         printf("Error: %ld\n",res);
   }
   // Continue to call NetShareEnum while 
   //  there are more entries. 
   // 
   while (res==ERROR_MORE_DATA); // end do
   return;
}

Anforderungen


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