Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Enumera gli spazi dei nomi DFS (Distributed File System) ospitati in un server o collegamenti DFS di uno spazio dei nomi ospitato da un server.
Sintassi
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
);
Parametri
[in] DfsName
Puntatore a una stringa che specifica il percorso UNC (Universal Naming Convention) della radice o del collegamento DFS.
Quando si specifica il livello di informazioni 200 (DFS_INFO_200), questo parametro è il nome di un dominio. Quando si specifica il livello di informazioni 300 (DFS_INFO_300), questo parametro è il nome di un server.
Per tutti gli altri livelli, la stringa può essere in una delle quattro forme seguenti:
Nomeserver\DfsName
oppure
Nomeserver\DfsName\link_path
dove ServerName è il nome del server di destinazione radice che ospita lo spazio dei nomi DFS autonomo; Dfsname è il nome dello spazio dei nomi DFS; e link_path è un collegamento DFS.
La stringa può essere anche dei moduli seguenti:
Domainname\DomainName\DomDfsName
oppure
Domainname\DomDfsName\link_path
dove DomainName è il nome del dominio che ospita la radice DFS basata su dominio; DomDfsName è il nome dello spazio dei nomi DFS; e link_path è un collegamento DFS.
È possibile precedere la stringa con barre rovesciata (\), ma non sono necessarie. Questo parametro è obbligatorio.
[in] Level
Specifica il livello di informazioni della richiesta. Questo parametro può avere uno dei valori seguenti.
1
Restituisce il nome della radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_1 .
2
Restituisce il nome, il commento, lo stato e il numero di destinazioni per la radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_2 .
3
Restituisce il nome, il commento, lo stato, il numero di destinazioni e le informazioni su ogni destinazione per la radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_3 .
4
Restituisce il nome, il commento, lo stato, il GUID, il timeout, il numero di destinazioni e le informazioni su ogni destinazione per la radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_4 .
5
Restituisce il nome, lo stato, il GUID, il timeout, i flag di proprietà, le dimensioni dei metadati e il numero di destinazioni per una radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_5 .
6
Restituisce il nome, lo stato, il GUID, il timeout, i flag di proprietà, le dimensioni dei metadati, le informazioni di destinazione DFS per una radice o un collegamento e un elenco di destinazioni DFS. Il parametro Buffer punta a una matrice di strutture DFS_INFO_6 .
8
Restituisce il nome, lo stato, il GUID, il timeout, i flag di proprietà, le dimensioni dei metadati, il numero di destinazioni e i descrittori di sicurezza dei punti per una radice DFS e tutti i collegamenti nella radice. Il parametro Buffer punta a una matrice di strutture DFS_INFO_8 .
9
Restituisce il nome, lo stato, il GUID, il timeout, i flag di proprietà, le dimensioni dei metadati, le informazioni di destinazione DFS, i descrittori di sicurezza dei punti di ripristino del collegamento e un elenco di destinazioni DFS per una radice o un collegamento. Il parametro Buffer punta a una matrice di strutture DFS_INFO_9 .
200
Restituisce l'elenco degli spazi dei nomi DFS basati su dominio nel dominio. Il parametro Buffer punta a una matrice di strutture DFS_INFO_200 .
300
Restituisce gli spazi dei nomi DFS autonomi e basati su dominio ospitati da un server. Il parametro Buffer punta a una matrice di strutture DFS_INFO_300 .
[in] PrefMaxLen
Specifica il numero di byte che devono essere restituiti da questa funzione nel buffer della struttura delle informazioni. Se questo parametro è MAX_PREFERRED_LENGTH, la funzione alloca la quantità di memoria necessaria per i dati. Per ulteriori informazioni, vedere la sezione Osservazioni successiva. Questo parametro viene ignorato se si specifica il livello 200 o il livello 300.
[out] Buffer
Puntatore a un buffer che riceve le strutture di informazioni richieste. Il formato di questi dati dipende dal valore del parametro Level . Questo buffer viene allocato dal sistema e deve essere liberato usando la funzione NetApiBufferFree .
[out] EntriesRead
Puntatore a un valore che riceve il numero effettivo di voci restituite nella risposta.
[in, out] ResumeHandle
Puntatore a un valore che contiene un handle da usare per continuare un'enumerazione quando sono disponibili più dati che possono essere restituiti in una singola chiamata a questa funzione. L'handle deve essere zero nella prima chiamata e lasciato invariato per le chiamate successive. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è NERR_Success.
Se non sono disponibili più voci da enumerare, il valore restituito è ERROR_NO_MORE_ITEMS.
Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema. Per un elenco di codici di errore, vedere Codici di errore di sistema.
Commenti
Non è necessaria alcuna appartenenza speciale al gruppo per l'uso della funzione NetDfsEnum .
Chiamare la funzione NetDfsEnum con il parametro ResumeHandle impostato su zero per iniziare l'enumerazione. Per continuare l'operazione di enumerazione, chiamare questa funzione con resumeHandle restituita dalla chiamata precedente a NetDfsEnum. Se questa funzione non restituisce ERROR_NO_MORE_ITEMS, le chiamate successive a questa API restituiranno i collegamenti rimanenti. Una volta restituito ERROR_NO_MORE_ITEMS, tutti i collegamenti DFS disponibili sono stati recuperati.
La funzione NetDfsEnum alloca la memoria necessaria per il buffer della struttura delle informazioni. Se si specifica una quantità nel parametro PrefMaxLen , limita la memoria restituita dalla funzione. Tuttavia, le dimensioni effettive della memoria che la funzione NetDfsEnum alloca può essere maggiore della quantità specificata. Per altre informazioni, vedere Lunghezze del buffer delle funzioni di gestione della rete.
A causa della possibilità di aggiornamenti simultanei nello spazio dei nomi DFS, il chiamante non deve presupporre la completezza o l'univocità dei risultati restituiti durante la ripresa di un'operazione di enumerazione.
Esempio
L'esempio di codice seguente illustra come elencare i collegamenti DFS in una radice DFS denominata con una chiamata alla funzione NetDfsEnum . L'esempio chiama NetDfsEnum, specificando il livello di informazioni 3 ( DFS_INFO_3). Il codice di esempio scorre le voci e stampa i dati recuperati e lo stato di ogni server host a cui fa riferimento il collegamento DFS. Infine, l'esempio libera la memoria allocata per il buffer delle informazioni.
#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;
}
Requisiti
| Client minimo supportato | Windows Vista |
| Server minimo supportato | Windows Server 2008 |
| Piattaforma di destinazione | Windows |
| Intestazione | lmdfs.h (include LmDfs.h, Lm.h) |
| Libreria | Netapi32.lib |
| DLL | Netapi32.dll |