Função NetDfsEnum (lmdfs.h)
Enumera os namespaces do DFS (Sistema de Arquivos Distribuído) hospedados em um servidor ou links DFS de um namespace hospedado por um servidor.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
[in] LPWSTR DfsName,
[in] DWORD Level,
[in] DWORD PrefMaxLen,
[out] LPBYTE *Buffer,
[out] LPDWORD EntriesRead,
[in, out] LPDWORD ResumeHandle
);
Parâmetros
[in] DfsName
Ponteiro para uma cadeia de caracteres que especifica o caminho UNC (Convenção de Nomenclatura Universal) da raiz ou link do DFS.
Quando você especifica o nível de informações 200 (DFS_INFO_200), esse parâmetro é o nome de um domínio. Quando você especifica o nível de informações 300 (DFS_INFO_300), esse parâmetro é o nome de um servidor.
Para todos os outros níveis, a cadeia de caracteres pode estar em uma das quatro formas a seguir:
Servername\DfsName
ou
Servername\DfsName\link_path
em que ServerName é o nome do servidor de destino raiz que hospeda o namespace dfs autônomo; Dfsname é o nome do namespace do DFS; e link_path é um link do DFS.
A cadeia de caracteres também pode ser dos seguintes formulários:
Domainname\DomainName\DomDfsName
ou
Domainname\DomDfsName\link_path
em que DomainName é o nome do domínio que hospeda a raiz DFS baseada em domínio; DomDfsName é o nome do namespace do DFS; e link_path é um link do DFS.
Você pode preceder a cadeia de caracteres com barras invertidas (\), mas elas não são necessárias. Este parâmetro é necessário.
[in] Level
Especifica o nível de informações da solicitação. Esse parâmetro pode usar um dos valores a seguir.
1
Retorne o nome da raiz dfs e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_1 .
2
Retorne o nome, o comentário, status e o número de destinos para a raiz do DFS e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_2 .
3
Retorne o nome, o comentário, status, o número de destinos e as informações sobre cada destino para a raiz do DFS e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_3 .
4
Retorne o nome, o comentário, o status, o GUID, o tempo limite, o número de destinos e as informações sobre cada destino para a raiz do DFS e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_4 .
5
Retorne o nome, status, GUID, tempo limite, sinalizadores de propriedade, tamanho dos metadados e número de destinos para uma raiz dfs e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_5 .
6
Retorne o nome, status, GUID, tempo limite, sinalizadores de propriedade, tamanho dos metadados, informações de destino do DFS para uma raiz ou link e uma lista de destinos dfs. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_6 .
8
Retorne o nome, status, GUID, tempo limite, sinalizadores de propriedade, tamanho dos metadados, número de destinos e descritores de segurança de ponto de nova análise de link para uma raiz DFS e todos os links na raiz. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_8 .
9
Retorne o nome, status, GUID, tempo limite, sinalizadores de propriedade, tamanho dos metadados, informações de destino do DFS, descritores de segurança de ponto de nova análise de link e uma lista de destinos dfs para uma raiz ou link. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_9 .
200
Retorne a lista de namespaces DFS baseados em domínio no domínio. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_200 .
300
Retornar os namespaces DFS autônomos e baseados em domínio hospedados por um servidor. O parâmetro Buffer aponta para uma matriz de estruturas de DFS_INFO_300 .
[in] PrefMaxLen
Especifica o número de bytes que devem ser retornados por essa função no buffer de estrutura de informações. Se esse parâmetro for MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Para obter mais informações, consulte a seção Comentários a seguir. Esse parâmetro será ignorado se você especificar o nível 200 ou o nível 300.
[out] Buffer
Ponteiro para um buffer que recebe as estruturas de informações solicitadas. O formato desses dados depende do valor do parâmetro Level . Esse buffer é alocado pelo sistema e deve ser liberado usando a função NetApiBufferFree .
[out] EntriesRead
Ponteiro para um valor que recebe o número real de entradas retornadas na resposta.
[in, out] ResumeHandle
Ponteiro para um valor que contém um identificador a ser usado para continuar uma enumeração quando mais dados estiverem disponíveis do que podem ser retornados em uma única chamada para essa função. O identificador deve ser zero na primeira chamada e deixado inalterado para chamadas subsequentes. Para obter mais informações, consulte a seção Comentários a seguir.
Valor retornado
Se a função for bem-sucedida, o valor retornado será NERR_Success.
Se não houver mais entradas disponíveis para serem enumeradas, o valor retornado será ERROR_NO_MORE_ITEMS.
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
Nenhuma associação de grupo especial é necessária para usar a função NetDfsEnum .
Chame a função NetDfsEnum com o parâmetro ResumeHandle definido como zero para iniciar a enumeração. Para continuar a operação de enumeração, chame essa função com ResumeHandle retornado pela chamada anterior para NetDfsEnum. Se essa função não retornar ERROR_NO_MORE_ITEMS, as chamadas subsequentes para essa API retornarão os links restantes. Depois que ERROR_NO_MORE_ITEMS é retornado, todos os links dfs disponíveis foram recuperados.
A função NetDfsEnum aloca a memória necessária para o buffer de estrutura de informações. Se você especificar um valor no parâmetro PrefMaxLen , ele restringirá a memória retornada pela função. No entanto, o tamanho real da memória alocada pela função NetDfsEnum pode ser maior do que a quantidade especificada. Para obter informações adicionais, consulte Comprimentos do buffer de função de gerenciamento de rede.
Devido à possibilidade de atualizações simultâneas para o namespace do DFS, o chamador não deve assumir a integridade ou a exclusividade dos resultados retornados ao retomar uma operação de enumeração.
Exemplos
O exemplo de código a seguir demonstra como listar os links do DFS em uma raiz DFS nomeada com uma chamada para a função NetDfsEnum . O exemplo chama NetDfsEnum, especificando o nível de informações 3 ( DFS_INFO_3). O código de exemplo percorre as entradas e imprime os dados recuperados e o status de cada servidor host referenciado pelo link do DFS. Por fim, o exemplo libera a memória alocada para o buffer de informações.
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>
#pragma comment(lib, "Netapi32.lib")
void wmain(int argc, wchar_t *argv[ ])
{
PDFS_INFO_3 pData, p;
PDFS_STORAGE_INFO ps;
DWORD er = 0, hResume = 0, res, i, j;
if(argc < 2)
wprintf(L"Syntax: %s \\\\DfsName\n", argv[0]);
else
{
//
// Call the NetDfsEnum function, specifying level 3.
//
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
// Call NetDfsEnum until all available entries are returned.
// NetDfsEnum will return ERROR_NO_MORE_ITEMS when all entries
// have been obtained.
while (res == ERROR_SUCCESS)
{
p = pData;
//
// Loop through the entries; print the data.
//
for(i = 1; i <= er; i++)
{
printf("%-30S%u\n", p->EntryPath, p->NumberOfStorages);
ps = p->Storage;
//
// Loop through each target.
//
for(j = 1; j <= p->NumberOfStorages; j++)
{
//
// Print the status (Offline/Online) and the name
// of each target referenced by the DFS link.
//
printf(" %S ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"):TEXT("Online "));
printf("\\\\%S\\%S\n", ps->ServerName, ps->ShareName);
ps++;
}
p++;
}
// Free the allocated buffer.
//
NetApiBufferFree(pData);
res = NetDfsEnum(argv[1], 3, MAX_PREFERRED_LENGTH, (LPBYTE *) &pData, &er, &hResume);
}
if (res == ERROR_NO_MORE_ITEMS)
{
// the last of the entries have been processed.
res = ERROR_SUCCESS;
printf("Enumeration done\n");
}
else
{
// an error occurred.
printf("Error: %u\n", res);
}
}
return;
}
Requisitos
| Cliente mínimo com suporte | Windows Vista |
| Servidor mínimo com suporte | Windows Server 2008 |
| Plataforma de Destino | Windows |
| Cabeçalho | lmdfs.h (inclua LmDfs.h, Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
Funções dfs (sistema de arquivos distribuído)