Função NetServerDiskEnum (lmserver.h)
A função NetServerDiskEnum recupera uma lista de unidades de disco em um servidor. A função retorna uma matriz de cadeias de caracteres de três caracteres (uma letra de unidade, dois-pontos e um caractere nulo de terminação).
Sintaxe
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
Um 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
O nível de informações necessário. Um valor zero é o único nível válido.
[out] bufptr
Um ponteiro para o buffer que recebe os dados. Os dados são uma matriz de cadeias de caracteres de três caracteres (uma letra de unidade, dois-pontos e um caractere nulo de terminação). 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
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
Um ponteiro para um valor que recebe a contagem de elementos realmente enumerados.
[out] totalentries
Um 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
Um ponteiro para um valor que contém um identificador de currículo que é usado para continuar uma pesquisa de disco de servidor existente. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Se o parâmetro resume_handle for um ponteiro 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 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 é inválido. |
|
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas. |
|
Memória insuficiente disponível. |
|
A solicitação não terá suporte. Esse erro será retornado se um servidor remoto tiver sido especificado no parâmetro servername , o servidor remoto só oferecerá suporte a chamadas RPC remotas usando o mecanismo herdado do Protocolo de Acesso Remoto e essa solicitação não terá suporte. |
Comentários
Somente membros do grupo local Administradores ou Operadores de Servidor podem executar com êxito a função NetServerDiskEnum em um computador remoto.
Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter os mesmos resultados que você pode obter chamando as funções do servidor de gerenciamento de rede. Para obter mais informações, consulte a referência da interface IADsComputer .
Exemplos
O exemplo de código a seguir demonstra como chamar a função NetServerDiskEnum para recuperar uma lista de unidades de disco em um servidor. O exemplo chama NetServerDiskEnum, especificando o nível de informações 0 (obrigatório). Se houver entradas a serem retornadas e o usuário tiver acesso às informações, ele imprimirá uma lista das unidades, no formato de uma cadeia de caracteres de três caracteres: uma letra de unidade, dois-pontos e um caractere nulo de terminação. O exemplo também imprime o número total de entradas disponíveis e uma dica sobre o número de entradas realmente enumeradas. Por fim, o exemplo de código libera a memória alocada para o buffer.
#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 com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | lmserver.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
Funções de gerenciamento de rede