3.1.4.1.5 NetrDfsSetInfo (Opnum 3)

  • Article

The NetrDfsSetInfo method sets or modifies information relevant to a specific DFS root, DFS root target, DFS link, or DFS link target.

The NetrDfsSetInfo method uses the following MIDL syntax.

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

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

ServerName: The pointer to a null-terminated Unicode DFS root target or DFS link target host name string. Clients MUST set this to a NULL pointer when the DFS root or DFS link is used and not the DFS root target or DFS link target.

ShareName: The pointer to a null-terminated Unicode string DFS root target or DFS link target host name. Clients MUST set this to a NULL pointer when the DFS root or DFS link is used and not the DFS root target or DFS link target.

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

Value

Meaning

Level_100

0x00000064

Sets the comment associated with the root or link specified in the DfsInfo parameter. The ServerName and ShareName parameters MUST be NULL.

Level_101

0x00000065

Sets the state associated with the root, link, root target, or link target specified in DfsInfo.<52>

Level_102

0x00000066

Sets the time-out value associated with the root or link specified in DfsInfo. The ServerName and ShareName parameters MUST be ignored.

Level_103

0x00000067

Sets the property flags for the root or link specified in DfsInfo. The ServerName and ShareName parameters MUST be NULL.

Level_104

0x00000068

Sets the target priority rank and class for the root target or link target specified in DfsInfo.

Level_105

0x00000069

Sets the comment, state, time-out information, and property flags for the namespace root or link specified in DfsInfo. Does not apply to a root target or link target. The ServerName and ShareName parameters MUST be NULL.

Level_106

0x0000006A

Sets the target state and priority for the DFS root target or DFS link target specified in DfsInfo.<53> This does not apply to the DFS namespace root or link.

Level_107

0x0000006B

Sets the comment, state, time-out, security descriptor information, and property flags for the namespace root or link specified in DfsInfo. Does not apply to a root target or link target. The ServerName and ShareName parameters MUST be NULL. The security descriptor MUST NOT have owner, group, or SACLs in it.

The security descriptor MUST be a NULL, zero length value if used on a namespace root. In this case, note that it is equivalent to using Level_105.

Level_150

0x00000096

Sets the security descriptor associated with a DFS link. Only stand-alone DFS namespaces and domainv2-based DFS namespaces are supported. The ServerName and ShareName parameters MUST both be NULL. The security descriptor MUST NOT have owner, group, or SACLs in it.

The server MUST support Level values 100 and 101. The server SHOULD support Level values 102-107 and 150. If the server does not support the provided Level, it MUST fail the call.<54> The server SHOULD return error code ERROR_INVALID_PARAMETER for unsupported level values.<55>

DfsInfo: The pointer to a DFS_INFO_STRUCT union that contains the specified data. The value of the Level parameter selects the case of the union.

Return Values: This 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.

0x00000002

ERROR_FILE_NOT_FOUND

The specified DFS link target was not found as a target of the specified DFS link.

0x00000005

ERROR_ACCESS_DENIED

Permission to perform the operation was denied.

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 namespace or DFS link, or DFS link or root target, does not exist.

The NetrDfsSetInfo method SHOULD<56> support a domain-based DFS namespace. If it does not support a domain-based DFS namespace it MUST return ERROR_NOT_SUPPORTED.

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.

The server MUST verify the existence of the DFS link target of the DFS link that the ServerName and RootShare parameters specify. If that existence check fails, the server MUST return ERROR_FILE_NOT_FOUND.

The server MUST fail any attempt to set the state of a DFS root, a DFS link, a DFS root target or a DFS link target to a value that is not specified for the Level parameter. The server MUST fail any attempt to set the property flags on a DFS link that are defined only for a DFS root.

When the Level parameter is 101 and the State field in the DFS_INFO_101 structure is DFS_VOLUME_STATE_RESYNCHRONIZE, the server MUST reload the contents of the DFSMetadataCache for the DFS namespace that the ShareName parameter specifies. It MUST then update its local DFS namespace information by comparing this information against the DFS metadata. The details of this update operation are implementation-dependent.

When level 107 is used for a DFS namespace root or for a domainv1-based DFS link, the pSecurityDescriptor parameter has no meaning because security descriptors cannot be associated with those objects. In these cases, if pSecurityDescriptor is not NULL, the server MUST fail with ERROR_NOT_SUPPORTED.

For domainv1-based DFS root, if the Level in the DfsInfo structure is 103, 105, or 107, and if the PropertyFlagMask field has the DFS_PROPERTY_FLAG_ABDE flag set, the server MUST fail the call with ERROR_NOT_SUPPORTED.

