Funzione NetServerDiskEnum (lmserver.h)

Articolo
03/14/2023

La funzione NetServerDiskEnum recupera un elenco di unità disco in un server. La funzione restituisce una matrice di stringhe a tre caratteri (una lettera di unità, un punto e un carattere null di terminazione).

Sintassi

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

Parametri

[in] servername

Puntatore a una stringa che specifica il nome DNS o NetBIOS del server remoto in cui eseguire la funzione. Se questo parametro è NULL, viene usato il computer locale.

[in] level

Livello di informazioni necessarie. Un valore pari a zero è l'unico livello valido.

[out] bufptr

Puntatore al buffer che riceve i dati. I dati sono una matrice di stringhe a tre caratteri (una lettera di unità, un punto e un carattere null terminante). Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree . Si noti che è necessario liberare il buffer anche se la funzione ha esito negativo con ERROR_MORE_DATA.

[in] prefmaxlen

Lunghezza massima preferita dei dati restituiti, in byte. Se si specifica MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Se si specifica un altro valore in questo parametro, può limitare il numero di byte restituiti dalla funzione. Se le dimensioni del buffer non sono sufficienti per contenere tutte le voci, la funzione restituisce ERROR_MORE_DATA. Per altre informazioni, vedere Buffer delle funzioni di gestione della rete e lunghezze del buffer delle funzioni di gestione della rete.

Nota Questo parametro è attualmente ignorato.

[out] entriesread

Puntatore a un valore che riceve il conteggio degli elementi effettivamente enumerati.

[out] totalentries

Puntatore a un valore che riceve il numero totale di voci che potrebbero essere state enumerate dalla posizione di ripresa corrente. Si noti che le applicazioni devono considerare questo valore solo come hint.

[in, out] resume_handle

Puntatore a un valore che contiene un handle di ripresa usato per continuare una ricerca su disco del server esistente. L'handle deve essere zero nella prima chiamata e lasciato invariato per le chiamate successive. Se il parametro resume_handle è un puntatore NULL , non viene archiviato alcun handle di ripresa.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	L'utente non ha accesso alle informazioni richieste.
ERROR_INVALID_LEVEL	Il valore specificato per il parametro di livello non è valido.
ERROR_MORE_DATA	Sono disponibili altre voci. Specificare un buffer sufficiente per ricevere tutte le voci.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente disponibile.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se un server remoto è stato specificato nel parametro nome server , il server remoto supporta solo chiamate RPC remote usando il meccanismo di protocollo di accesso remoto legacy e questa richiesta non è supportata.

Commenti

Solo i membri del gruppo locale Administrators o Server Operator possono eseguire correttamente la funzione NetServerDiskEnum in un computer remoto.

Se si sta programmando per Active Directory, è possibile chiamare determinati metodi di Active Directory Service Interface (ADSI) per ottenere gli stessi risultati che è possibile ottenere chiamando le funzioni del server di gestione di rete. Per altre informazioni, vedere informazioni di riferimento sull'interfaccia IADsComputer .

Esempio

Nell'esempio di codice seguente viene illustrato come chiamare la funzione NetServerDiskEnum per recuperare un elenco di unità disco in un server. L'esempio chiama NetServerDiskEnum, specificando il livello di informazioni 0 (obbligatorio). Se sono presenti voci da restituire e l'utente ha accesso alle informazioni, stampa un elenco delle unità, nel formato di una stringa a tre caratteri: una lettera di unità, un punto e un carattere null terminante. L'esempio stampa anche il numero totale di voci disponibili e un suggerimento sul numero di voci effettivamente enumerate. Infine, l'esempio di codice libera la memoria allocata per il buffer.

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

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmserver.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll