Função NetServerDiskEnum (lmserver.h)

A função NetServerDiskEnum recupera uma lista de unidades de disco em um servidor. A função retorna uma matriz de cadeias de caracteres de três caracteres (uma letra de unidade, dois-pontos e um caractere nulo de terminação).

Sintaxe

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

Parâmetros

[in] servername

Um ponteiro para uma cadeia de caracteres que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.

[in] level

O nível de informações necessário. Um valor zero é o único nível válido.

[out] bufptr

Um ponteiro para o buffer que recebe os dados. Os dados são uma matriz de cadeias de caracteres de três caracteres (uma letra de unidade, dois-pontos e um caractere nulo de terminação). Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA.

[in] prefmaxlen

O comprimento máximo preferencial dos dados retornados, em bytes. Se você especificar MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Se você especificar outro valor nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.

[out] entriesread

Um ponteiro para um valor que recebe a contagem de elementos realmente enumerados.

[out] totalentries

Um ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas da posição de currículo atual. Observe que os aplicativos devem considerar esse valor apenas como uma dica.

[in, out] resume_handle

Um ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa de disco de servidor existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se o parâmetro resume_handle for um ponteiro NULL , nenhum identificador de retomada será armazenado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NERR_Success.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro.

Comentários

Somente membros do grupo local Administradores ou Operadores de Servidor podem executar com êxito a função NetServerDiskEnum em um computador remoto.

Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter os mesmos resultados que você pode obter chamando as funções do servidor de gerenciamento de rede. Para obter mais informações, consulte a referência da interface IADsComputer .

Exemplos

O exemplo de código a seguir demonstra como chamar a função NetServerDiskEnum para recuperar uma lista de unidades de disco em um servidor. O exemplo chama NetServerDiskEnum, especificando o nível de informações 0 (obrigatório). Se houver entradas a serem retornadas e o usuário tiver acesso às informações, ele imprimirá uma lista das unidades, no formato de uma cadeia de caracteres de três caracteres: uma letra de unidade, dois-pontos e um caractere nulo de terminação. O exemplo também imprime o número total de entradas disponíveis e uma dica sobre o número de entradas realmente enumeradas. Por fim, o exemplo de código libera a memória alocada para o 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;
}

Requisitos

Confira também

IADsComputer

NetServerEnum

Funções de gerenciamento de rede

Visão geral do gerenciamento de rede

Funções de servidor