3.1.4.1.5 NetrDfsSetInfo (Opnum 3)

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.

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.

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.

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>