Função NetSessionEnum (lmshare.h)
Fornece informações sobre sessões estabelecidas em um servidor.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetSessionEnum(
[in] LMSTR servername,
[in] LMSTR UncClientName,
[in] LMSTR username,
[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] UncClientName
Ponteiro para uma cadeia de caracteres que especifica o nome da sessão do computador para a qual as informações devem ser retornadas. Se esse parâmetro for NULL, NetSessionEnum retornará informações para todas as sessões de computador no servidor.
[in] username
Ponteiro para uma cadeia de caracteres que especifica o nome do usuário para o qual as informações devem ser retornadas. Se esse parâmetro for NULL, NetSessionEnum retornará informações para todos os usuários.
[in] level
Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Retorne o nome do computador que estabeleceu a sessão. O parâmetro bufptr aponta para uma matriz de estruturas de SESSION_INFO_0 . |
|
Retornar o nome do computador, o nome do usuário e abrir arquivos, pipes e dispositivos no computador. O parâmetro bufptr aponta para uma matriz de estruturas de SESSION_INFO_1 . |
|
Além das informações indicadas para o nível 1, retorne o tipo de cliente e como o usuário estabeleceu a sessão. O parâmetro bufptr aponta para uma matriz de estruturas de SESSION_INFO_2 . |
|
Retorne o nome do computador, o nome do usuário e os horários ativos e ociosos da sessão. O parâmetro bufptr aponta para uma matriz de estruturas de SESSION_INFO_10 . |
|
Retornar o nome do computador; nome do usuário; abrir arquivos, pipes e dispositivos no computador; e o nome do transporte que o cliente está usando. O parâmetro bufptr aponta para uma matriz de estruturas SESSION_INFO_502 . |
[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 da posição de currículo atual. 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 sessão existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se resume_handle for NULL, nenhum identificador de currículo 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.
| Código de retorno | Descrição |
|---|---|
|
O usuário não tem acesso às informações solicitadas. |
|
O valor especificado para o parâmetro de nível não é válido. |
|
O parâmetro especificado não é válido. |
|
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas. |
|
Memória insuficiente disponível. |
|
Uma sessão não existe com o nome do computador. |
|
O nome do computador não é válido. |
|
Não foi possível encontrar o nome de usuário. |
Comentários
Somente membros do grupo local Administradores ou Operadores de Servidor podem executar com êxito a função NetSessionEnum no nível 1 ou nível 2.
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 sessão de gerenciamento de rede. Para obter mais informações, consulte IADsSession e IADsFileServiceOperations.
Exemplos
O exemplo de código a seguir demonstra como recuperar informações sobre sessões atuais usando uma chamada para a função NetSessionEnum . O exemplo chama NetSessionEnum, especificando o nível de informações 10 ( SESSION_INFO_10). O exemplo percorre as entradas e imprime as informações recuperadas. Por fim, o código imprime o número total de sessões enumeradas e libera a memória alocada para o buffer de informações.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "Netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t *argv[])
{
LPSESSION_INFO_10 pBuf = NULL;
LPSESSION_INFO_10 pTmpBuf;
DWORD dwLevel = 10;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
LPTSTR pszServerName = NULL;
LPTSTR pszClientName = NULL;
LPTSTR pszUserName = NULL;
NET_API_STATUS nStatus;
//
// Check command line arguments.
//
if (argc > 4)
{
wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
exit(1);
}
if (argc >= 2)
pszServerName = argv[1];
if (argc >= 3)
pszClientName = argv[2];
if (argc == 4)
pszUserName = argv[3];
//
// Call the NetSessionEnum function, specifying level 10.
//
do // begin do
{
nStatus = NetSessionEnum(pszServerName,
pszClientName,
pszUserName,
dwLevel,
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the retrieved data.
//
wprintf(L"\n\tClient: %s\n", pTmpBuf->sesi10_cname);
wprintf(L"\tUser: %s\n", pTmpBuf->sesi10_username);
printf("\tActive: %d\n", pTmpBuf->sesi10_time);
printf("\tIdle: %d\n", pTmpBuf->sesi10_idle_time);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, indicate a system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated memory.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
//
// Continue to call NetSessionEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
// Check again for an allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of sessions enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
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