NetShareEnum-Funktion (lmshare.h)

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.

[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

Weitere Informationen

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

Netzwerkfreigabefunktionen

SHARE_INFO_0

SHARE_INFO_1

SHARE_INFO_2

SHARE_INFO_502

SHARE_INFO_503