Função NetShareGetInfo (lmshare.h)

Artigo
08/24/2023

Recupera informações sobre um recurso compartilhado específico em um servidor.

Sintaxe

NET_API_STATUS NET_API_FUNCTION NetShareGetInfo(
  [in]  LMSTR  servername,
  [in]  LMSTR  netname,
  [in]  DWORD  level,
  [out] LPBYTE *bufptr
);

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] netname

Ponteiro para uma cadeia de caracteres que especifica o nome do compartilhamento para o qual retornar informações.

[in] level

Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
0	Retornar o nome do compartilhamento. O parâmetro bufptr aponta para uma estrutura de SHARE_INFO_0 .
1	Retornar informações sobre o recurso compartilhado, incluindo o nome e o tipo do recurso e um comentário associado ao recurso. O parâmetro bufptr aponta para uma estrutura de SHARE_INFO_1 .
2	Retornar informações sobre o recurso compartilhado, incluindo nome do recurso, tipo e permissões, senha e número de conexões. O parâmetro bufptr aponta para uma estrutura de SHARE_INFO_2 .
501	Retorne o nome e o tipo do recurso e um comentário associado ao recurso. O parâmetro bufptr aponta para uma estrutura de SHARE_INFO_501 .
502	Retornar informações sobre o recurso compartilhado, 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 estrutura de SHARE_INFO_502 .
503	Especifica informações sobre o recurso compartilhado, 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 buf aponta para uma estrutura de SHARE_INFO_503 . Se o shi503_servername membro dessa estrutura for "", não haverá nenhum nome de servidor configurado. Windows Server 2003 e Windows XP:* Não há suporte para esse nível de informação.
1005	Retornar um valor que indica se o compartilhamento é o volume raiz em uma estrutura de árvore dfs. O parâmetro bufptr aponta para uma estrutura de SHARE_INFO_1005 .

[out] bufptr

Ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro de nível . Para obter mais informações, consulte Buffers de função de gerenciamento de rede.

Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree .

Retornar valor

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.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O usuário não tem acesso às informações solicitadas.
ERROR_INVALID_LEVEL	O valor especificado para o parâmetro de nível não é válido.
ERROR_INVALID_PARAMETER	O parâmetro especificado não é válido.
ERROR_NOT_ENOUGH_MEMORY	Memória insuficiente disponível.
NERR_NetNameNotFound	O nome do compartilhamento não existe.

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 NetShareGetInfo . 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 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 NetShareGetInfo nos níveis 2 e 502.

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.

Se 503 for especificado para o parâmetro de nível , o servidor remoto especificado no membro shi503_servername da estrutura SHARE_INFO_503 deverá ter sido associado a um protocolo de transporte usando a função NetServerTransportAddEx . Na chamada para NetServerTransportAddEx, 2 ou 3 devem ter sido especificados para o parâmetro de nível e o sinalizador SVTI2_SCOPED_NAME deve ter sido especificado na estrutura SERVER_TRANSPORT_INFO_2 para o protocolo de transporte.

Exemplos

O exemplo de código a seguir demonstra como recuperar informações sobre um recurso compartilhado específico usando uma chamada para a função NetShareGetInfo . O exemplo chama NetShareGetInfo, especificando o nível de informações 502 ( SHARE_INFO_502). Se a chamada for bem-sucedida, o código imprimirá os dados recuperados. O exemplo também chama a função IsValidSecurityDescriptor para validar o membro shi502_security_descriptor . Por fim, o exemplo 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;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL, lpszShare;
   //
   // Check command line arguments.
   //
   switch(argc)
   {
   case 3:
      lpszServer = lpszArgv[2];
   case 2:
      lpszShare = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareGetInfo sharename <servername>\n");
      return;
   }
   //
   // Call the NetShareGetInfo function, specifying level 502.
   //
   if((res = NetShareGetInfo (lpszServer,lpszShare,502,(LPBYTE *) &BufPtr)) == ERROR_SUCCESS)
   {
      //
      // Print the retrieved data.
      //
      printf("%S\t%S\t%u\n",BufPtr->shi502_netname, BufPtr->shi502_path, BufPtr->shi502_current_uses);
      //
      // Validate the value of the 
      //  shi502_security_descriptor member.
      //
      if (IsValidSecurityDescriptor(BufPtr->shi502_security_descriptor))
         printf("It has a valid Security Descriptor.\n");
      else
         printf("It does not have a valid Security Descriptor.\n");
      //
      // Free the allocated memory.
      //
      NetApiBufferFree(BufPtr);
   }
   else 
      printf("Error: %ld\n",res);
   return;
}

Requisitos

Requisito	Valor
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