Función NetServerDiskEnum (lmserver.h)

Artículo
08/24/2023

La función NetServerDiskEnum recupera una lista de unidades de disco en un servidor. La función devuelve una matriz de cadenas de tres caracteres (una letra de unidad, dos puntos y un carácter nulo de terminación).

Sintaxis

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

Puntero a una cadena que especifica el nombre DNS o NetBIOS del servidor remoto en el que se va a ejecutar la función. Si este parámetro es NULL, se usa el equipo local.

[in] level

Nivel de información necesario. Un valor de cero es el único nivel válido.

[out] bufptr

Puntero al búfer que recibe los datos. Los datos son una matriz de cadenas de tres caracteres (una letra de unidad, dos puntos y un carácter NULO de terminación). El sistema asigna este búfer y debe liberarse mediante la función NetApiBufferFree . Tenga en cuenta que debe liberar el búfer incluso si se produce un error en la función con ERROR_MORE_DATA.

[in] prefmaxlen

Longitud máxima preferida de los datos devueltos, en bytes. Si especifica MAX_PREFERRED_LENGTH, la función asigna la cantidad de memoria necesaria para los datos. Si especifica otro valor en este parámetro, puede restringir el número de bytes que devuelve la función. Si el tamaño del búfer no es suficiente para contener todas las entradas, la función devuelve ERROR_MORE_DATA. Para obtener más información, consulte Búferes de funciones de administración de red y longitudes de búfer de funciones de administración de red.

Nota Este parámetro se omite actualmente.

[out] entriesread

Puntero a un valor que recibe el recuento de elementos enumerados realmente.

[out] totalentries

Puntero a un valor que recibe el número total de entradas que se podrían haber enumerado a partir de la posición de reanudación actual. Tenga en cuenta que las aplicaciones solo deben tener en cuenta este valor como sugerencia.

[in, out] resume_handle

Puntero a un valor que contiene un identificador de reanudación que se usa para continuar con una búsqueda de disco de servidor existente. El identificador debe ser cero en la primera llamada y dejar sin cambios para las llamadas posteriores. Si el parámetro resume_handle es un puntero NULL , no se almacena ningún identificador de reanudación.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El usuario no tiene acceso a la información pedida.
ERROR_INVALID_LEVEL	El valor especificado para el parámetro level no es válido.
ERROR_MORE_DATA	Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas.
ERROR_NOT_ENOUGH_MEMORY	Memoria insuficiente disponible.
ERROR_NOT_SUPPORTED	No se admite la solicitud. Este error se devuelve si se especificó un servidor remoto en el parámetro servername , el servidor remoto solo admite llamadas RPC remotas mediante el mecanismo del protocolo de acceso remoto heredado y no se admite esta solicitud.

Comentarios

Solo los miembros del grupo local Administradores o Operadores de servidor pueden ejecutar correctamente la función NetServerDiskEnum en un equipo remoto.

Si está programando para Active Directory, puede llamar a determinados métodos de interfaz de servicio de Active Directory (ADSI) para lograr los mismos resultados que puede lograr llamando a las funciones del servidor de administración de red. Para obtener más información, consulte la referencia de la interfaz IADsComputer .

Ejemplos

En el ejemplo de código siguiente se muestra cómo llamar a la función NetServerDiskEnum para recuperar una lista de unidades de disco en un servidor. El ejemplo llama a NetServerDiskEnum, especificando el nivel de información 0 (obligatorio). Si hay entradas que devolver y el usuario tiene acceso a la información, imprime una lista de las unidades, en el formato de una cadena de tres caracteres: una letra de unidad, dos puntos y un carácter nulo de terminación. En el ejemplo también se imprime el número total de entradas disponibles y una sugerencia sobre el número de entradas enumeradas realmente. Por último, el ejemplo de código libera la memoria asignada para el búfer.

#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


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	lmserver.h (include Lm.h)
Library	Netapi32.lib
Archivo DLL	Netapi32.dll