Função NetShareEnum (lmshare.h)
Recupera informações sobre cada recurso compartilhado em um servidor.
Você também pode usar a função WNetEnumResource para recuperar informações de recurso. No entanto, WNetEnumResource não enumera compartilhamentos ocultos ou usuários conectados a um compartilhamento.
Sintaxe
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
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
Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Retornar nomes de compartilhamento. O parâmetro bufptr aponta para uma matriz de estruturas de SHARE_INFO_0 . |
|
Retornar informações sobre recursos compartilhados, incluindo o nome e o tipo do recurso e um comentário associado ao recurso.
O parâmetro bufptr aponta para uma matriz de estruturas de SHARE_INFO_1 . |
|
Retornar informações sobre recursos compartilhados, incluindo nome do recurso, tipo e permissões, senha e número de conexões. O parâmetro bufptr aponta para uma matriz de estruturas de SHARE_INFO_2 . |
|
Retornar informações sobre recursos compartilhados, incluindo nome do recurso, tipo e permissões, número de conexões e outras informações pertinentes. O parâmetro bufptr aponta para uma matriz de estruturas SHARE_INFO_502 . Compartilhamentos de escopos diferentes não são retornados. Para obter mais informações sobre escopo, consulte a seção Comentários da documentação da função NetServerTransportAddEx . |
|
Retornar informações sobre recursos compartilhados, incluindo o nome do recurso, o tipo e as permissões, o número de conexões e outras informações pertinentes. O parâmetro bufptr aponta para uma matriz de estruturas SHARE_INFO_503 . Compartilhamentos de todos os escopos são retornados. Se o membro shi503_servername dessa estrutura for "*", não haverá nenhum nome de servidor configurado e a função NetShareEnum enumera compartilhamentos para todos os nomes nãocopados.
Windows Server 2003 e Windows XP: Não há suporte para esse nível de informação. |
[out] bufptr
Ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro de nível .
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
Especifica 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
Ponteiro para um valor que recebe a contagem de elementos realmente enumerados.
[out] totalentries
Ponteiro para um valor que recebe o número total de entradas que poderiam ter sido enumeradas. Observe que os aplicativos devem considerar esse valor apenas como uma dica.
[in, out] resume_handle
Ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa de compartilhamento existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se resume_handle for 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 será um código de erro do sistema. Para obter uma lista de códigos de erro, consulte Códigos de erro do sistema.
Comentários
Essa função se aplica somente aos compartilhamentos do SMB (Bloco de Mensagens do Servidor). Para outros tipos de compartilhamentos, como DFS (Sistema de Arquivos Distribuído) ou compartilhamentos WebDAV, use funções WNet (Rede Windows), que dão suporte a todos os tipos de compartilhamentos.
Para usuários interativos (usuários conectados localmente ao computador), nenhuma associação de grupo especial é necessária para executar a função NetShareEnum . Para usuários não interativos, a associação de grupo Administrador, Usuário do Power, Operador de Impressão ou Operador de Servidor é necessária para executar com êxito a função NetShareEnum nos níveis 2, 502 e 503. Nenhuma associação de grupo especial é necessária para chamadas de nível 0 ou nível 1.
Windows Server 2022: Para usuários não interativos, administrador, operadores de assistência Controle de Acesso ou associação de grupo operador de servidor são necessários para executar com êxito a função NetShareEnum nos níveis 2, 502 e 503.
Windows Server 2003 e Windows XP: Para todos os usuários, a associação de grupo Administrador, Usuário do Power, Operador de Impressão ou Operador de Servidor é necessária para executar com êxito a função NetShareEnum nos níveis 2 e 502.
Para recuperar um valor que indica se um compartilhamento é o volume raiz em uma estrutura de árvore DFS, você deve chamar a função NetShareGetInfo e especificar o nível de informações 1005.
Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter a mesma funcionalidade que você pode obter chamando as funções de compartilhamento de gerenciamento de rede. Para obter mais informações, consulte IADsFileShare.
Exemplos
O exemplo de código a seguir demonstra como recuperar informações sobre cada recurso compartilhado em um servidor usando uma chamada para a função NetShareEnum . O exemplo chama NetShareEnum, especificando o nível de informações 502 (SHARE_INFO_502). Se a chamada for bem-sucedida, o código passará pelas entradas e imprimirá informações sobre cada compartilhamento. O exemplo também chama a função IsValidSecurityDescriptor para validar o membro shi502_security_descriptor . Por fim, o exemplo de código libera a memória alocada para o buffer de informações.
#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 com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | lmshare.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
Funções de gerenciamento de rede
Visão geral do gerenciamento de rede