NetServerDiskEnum, fonction (lmserver.h)

Article
08/24/2023

La fonction NetServerDiskEnum récupère une liste de lecteurs de disque sur un serveur. La fonction retourne un tableau de chaînes de trois caractères (une lettre de lecteur, un signe deux-points et un caractère null de fin).

Syntaxe

NET_API_STATUS NET_API_FUNCTION NetServerDiskEnum(
  [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

Niveau d’informations requis. La valeur zéro est le seul niveau valide.

[out] bufptr

Pointeur vers la mémoire tampon qui reçoit les données. Les données sont un tableau de chaînes de trois caractères (une lettre de lecteur, un signe deux-points et un caractère null de fin). 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

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.

Note Ce paramètre est actuellement ignoré.

[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 à partir de la position actuelle du CV. 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 disque de serveur existante. Le handle doit être égal à zéro lors du premier appel et rester inchangé pour les appels suivants. Si le paramètre resume_handle est un pointeur 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 peut être l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_ACCESS_DENIED	L’utilisateur n’a pas accès aux informations demandées.
ERROR_INVALID_LEVEL	La valeur spécifiée pour le paramètre de niveau n’est pas valide.
ERROR_MORE_DATA	D’autres entrées sont disponibles. Spécifiez une mémoire tampon suffisamment grande pour recevoir toutes les entrées.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si un serveur distant a été spécifié dans le paramètre servername , si le serveur distant prend uniquement en charge les appels RPC distants à l’aide du mécanisme hérité du protocole d’accès à distance et que cette demande n’est pas prise en charge.

Notes

Seuls les membres du groupe local Administrateurs ou Opérateurs de serveur peuvent exécuter correctement la fonction NetServerDiskEnum sur un ordinateur distant.

Si vous programmez pour Active Directory, vous pourrez peut-être appeler certaines méthodes ADSI (Active Directory Service Interface) pour obtenir les mêmes résultats qu’en appelant les fonctions du serveur d’administration réseau. Pour plus d’informations, consultez les informations de référence sur l’interface IADsComputer .

Exemples

L’exemple de code suivant montre comment appeler la fonction NetServerDiskEnum pour récupérer une liste de lecteurs de disque sur un serveur. L’exemple appelle NetServerDiskEnum, en spécifiant le niveau d’informations 0 (obligatoire). S’il existe des entrées à retourner et que l’utilisateur a accès aux informations, il imprime une liste des lecteurs, au format d’une chaîne de trois caractères : une lettre de lecteur, un signe deux-points et un caractère null de fin. L’exemple affiche également le nombre total d’entrées disponibles et un indicateur sur le nombre d’entrées réellement énumérées. Enfin, l’exemple de code libère la mémoire allouée pour la mémoire tampon.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h> 
#include <lm.h>

#pragma comment(lib, "netapi32.lib")

int wmain(int argc, wchar_t *argv[])
{
   const int ENTRY_SIZE = 3; // Drive letter, colon, NULL
   LPTSTR pBuf = NULL;
   DWORD dwLevel = 0; // level must be zero
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;
   LPWSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = (LPTSTR) argv[1];
   //
   // Call the NetServerDiskEnum function.
   //
   nStatus = NetServerDiskEnum(pszServerName,
                               dwLevel,
                               (LPBYTE *) &pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               NULL);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPTSTR pTmpBuf;

      if ((pTmpBuf = pBuf) != NULL)
      {
         DWORD i;
         DWORD dwTotalCount = 0;
         //
         // Loop through the entries.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               // On a remote computer, only members of the
               //  Administrators or the Server Operators 
               //  local group can execute NetServerDiskEnum.
               //
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Print drive letter, colon, NULL for each drive;
            //   the number of entries actually enumerated; and
            //   the total number of entries available.
            //
            fwprintf(stdout, L"\tDisk: %S\n", pTmpBuf);

            pTmpBuf += ENTRY_SIZE;
            dwTotalCount++;
         }

         fprintf(stderr, "\nEntries enumerated: %d\n", dwTotalCount);
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Spécifications


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