NetShareEnum, fonction (lmshare.h)

Article
08/24/2023

Récupère des informations sur chaque ressource partagée sur un serveur.

Vous pouvez également utiliser la fonction WNetEnumResource pour récupérer des informations sur les ressources. Toutefois, WNetEnumResource n’énumère pas les partages masqués ou les utilisateurs connectés à un partage.

Syntaxe

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
);

Paramètres

[in] servername

Pointeur vers une chaîne qui spécifie le nom DNS ou NetBIOS du serveur distant sur lequel la fonction doit s’exécuter. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

[in] level

Spécifie le niveau d’informations des données. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
0	Renvoyer des noms de partage. Le paramètre bufptr pointe vers un tableau de structures SHARE_INFO_0 .
1	Retournez des informations sur les ressources partagées, notamment le nom et le type de la ressource, ainsi qu’un commentaire associé à la ressource. Le paramètre bufptr pointe vers un tableau de structures SHARE_INFO_1 .
2	Retournez des informations sur les ressources partagées, notamment le nom de la ressource, le type et les autorisations, le mot de passe et le nombre de connexions. Le paramètre bufptr pointe vers un tableau de structures SHARE_INFO_2 .
502	Retourner des informations sur les ressources partagées, notamment le nom de la ressource, le type et les autorisations, le nombre de connexions et d’autres informations pertinentes. Le paramètre bufptr pointe vers un tableau de structures SHARE_INFO_502 . Les partages de différentes étendues ne sont pas retournés. Pour plus d’informations sur l’étendue, consultez la section Remarques de la documentation relative à la fonction NetServerTransportAddEx .
503	Retournez des informations sur les ressources partagées, notamment le nom de la ressource, le type et les autorisations, le nombre de connexions et d’autres informations pertinentes. Le paramètre bufptr pointe vers un tableau de structures SHARE_INFO_503 . Les partages de toutes les étendues sont retournés. Si le shi503_servername membre de cette structure est « * », il n’y a pas de nom de serveur configuré et la fonction NetShareEnum énumère les partages pour tous les noms non ciblés. Windows Server 2003 et Windows XP : Ce niveau d’informations n’est pas pris en charge.

[out] bufptr

Pointeur vers la mémoire tampon qui reçoit les données. Le format de ces données dépend de la valeur du paramètre de niveau .

Cette mémoire tampon est allouée par le système et doit être libérée à l’aide de la fonction NetApiBufferFree . Notez que vous devez libérer la mémoire tampon même si la fonction échoue avec ERROR_MORE_DATA.

[in] prefmaxlen

Spécifie la longueur maximale préférée des données retournées, en octets. Si vous spécifiez MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour les données. Si vous spécifiez une autre valeur dans ce paramètre, cela peut limiter le nombre d’octets retournés par la fonction. Si la taille de la mémoire tampon est insuffisante pour contenir toutes les entrées, la fonction retourne ERROR_MORE_DATA. Pour plus d’informations, consultez Mémoires tampons de fonction de gestion réseau et Longueurs de mémoire tampon des fonctions de gestion réseau.

[out] entriesread

Pointeur vers une valeur qui reçoit le nombre d’éléments réellement énumérés.

[out] totalentries

Pointeur vers une valeur qui reçoit le nombre total d’entrées qui auraient pu être énumérées. Notez que les applications doivent considérer cette valeur uniquement comme un indicateur.

[in, out] resume_handle

Pointeur vers une valeur qui contient un handle de CV utilisé pour poursuivre une recherche de partage existante. Le handle doit être égal à zéro lors du premier appel et rester inchangé pour les appels suivants. Si resume_handle a la valeur NULL, aucun handle de reprise n’est stocké.

Valeur retournée

Si la fonction réussit, la valeur de retour est NERR_Success.

Si la fonction échoue, la valeur de retour est un code d’erreur système. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur système.

Notes

Cette fonction s’applique uniquement aux partages SMB (Server Message Block). Pour d’autres types de partages, tels que les partages DFS (Distributed File System) ou WebDAV, utilisez les fonctions WNet (Windows Networking), qui prennent en charge tous les types de partages.

Pour les utilisateurs interactifs (utilisateurs connectés localement à l’ordinateur), aucune appartenance à un groupe spécial n’est requise pour exécuter la fonction NetShareEnum . Pour les utilisateurs non interactifs, l’appartenance administrateur, utilisateur actif, opérateur d’impression ou opérateur de serveur est requise pour exécuter correctement la fonction NetShareEnum aux niveaux 2, 502 et 503. Aucune appartenance à un groupe spécial n’est requise pour les appels de niveau 0 ou 1.

Windows Server 2022 : Pour les utilisateurs non interactifs, l’appartenance administrateur, opérateur d’assistance Access Control ou groupe opérateur de serveur est requise pour exécuter correctement la fonction NetShareEnum aux niveaux 2, 502 et 503.

Windows Server 2003 et Windows XP : Pour tous les utilisateurs, l’appartenance administrateur, utilisateur actif, opérateur d’impression ou groupe opérateur serveur est requise pour exécuter correctement la fonction NetShareEnum aux niveaux 2 et 502.

Pour récupérer une valeur qui indique si un partage est le volume racine dans une arborescence DFS, vous devez appeler la fonction NetShareGetInfo et spécifier le niveau d’informations 1005.

Si vous programmez pour Active Directory, vous pouvez peut-être appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir les mêmes fonctionnalités que celles que vous pouvez obtenir en appelant les fonctions de partage de gestion réseau. Pour plus d’informations, consultez IADsFileShare.

Exemples

L’exemple de code suivant montre comment récupérer des informations sur chaque ressource partagée sur un serveur à l’aide d’un appel à la fonction NetShareEnum . L’exemple appelle NetShareEnum, en spécifiant le niveau d’informations 502 (SHARE_INFO_502). Si l’appel réussit, le code boucle les entrées et imprime des informations sur chaque partage. L’exemple appelle également la fonction IsValidSecurityDescriptor pour valider le membre shi502_security_descriptor . Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon d’informations.

#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;
}

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmshare.h (inclure Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll