3.1.4.1.6 NetrDfsGetInfo (Opnum 4)

Article
06/24/2021

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.

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.

Value	DFS metadata field
1 (0x00000001)	The Prefix field of NamespaceElement.
2 (0x00000002)	In addition to those for Level 1: the Comment and State fields of NamespaceElement and the TargetCount field of TargetsList.
3 (0x00000003)	In addition to those for Level 2: Target entries in the TargetsList.
4 (0x00000004)	In addition to those for Level 3: the ReferralTTL and IdentityGUID fields of NamespaceElement.
5 (0x00000005)	In addition to those for Level 4: the Properties field of NamespaceElement, and the size of the DFS namespace metadata,<61> but excluding Target entries.
6 (0x00000006)	In addition to those for Level 5: Target entries in the TargetsList.
7 (0x00000007)	The value of GenerationGUID attribute of the Namespace object.
8 (0x00000008)	In addition to those for Level 5: SecurityDescriptor of the NamespaceElement.
9 (0x00000009)	In addition to those for Level 6: SecurityDescriptor of the NamespaceElement.
50 (0x00000032)	No metadata attribute stores this data. The value returned MUST, however, be one of the values defined in the table in section 2.2.3.10.
100 (0x00000064)	Comment in NamespaceElement.
150 (0x00000096)	SecurityDescriptor of the NamespaceElement.

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.

Value	DFS metadata field
1 (0x00000001)	The PrefixSize and Prefix fields of DFSRootOrLinkIDBLOB.
2 (0x00000002)	In addition to those for Level 1: the CommentSize, Comment, and State fields of DFSRootOrLinkIDBLOB and the TargetCount field of DFSTargetListBLOB.
3 (0x00000003)	In addition to those for Level 2: TargetEntryBLOB.
4 (0x00000004)	In addition to those for Level 3: the ReferralTTL field of DFSNamespaceRootBLOB or DFSNamespaceLinkBLOB; the RootOrLinkGuid field of DFSRootOrLinkIDBLOB.
5 (0x00000005)	In addition to those for Level 4: the RootOrLinkGuid field of DFSRootOrLinkIDBLOB, the Type field of DFSRootOrLinkIDBLOB, and the Size field of the value stored in the pKT attribute of the DFS namespace's object, but excluding TargetEntryBLOB.
6 (0x00000006)	In addition to those for Level 5: TargetEntryBLOB.
7 (0x00000007)	The Value of pKTGuid attribute of the DFS namespace's object.
50 (0x00000032)	No metadata attribute stores this data. The value returned MUST, however, be one of the values defined in the table in section 2.2.3.10.
100 (0x00000064)	CommentSize and Comment in DFSRootOrLinkIDBLOB, and BLOBDataSize of DFSNamespaceLinkBLOB.

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.

Value	DFS metadata field
1 (0x00000001)	The msDFS-LinkPathv2 attribute.
2 (0x00000002)	In addition to those for Level 1: msDFS-Commentv2, msDFS-Propertiesv2, and the TargetCount field of msDFS-TargetListv2.
3 (0x00000003)	In addition to those for Level 2: msDFS-TargetListv2.
4 (0x00000004)	In addition to those for Level 3: msDFS-Ttlv2, msDFS-NamespaceIdentityGUIDv2 for DFS root, and msDFS-LinkIdentityGUIDv2 for DFS link.
5 (0x00000005)	In addition to those for Level 4: msDFS-Propertiesv2. Excludes msDFS-TargetListv2.
6 (0x00000006)	In addition to those for Level 4: msDFS-Propertiesv2.
7 (0x00000007)	The value of the msDFS-GenerationGUIDv2 attribute of the DFS namespace's object.
8 (0x00000008)	In addition to those for Level 5: msDFS-LinkSecurityDescriptorv2.
9 (0x00000009)	In addition to those for Level 6: msDFS-LinkSecurityDescriptorv2.
50 (0x00000032)	The msDFS-SchemaMajorVersion and msDFS-SchemaMinorVersion attributes.
100 (0x00000064)	The msDFS-Commentv2 attribute.
150 (0x00000096)	The msDFS-LinkSecurityDescriptorv2 attribute.

3.1.4.1.6 NetrDfsGetInfo (Opnum 4)

Additional resources