3.1.4.2.3 NetrDfsEnumEx (Opnum 21)

  • Article

The NetrDfsEnumEx (Opnum 21) method enumerates the DFS roots hosted on a server, or DFS links of a namespace hosted by the server.<92><93> Depending on the information level, the targets associated with the roots and links are also displayed.

The NetrDfsEnumEx method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsEnumEx(
   [in, string] WCHAR* DfsEntryPath,
   [in] DWORD Level,
   [in] DWORD PrefMaxLen,
   [in, out, unique] DFS_INFO_ENUM_STRUCT* DfsEnum,
   [in, out, unique] DWORD* ResumeHandle
 );

DfsEntryPath: The pointer to a domain name, a host name, or a DFS path, depending on the Level parameter.

  • A domain name MUST be a null-terminated Unicode string in the following forms:

     <DomainName> or \<DomainName> or \\<DomainName>
 

    where <DomainName> is the domain name to use for the enumeration.

  • A host name MUST be a null-terminated Unicode string in the following formats:

     <ServerName> or \<ServerName> or \\<ServerName>
 

    where <ServerName> is a host name.

  • A DFS root or a DFS link path.

    When DfsEntryPath points to a DFS link path, the remaining path after the DFS namespace name MUST be ignored.

Level: This parameter specifies the information level of the data and in turn determines the action the method performs. On successful return, the server MUST return an array of the corresponding structures in the buffer pointed to by DfsEnum.

Value

Meaning

Level_1

0x00000001

Gets the name of the DFS root and all links beneath it. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_1 structures.

Level_2

0x00000002

Gets the name, comment, state, and number of targets for the DFS root and all links under the root. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_2 structures.

Level_3

0x00000003

Gets the name, comment, state, number of targets, and information about each target for the DFS root and all links under the root. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_3 structures.

Level_4

0x00000004

Gets the name, comment, state, time-out, GUID, number of targets, and information about each target for the DFS root and all links under the root. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_4 structures.

Level_5

0x00000005

Gets the name, comment, state, time-out, GUID, property flags, metadata size, and number of targets for a DFS root and all links under the root. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_5 structures.

Level_6

0x00000006

Gets the name, comment, state, time-out, GUID, property flags, metadata size, number of targets, and target information for a root or link. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_6 structures.

Level_8

0x00000008

Gets the name, comment, state, time-out, GUID, property flags, metadata size, and number of targets for a DFS root and all links under the root. Also returns the security descriptor associated with each of the DFS links. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_8 structures.

Level_9

0x00000009

Gets the name, comment, state, time-out, GUID, property flags, metadata size, and number of targets and target information for a DFS root and all links under the root. Also returns the security descriptor associated with each of the DFS links. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_9 structures.

Level_200

0x000000C8

Enumerates all of the domain-based DFS namespace in the specified domain. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_200 structures.

Level_300

0x0000012C

Enumerates the stand-alone and domain-based DFS roots that the server hosts. In this case, on successful return DfsEnum MUST point to an array of DFS_INFO_300 structures.

The server MUST support Level values 1, 2 and 3. The server SHOULD support Level values 5, 6, 8, 9, and 300. The server on a DC SHOULD support Level value 200.<94> If the server does not support the provided Level, it MUST fail the call. The server SHOULD return error code ERROR_INVALID_PARAMETER for unsupported Level values.<95>

PrefMaxLen: This parameter specifies restrictions on the number of elements returned. A value of 0xFFFFFFFF means there are no restrictions, in which case all entries MUST be returned.<96>

DfsEnum: A pointer to a DFS_INFO_ENUM_STRUCT union to receive the returned information. The client SHOULD set the Level member to the same value as the method's Level parameter, and MUST set the DfsInfoContainer union member to a pointer to the corresponding container structure as specified in section 2.2.6. The client MUST initialize the container structure's EntriesRead member to zero and the Buffer member to a NULL pointer. The value of the Level member determines the case of the union.

ResumeHandle: This parameter is used to continue an enumeration when more data is available than can be returned in a single invocation of this method.

  • If this parameter is not a NULL pointer, and the method returns ERROR_SUCCESS, this parameter receives an implementation-specific nonzero value that can be passed in subsequent calls to this method to continue the enumeration.

  • If this parameter is a NULL pointer, or it points to a zero value, it indicates that this is an initial enumeration.

  • If this parameter is not a NULL pointer, and it points to a nonzero value returned in ResumeHandle by an earlier invocation of this method, the server will attempt to continue a previous enumeration.<97>

Return Values: The method MUST return 0 on success and a nonzero error code on failure. The method can return any specific error code value, as specified in [MS-ERREF], section 2.2. The most common error codes are listed in the following table.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Successful completion.

0x00000057

ERROR_INVALID_PARAMETER

An incorrect parameter was specified.

0x00000103

ERROR_NO_MORE_ITEMS

There is no data to return.

0x00000490

ERROR_NOT_FOUND

The specified DFS root namespace does not exist.

The server MUST verify the existence of the DFS namespace that the DfsEntryPath parameter specifies. If that existence check fails, the server MUST return ERROR_NOT_FOUND.

The server MUST return ERROR_NO_MORE_ITEMS (0x00000103) if there is no data to return.

Unlike the NetrDfsEnum method, this method can be used even when the server is hosting more than one DFS root.

If the server hosts exactly one DFS namespace, the requested Level is 1 through 9, and the DfsEntryPath does not specify a DFS namespace name, the server MAY enumerate the namespace it hosts.<98>

Each member of the DFS_INFO_ENUM_STRUCT return buffer MUST be constructed according to the rules of section 3.1.4.1.6 (NetrDfsGetInfo) for the specified value of the Level parameter.

If the requested Level is 1 through 9 and ResumeHandle indicates initial enumeration, the server MUST return the DFS root entry as the first member of the DFS_INFO_ENUM_STRUCT return buffer followed by DFS links in implementation-specific order.

If the requested Level is 1 through 9 and ResumeHandle does not indicate initial enumeration, the server MUST NOT return the DFS root entry and all the entries of the DFS_INFO_ENUM_STRUCT return buffer MUST be DFS links in implementation-specific order.