Función NetShareEnum (lmshare.h)

Artículo
03/14/2023

Recupera información sobre cada recurso compartido en un servidor.

También puede usar la función WNetEnumResource para recuperar información de recursos. Sin embargo, WNetEnumResource no enumera los recursos compartidos ocultos ni los usuarios conectados a un recurso compartido.

Sintaxis

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

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

Especifica el nivel de información de los datos. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
0	Devuelve nombres de recurso compartido. El parámetro bufptr apunta a una matriz de estructuras SHARE_INFO_0 .
1	Devuelve información sobre los recursos compartidos, incluido el nombre y el tipo del recurso, y un comentario asociado al recurso. El parámetro bufptr apunta a una matriz de estructuras SHARE_INFO_1 .
2	Devuelve información sobre los recursos compartidos, incluido el nombre del recurso, el tipo y los permisos, la contraseña y el número de conexiones. El parámetro bufptr apunta a una matriz de estructuras SHARE_INFO_2 .
502	Devuelve información sobre los recursos compartidos, incluido el nombre del recurso, el tipo y los permisos, el número de conexiones y otra información pertinente. El parámetro bufptr apunta a una matriz de estructuras SHARE_INFO_502 . No se devuelven recursos compartidos de ámbitos diferentes. Para obtener más información sobre el ámbito, vea la sección Comentarios de la documentación de la función NetServerTransportAddEx .
503	Devuelve información sobre los recursos compartidos, incluido el nombre del recurso, el tipo y los permisos, el número de conexiones y otra información pertinente. El parámetro bufptr apunta a una matriz de estructuras SHARE_INFO_503 . Se devuelven recursos compartidos de todos los ámbitos. Si el miembro shi503_servername de esta estructura es "", no hay ningún nombre de servidor configurado y la función NetShareEnum* enumera los recursos compartidos para todos los nombres sin ámbito. Windows Server 2003 y Windows XP: No se admite este nivel de información.

[out] bufptr

Puntero al búfer que recibe los datos. El formato de estos datos depende del valor del parámetro level .

El sistema asigna este búfer y se debe liberar 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

Especifica la 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 Network Management Function Buffers (Búferes de funciones de administración de red) y Network Management Function Buffer Lengths (Longitudes de búfer de funciones de administración de red).

[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. Tenga en cuenta que las aplicaciones deben considerar este valor solo como sugerencia.

[in, out] resume_handle

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

Valor devuelto

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

Si se produce un error en la función, el valor devuelto es un código de error del sistema. Para obtener una lista de códigos de error, consulte Códigos de error del sistema.

Comentarios

Esta función solo se aplica a los recursos compartidos del bloque de mensajes del servidor (SMB). Para otros tipos de recursos compartidos, como sistemas de archivos distribuidos (DFS) o recursos compartidos de WebDAV, use funciones de Redes de Windows (WNet), que admiten todos los tipos de recursos compartidos.

En el caso de los usuarios interactivos (usuarios que han iniciado sesión localmente en la máquina), no se requiere pertenencia a grupos especiales para ejecutar la función NetShareEnum . Para los usuarios no interactivos, se requiere la pertenencia al grupo Administrador, Usuario avanzado, Operador de impresión o Operador de servidor para ejecutar correctamente la función NetShareEnum en los niveles 2, 502 y 503. No se requiere pertenencia a grupos especiales para las llamadas de nivel 0 o 1.

Windows Server 2022: Para los usuarios no interactivos, el administrador, los operadores de asistencia Access Control o la pertenencia a grupos de operadores de servidor es necesario para ejecutar correctamente la función NetShareEnum en los niveles 2, 502 y 503.

Windows Server 2003 y Windows XP: Para todos los usuarios, se requiere la pertenencia al grupo Administrador, Usuario avanzado, Operador de impresión o Operador de servidor para ejecutar correctamente la función NetShareEnum en los niveles 2 y 502.

Para recuperar un valor que indica si un recurso compartido es el volumen raíz de una estructura de árbol DFS, debe llamar a la función NetShareGetInfo y especificar el nivel de información 1005.

Si está programando para Active Directory, puede llamar a determinados métodos de interfaz de servicio de Active Directory (ADSI) para lograr la misma funcionalidad que puede lograr llamando a las funciones de recurso compartido de administración de red. Para obtener más información, vea IADsFileShare.

Ejemplos

En el ejemplo de código siguiente se muestra cómo recuperar información sobre cada recurso compartido en un servidor mediante una llamada a la función NetShareEnum . El ejemplo llama a NetShareEnum, especificando el nivel de información 502 (SHARE_INFO_502). Si la llamada se realiza correctamente, el código recorre en bucle las entradas e imprime información sobre cada recurso compartido. El ejemplo también llama a la función IsValidSecurityDescriptor para validar el miembro shi502_security_descriptor . Por último, el ejemplo de código libera la memoria asignada para el búfer de información.

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

Requisitos


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