If the Level in the DfsInfo structure is 103, 105, or 107, and if PropertyFlagMask field has DFS_PROPERTY_FLAG_CLUSTER_ENABLED flag set, the server MUST fail the call with ERROR_NOT_SUPPORTED.

The server MUST synchronously update the following fields in the DFS metadata for a stand-alone DFS namespace, depending on the value of the Level parameter.

Value

DFS metadata changes required

100

(0x00000064)

Update Comment in the NamespaceElement.

101

(0x00000065)

If a link, update the State field of NamespaceElement. If a root target or link target, update the TargetState field of Target.

102

(0x00000066)

Update the ReferralTTL field of NamespaceElement.

103

(0x00000067)

Update the Properties field of NamespaceElement.

104

(0x00000068)

Update the PriorityRank and PriorityClass fields of Target.

105

(0x00000069)

Update the Comment, State, ReferralTTL, and Properties fields of NamespaceElement.

106

(0x0000006A)

Update the PriorityRank, PriorityClass, and TargetState fields of Target.

107

(0x0000006B)

Update the Comment, State, ReferralTTL, SecurityDescriptor, and Properties fields of NamespaceElement.

150

(0x00000096)

Update SecurityDescriptor of the NamespaceElement.

The server MUST update the following fields in the DFS metadata for a domainv1-based DFS namespace, depending on the value of the Level parameter.

Value

DFS metadata changes required

100 (0x00000064)

Update CommentSize and Comment in DFSRootOrLinkIDBLOB and BLOBDataSize of DFSNamespaceLinkBLOB.

101 (0x00000065)

If a link, update the State field of DFSRootOrLinkIDBLOB.

If a root target or link target, update the TargetState field of TargetEntryBLOB.

102 (0x00000066)

Update the ReferralTTL field of DFSNamespaceRootBLOB or DFSNamespaceLinkBLOB.

103 (0x00000067)

Update the Type field of DFSRootOrLinkIDBLOB.

104 (0x00000068)

Update the PriorityRank and PriorityClass fields of TargetEntryBLOB.

105 (0x00000069)

Update CommentSize and Comment in DFSRootOrLinkIDBLOB, the State field of DFSRootOrLinkIDBLOB, the ReferralTTL field of DFSNamespaceRootBLOB or DFSNamespaceLinkBLOB, and the Type field of DFSRootOrLinkIDBLOB.

106 (0x0000006A)

Update the PriorityRank, PriorityClass, and TargetState fields of TargetEntryBLOB.

107 (0x0000006B)

See 105 (0x00000069).

If the server does not support levels 104 or 106, it MUST use the FILETIME encoding for the TargetTimestamp field of the TargetEntryBLOB and update the field for each modified TargetEntryBLOB, as specified in section 2.3.3.1.1.3.1.

If the server supports levels 104 and 106, it MUST instead use the encoding which provides the PriorityRank and PriorityClass in the TargetTimestamp field.

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

The server MUST update the following fields in the DFS metadata for a domainv2-based DFS namespace, depending on the value of the Level parameter. For information about these fields, see section 2.3.4.

Value

DFS metadata changes required

100 (0x00000064)

Update msDFS-Commentv2.

101 (0x00000065)

State field of msDFS-TargetListv2.

102 (0x00000066)

Update msDFS-Ttlv2.

103 (0x00000067)

Update msDFS-Propertiesv2.

104 (0x00000068)

Update the priorityClass and priorityRank attributes in msDFS-TargetListv2.

105 (0x00000069)

Update msDFS-Commentv2, msDFS-Ttlv2, msDFS-Propertiesv2, and the State field of msDFS-Targetlistv2.

106 (0x0000006A)

Update priorityClass, priorityRank, and the State field of msDFS-TargetListv2.

107 (0x0000006B)

Update msDFS-Commentv2, msDFS-Ttlv2, msDFS-Propertiesv2, msDFS-LinkSecurityDescriptorv2, and the State field of msDFS-TargetListv2.

150 (0x00000096)

Update msDFS-LinkSecurityDescriptorv2.

The server MUST synchronously update the DFS metadata of a domain-based DFS namespace.

For domainv2-based or standalone DFS root, if the DFS_PROPERTY_FLAG_ABDE flag in NamespaceElement.Properties is either set or cleared as a result of this method, the server MUST communicate with the local SMB service to enable (DFS_PROPERTY_FLAG_ABDE set) or disable (DFS_PROPERTY_FLAG_ABDE cleared) the Access-Based Directory Enumeration property on the DFS root target by calling the NetrShareSetinfo method using Level 1005 (as specified in [MS-SRVS] section 3.1.4.11).

If DFS root scalability mode is not enabled for the domain-based DFS namespace, the server MUST notify other DFS root targets of the change in DFS metadata by asynchronously issuing a NetrDfsSetInfo method with the Level parameter 101, and with the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE.<57>