NetShareGetInfo-Funktion (lmshare.h)

Artikel
08/24/2023

Ruft Informationen zu einer bestimmten freigegebenen Ressource auf einem Server ab.

Syntax

NET_API_STATUS NET_API_FUNCTION NetShareGetInfo(
  [in]  LMSTR  servername,
  [in]  LMSTR  netname,
  [in]  DWORD  level,
  [out] LPBYTE *bufptr
);

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] netname

Zeiger auf eine Zeichenfolge, die den Namen der Freigabe angibt, für die Informationen zurückgegeben werden sollen.

[in] level

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

Wert	Bedeutung
0	Gibt den Freigabenamen zurück. Der bufptr-Parameter verweist auf eine SHARE_INFO_0-Struktur .
1	Gibt Informationen zur freigegebenen Ressource zurück, einschließlich des Namens und typs der Ressource und eines Kommentars, der der Ressource zugeordnet ist. Der parameter bufptr verweist auf eine SHARE_INFO_1-Struktur .
2	Gibt Informationen zur freigegebenen Ressource zurück, einschließlich Name der Ressource, Typ und Berechtigungen, Kennwort und Anzahl der Verbindungen. Der bufptr-Parameter verweist auf eine SHARE_INFO_2-Struktur .
501	Gibt den Namen und Typ der Ressource sowie einen Kommentar zurück, der der Ressource zugeordnet ist. Der parameter bufptr verweist auf eine SHARE_INFO_501-Struktur .
502	Gibt Informationen zur freigegebenen Ressource zurück, einschließlich Name der Ressource, Typ und Berechtigungen, Anzahl der Verbindungen und andere relevante Informationen. Der bufptr-Parameter verweist auf eine SHARE_INFO_502-Struktur .
503	Gibt Informationen zur freigegebenen Ressource an, einschließlich des Namens der Ressource, des Typs und der Berechtigungen, der Anzahl der Verbindungen und anderer relevanter Informationen. Der buf-Parameter verweist auf eine SHARE_INFO_503-Struktur . Wenn der shi503_servername Member dieser Struktur "" lautet, gibt es keinen konfigurierten Servernamen. Windows Server 2003 und Windows XP:* Diese Informationsebene wird nicht unterstützt.
1005	Gibt einen Wert zurück, der angibt, ob die Freigabe das Stammvolume in einer Dfs-Struktur ist. Der bufptr-Parameter verweist auf eine SHARE_INFO_1005-Struktur .

[out] bufptr

Zeiger auf den Puffer, der die Daten empfängt. Das Format dieser Daten hängt vom Wert des level-Parameters ab. Weitere Informationen finden Sie unter Netzwerkverwaltungsfunktionspuffer.

Dieser Puffer wird vom System zugeordnet und muss mithilfe der NetApiBufferFree-Funktion freigegeben werden.

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 level-Parameter angegebene Wert ist ungültig.
ERROR_INVALID_PARAMETER	Der angegebene Parameter ist ungültig.
ERROR_NOT_ENOUGH_MEMORY	Nicht genügend Arbeitsspeicher ist verfügbar.
NERR_NetNameNotFound	Der Freigabename ist nicht vorhanden.

Hinweise

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

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

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

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 erreichen, die Sie durch Aufrufen der Netzwerkverwaltungsfreigabefunktionen erreichen können. Weitere Informationen finden Sie unter IADsFileShare.

Wenn 503 für den level-Parameter angegeben ist, muss der remote server, der im shi503_servername Member der SHARE_INFO_503-Struktur angegeben ist, mithilfe der NetServerTransportAddEx-Funktion an ein Transportprotokoll gebunden worden sein. Beim Aufruf von NetServerTransportAddEx muss entweder 2 oder 3 für den level-Parameter angegeben worden sein, und das flag SVTI2_SCOPED_NAME muss in der SERVER_TRANSPORT_INFO_2-Struktur für das Transportprotokoll angegeben worden sein.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie Informationen zu einer bestimmten freigegebenen Ressource mithilfe eines Aufrufs der NetShareGetInfo-Funktion abgerufen werden. Im Beispiel wird NetShareGetInfo aufgerufen, wobei die Informationsebene 502 ( SHARE_INFO_502) angegeben wird. Wenn der Aufruf erfolgreich ist, gibt der Code die abgerufenen Daten aus. Im Beispiel wird auch die IsValidSecurityDescriptor-Funktion aufgerufen, um den shi502_security_descriptor-Member zu überprüfen. Schließlich gibt das Beispiel den für den Informationspuffer zugeordneten 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;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL, lpszShare;
   //
   // Check command line arguments.
   //
   switch(argc)
   {
   case 3:
      lpszServer = lpszArgv[2];
   case 2:
      lpszShare = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareGetInfo sharename <servername>\n");
      return;
   }
   //
   // Call the NetShareGetInfo function, specifying level 502.
   //
   if((res = NetShareGetInfo (lpszServer,lpszShare,502,(LPBYTE *) &BufPtr)) == ERROR_SUCCESS)
   {
      //
      // Print the retrieved data.
      //
      printf("%S\t%S\t%u\n",BufPtr->shi502_netname, BufPtr->shi502_path, BufPtr->shi502_current_uses);
      //
      // Validate the value of the 
      //  shi502_security_descriptor member.
      //
      if (IsValidSecurityDescriptor(BufPtr->shi502_security_descriptor))
         printf("It has a valid Security Descriptor.\n");
      else
         printf("It does not have a valid Security Descriptor.\n");
      //
      // Free the allocated memory.
      //
      NetApiBufferFree(BufPtr);
   }
   else 
      printf("Error: %ld\n",res);
   return;
}

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