3.1.4.1.6 NetrDfsGetInfo (Opnum 4)

The NetrDfsGetInfo method returns information about a DFS root or a DFS link of the specified DFS namespace.

The NetrDfsGetInfo method has the following MIDL syntax.

 NET_API_STATUS NetrDfsGetInfo(
   [in, string] WCHAR* DfsEntryPath,
   [in, unique, string] WCHAR* ServerName,
   [in, unique, string] WCHAR* ShareName,
   [in] DWORD Level,
   [out, switch_is(Level)] DFS_INFO_STRUCT* DfsInfo
 );

DfsEntryPath: The pointer to a DFS root or a DFS link path.

ServerName: This parameter MUST be a NULL pointer for Level_50 and MUST be ignored for other levels.

ShareName: This parameter MUST be a NULL pointer for Level_50 and MUST be ignored for other levels.

Level: This parameter specifies the information level of the data and, in turn, determines the action the method performs.

Value	Meaning
Level_1 0x00000001	Returns the name of the DFS root or the DFS link.
Level_2 0x00000002	Returns the name, comment, state, and number of targets for the DFS root or the DFS link.
Level_3 0x00000003	Returns the name, comment, state, number of targets, and target information for the DFS root or the DFS link.
Level_4 0x00000004	Returns the name, comment, state, time-out, GUID, number of targets, and target information for the DFS root or the DFS link.
Level_5 0x00000005	Returns the name, comment, state, time-out, GUID, property flags, metadata size, and number of targets for the DFS root or the DFS link.
Level_6 0x00000006	Returns the name, comment, state, GUID, time-out, property flags, metadata size, number of targets, and target information for the DFS root or the DFS link.
Level_7 0x00000007	Returns the version number GUID of the DFS metadata. This value only applies to the DFS root.
Level_8 0x00000008	Returns the name, comment, state, time-out, GUID, property flags, metadata size, number of targets, and security descriptor associated with the DFS root or the DFS link. Only stand-alone DFS namespaces and domainv2-based DFS namespaces are supported.
Level_9 0x00000009	Returns the name, comment, state, GUID, time-out, property flags, metadata size, number of targets, list of targets, and security descriptor for the DFS root or the DFS link. Only stand-alone DFS namespaces and domainv2-based DFS namespaces are supported.
Level_50 0x00000032	Returns the DFS metadata version and capability information of an existing DFS namespace. This level is valid only for the DFS namespace root, not for DFS links. The ServerName and ShareName parameters MUST both be NULL.<58>
Level_100 0x00000064	Returns the comment associated with the root or DFS link specified in the DfsEntryPath parameter.
Level_150 0x00000096	Returns the security descriptor associated with a DFS link. Only stand-alone DFS namespaces and domainv2-based DFS namespaces are supported.

The server MUST support Level values 1-3 and 100. The server SHOULD support Level values 4-9, 50 and 150. If the server does not support the provided Level, it MUST fail the call.<59> The server SHOULD return error code ERROR_INVALID_PARAMETER for unsupported Level values.<60>

DfsInfo: The pointer to a DFS_INFO_STRUCT union to receive the returned information. The case of the union is selected by the value of the Level parameter.

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.
0x00000032 ERROR_NOT_SUPPORTED	The specified operation is not supported.
0x00000057 ERROR_INVALID_PARAMETER	An incorrect parameter was specified.
0x00000490 ERROR_NOT_FOUND	The specified DFS root or DFS link, or DFS link or root target does not exist.

The server MUST verify the existence of the DFS namespace that the DfsEntryPath parameter specifies. If the namespace does not exist, the server MUST return ERROR_NOT_FOUND.

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

 For a standalone DFS namespace, the server MUST identify a consistent GUID for the specified DFS link or DFS root path. This value MUST conform to the expectations of UUID uniqueness provided by [RFC4122] or [C706], though those specific algorithms are not required. This GUID value MUST be used when responding to calls specifying a Level parameter whose corresponding return structure provides the GUID: values of 4, 5, 6, 8, or 9.

The server MUST use the following fields in the DFS metadata for a stand-alone DFS namespace to return the required information, depending on the value of the Level parameter.

The server MUST use the following fields in the DFS metadata for a domainv1-based DFS namespace to return the required information, depending on the value of the Level parameter.

Note that for interoperability, all root targets of a namespace SHOULD use the same encoding for this TargetTimestamp field, as specified in section 2.3.3.1.1.3.1.

The server MUST use the following fields in the DFS metadata for a domainv2-based DFS namespace to return the required information, depending on the value of the Level parameter.