NetShareEnum, fonction (lmshare.h)

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.

[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 gestionré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

Voir aussi

Fonctions de gestion réseau

Vue d’ensemble de la gestion du réseau

Fonctions de partage réseau

SHARE_INFO_0

SHARE_INFO_1

SHARE_INFO_2

SHARE_INFO_502

SHARE_INFO_503