NetDfsEnum 函数 (lmdfs.h)

项目
08/24/2023

枚举分布式文件系统 (DFS) 服务器上托管的命名空间或服务器托管的命名空间的 DFS 链接。

语法

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
);

parameters

[in] DfsName

指向指定通用命名约定 (UNC) DFS 根或链接路径的字符串的指针。

将信息级别指定为 200 (DFS_INFO_200) 时，此参数是域的名称。将信息级别指定为 300 (DFS_INFO_300) 时，此参数是服务器的名称。

对于所有其他级别，字符串可以是以下四种形式之一：

ServerName\DfsName

或

ServerName\DfsName\link_path

其中 ，ServerName 是托管独立 DFS 命名空间的根目标服务器的名称; Dfsname 是 DFS 命名空间的名称; 和 link_path 是 DFS 链接。

字符串也可以是以下形式：

DomainName\DomainName\DomDfsName

或

DomainName\DomDfsName\link_path

其中 ，DomainName 是托管基于域的 DFS 根的域的名称; DomDfsName 是 DFS 命名空间的名称; 和 link_path 是 DFS 链接。

可以在字符串前面加上反斜杠 (\) ，但不是必需的。此参数是必需的。

[in] Level

指定请求的信息级别。此参数的取值可为下列值之一：

1

返回 DFS 根的名称以及根目录下的所有链接。 Buffer 参数指向DFS_INFO_1结构的数组。

2

返回 DFS 根和根下所有链接的名称、注释、状态和目标数。 Buffer 参数指向DFS_INFO_2结构的数组。

3

返回名称、注释、状态、目标数，以及有关 DFS 根下每个目标以及根下的所有链接的信息。 Buffer 参数指向DFS_INFO_3结构的数组。

4

返回名称、注释、状态、 GUID、超时、目标数，以及 DFS 根目录下所有链接的每个目标的相关信息。 Buffer 参数指向DFS_INFO_4结构的数组。

5

返回 DFS 根和根下所有链接的名称、状态、 GUID、超时、属性标志、元数据大小和目标数。 Buffer 参数指向DFS_INFO_5结构的数组。

6

返回名称、状态、 GUID、超时、属性标志、元数据大小、根或链接的 DFS 目标信息以及 DFS 目标的列表。 Buffer 参数指向DFS_INFO_6结构的数组。

8

返回 DFS 根和根下所有链接的名称、状态、 GUID、超时、属性标志、元数据大小、目标数和链接重分析点安全描述符。 Buffer 参数指向DFS_INFO_8结构的数组。

9

返回名称、状态、 GUID、超时、属性标志、元数据大小、DFS 目标信息、链接重分析点安全描述符以及根或链接的 DFS 目标列表。 Buffer 参数指向DFS_INFO_9结构的数组。

200

返回域中基于域的 DFS 命名空间的列表。 Buffer 参数指向DFS_INFO_200结构的数组。

300

返回服务器托管的独立和基于域的 DFS 命名空间。 Buffer 参数指向DFS_INFO_300结构的数组。

[in] PrefMaxLen

指定此函数应在信息结构缓冲区中返回的字节数。如果 此参数MAX_PREFERRED_LENGTH，则函数将分配数据所需的内存量。有关更多信息，请参见下面的“备注”部分。如果指定级别 200 或级别 300，则忽略此参数。

[out] Buffer

指向接收请求的信息结构的缓冲区的指针。此数据的格式取决于 Level 参数的值。此缓冲区由系统分配，必须使用 NetApiBufferFree 函数释放。

[out] EntriesRead

指向接收响应中返回的实际条目数的值的指针。

[in, out] ResumeHandle

指向一个值的指针，该值包含一个句柄，该句柄用于在可用数据多于对此函数的单个调用中返回的数据时用于继续枚举。第一次调用时，句柄应为零，后续调用应保持不变。有关更多信息，请参见下面的“备注”部分。

返回值

如果函数成功，则返回值 NERR_Success。

如果没有更多条目可供枚举，则 返回值ERROR_NO_MORE_ITEMS。

如果函数失败，则返回值为系统错误代码。有关错误代码的列表，请参阅系统错误代码。

注解

使用 NetDfsEnum 函数不需要特殊组成员身份。

调用将 ResumeHandle 参数设置为零的 NetDfsEnum 函数以开始枚举。若要继续枚举操作，请使用上一次调用 NetDfsEnum 返回的 ResumeHandle 调用此函数。如果此函数不返回 ERROR_NO_MORE_ITEMS，则对此 API 的后续调用将返回剩余的链接。返回 ERROR_NO_MORE_ITEMS 后，已检索所有可用的 DFS 链接。

NetDfsEnum 函数分配信息结构缓冲区所需的内存。如果在 PrefMaxLen 参数中指定一个量，它将限制函数返回的内存。但是， NetDfsEnum 函数分配的实际内存大小可能大于指定的内存量。有关详细信息，请参阅网络管理功能缓冲区长度。

由于可能会并发更新 DFS 命名空间，调用方不应假定在恢复枚举操作时返回的结果的完整性或唯一性。

示例

下面的代码示例演示如何通过调用 NetDfsEnum 函数列出命名 DFS 根中的 DFS 链接。此示例调用 NetDfsEnum，指定信息级别 3 ( DFS_INFO_3) 。示例代码循环访问条目，并输出检索的数据以及 DFS 链接引用的每个主机服务器的状态。最后，该示例释放为信息缓冲区分配的内存。

#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;
}

要求


最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	lmdfs.h (包括 LmDfs.h、Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll