Fonction NetDfsEnum (lmdfs.h)
Énumère les espaces de noms DFS (Distributed File System) hébergés sur un serveur ou les liens DFS d’un espace de noms hébergé par un serveur.
Syntaxe
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
);
Paramètres
[in] DfsName
Pointeur vers une chaîne qui spécifie le chemin d’accès UNC (Universal Naming Convention) de la racine ou du lien DFS.
Lorsque vous spécifiez le niveau d’informations 200 (DFS_INFO_200), ce paramètre est le nom d’un domaine. Lorsque vous spécifiez le niveau d’informations 300 (DFS_INFO_300), ce paramètre est le nom d’un serveur.
Pour tous les autres niveaux, la chaîne peut se trouver sous l’une des quatre formes suivantes :
Servername\DfsName
or
Servername\DfsName\link_path
où ServerName est le nom du serveur cible racine qui héberge l’espace de noms DFS autonome ; Dfsname est le nom de l’espace de noms DFS ; et link_path est un lien DFS.
La chaîne peut également être des formes suivantes :
Domainname\DomainName\DomDfsName
or
Domainname\DomDfsName\link_path
où DomainName est le nom du domaine qui héberge la racine DFS basée sur le domaine ; DomDfsName est le nom de l’espace de noms DFS ; et link_path est un lien DFS.
Vous pouvez faire précéder la chaîne avec des barres obliques inverses (\), mais elles ne sont pas obligatoires. Ce paramètre est obligatoire.
[in] Level
Spécifie le niveau d’informations de la demande. Ce paramètre peut prendre les valeurs suivantes.
1
Retourne le nom de la racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_1 .
2
Retournez le nom, le commentaire, status et le nombre de cibles pour la racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_2 .
3
Retournez le nom, le commentaire, status, le nombre de cibles et les informations sur chaque cible pour la racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_3 .
4
Retournez le nom, le commentaire, le status, le GUID, le délai d’attente, le nombre de cibles et les informations sur chaque cible pour la racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_4 .
5
Retourne le nom, le status, le GUID, le délai d’expiration, les indicateurs de propriété, la taille des métadonnées et le nombre de cibles pour une racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_5 .
6
Retournez le nom, le status, le GUID, le délai d’expiration, les indicateurs de propriété, la taille des métadonnées, les informations cibles DFS pour une racine ou un lien, ainsi qu’une liste de cibles DFS. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_6 .
8
Retourne le nom, le status, le GUID, le délai d’expiration, les indicateurs de propriété, la taille des métadonnées, le nombre de cibles et les descripteurs de sécurité de point d’analyse des liens pour une racine DFS et tous les liens sous la racine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_8 .
9
Retournez le nom, les status, le GUID, le délai d’expiration, les indicateurs de propriété, la taille des métadonnées, les informations cibles DFS, les descripteurs de sécurité des points d’analyse de lien et une liste de cibles DFS pour une racine ou un lien. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_9 .
200
Retourne la liste des espaces de noms DFS basés sur un domaine dans le domaine. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_200 .
300
Retourne les espaces de noms DFS autonomes et basés sur un domaine hébergés par un serveur. Le paramètre Buffer pointe vers un tableau de structures DFS_INFO_300 .
[in] PrefMaxLen
Spécifie le nombre d’octets qui doivent être retournés par cette fonction dans la mémoire tampon de structure d’informations. Si ce paramètre est MAX_PREFERRED_LENGTH, la fonction alloue la quantité de mémoire requise pour les données. Pour plus d'informations, consultez la section Notes qui suit. Ce paramètre est ignoré si vous spécifiez le niveau 200 ou le niveau 300.
[out] Buffer
Pointeur vers une mémoire tampon qui reçoit les structures d’informations demandées. Le format de ces données dépend de la valeur du paramètre Level . Cette mémoire tampon est allouée par le système et doit être libérée à l’aide de la fonction NetApiBufferFree .
[out] EntriesRead
Pointeur vers une valeur qui reçoit le nombre réel d’entrées retournées dans la réponse.
[in, out] ResumeHandle
Pointeur vers une valeur qui contient un handle à utiliser pour la poursuite d’une énumération lorsque plus de données sont disponibles que ce qui peut être retourné dans un seul appel à cette fonction. Le handle doit être égal à zéro lors du premier appel et rester inchangé pour les appels suivants. Pour plus d'informations, consultez la section Notes qui suit.
Valeur retournée
Si la fonction réussit, la valeur de retour est NERR_Success.
Si aucune autre entrée n’est disponible pour être énumérée, la valeur de retour est ERROR_NO_MORE_ITEMS.
Si la fonction échoue, la valeur de retour est un code d’erreur système. Pour obtenir la liste des codes d’erreur, consultez Codes d’erreur système.
Notes
Aucune appartenance à un groupe spécial n’est requise pour l’utilisation de la fonction NetDfsEnum .
Appelez la fonction NetDfsEnum avec le paramètre ResumeHandle défini sur zéro pour commencer l’énumération. Pour continuer l’opération d’énumération, appelez cette fonction avec le ResumeHandle retourné par l’appel précédent à NetDfsEnum. Si cette fonction ne retourne pas ERROR_NO_MORE_ITEMS, les appels suivants à cette API retournent les liens restants. Une fois ERROR_NO_MORE_ITEMS retourné, tous les liens DFS disponibles ont été récupérés.
La fonction NetDfsEnum alloue la mémoire nécessaire pour la mémoire tampon de structure d’informations. Si vous spécifiez une quantité dans le paramètre PrefMaxLen , cela limite la mémoire retournée par la fonction. Toutefois, la taille réelle de la mémoire allouée par la fonction NetDfsEnum peut être supérieure à la quantité que vous spécifiez. Pour plus d’informations, consultez Longueurs de mémoire tampon de la fonction de gestion réseau.
En raison de la possibilité de mises à jour simultanées de l’espace de noms DFS, l’appelant ne doit pas supposer l’exhaustivité ou l’unicité des résultats retournés lors de la reprise d’une opération d’énumération.
Exemples
L’exemple de code suivant montre comment répertorier les liens DFS dans une racine DFS nommée avec un appel à la fonction NetDfsEnum . L’exemple appelle NetDfsEnum, en spécifiant le niveau d’informations 3 ( DFS_INFO_3). L’exemple de code boucle les entrées et imprime les données récupérées et les status de chaque serveur hôte référencé par le lien DFS. Enfin, l’exemple libère la mémoire allouée pour la mémoire tampon d’informations.
#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;
}
Configuration requise
| Client minimal pris en charge | Windows Vista |
| Serveur minimal pris en charge | Windows Server 2008 |
| Plateforme cible | Windows |
| En-tête | lmdfs.h (include LmDfs.h, Lm.h) |
| Bibliothèque | Netapi32.lib |
| DLL | Netapi32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour