3.1.4.2.4 NetrDfsSetInfo2 (Opnum 22)

Article
04/06/2021

The NetrDfsSetInfo2 (Opnum 22) method sets or modifies the information associated with a DFS root, a DFS root target, a DFS link, or a DFS link target.

The NetrDfsSetInfo2 method has the following MIDL syntax.

 NET_API_STATUS NetrDfsSetInfo2(
   [in, string] WCHAR* DfsEntryPath,
   [in, string] WCHAR* DcName,
   [in, unique, string] WCHAR* ServerName,
   [in, unique, string] WCHAR* ShareName,
   [in] DWORD Level,
   [in, switch_is(Level)] DFS_INFO_STRUCT* pDfsInfo,
   [in, out, unique] DFSM_ROOT_LIST** ppRootList
 );

DfsEntryPath: The pointer to a DFS root path or a DFS link path that contains the name of a DFS root or DFS link name.

DcName: The pointer to a null-terminated Unicode string. It MUST be ignored for a stand-alone DFS namespace. For a domain-based DFS namespace, this string contains the host name of the DC that the DFS root target uses to get or update DFS metadata for the DFS namespace. This parameter MAY be a NULL pointer; otherwise, it MUST be the PDC for the domain of the DFS namespace.<99>

ServerName: The pointer to a null-terminated Unicode DFS root target or a DFS link target host name string. This parameter MUST be a NULL pointer if the operation is intended for a DFS root or a DFS link and not for targets.

ShareName: The pointer to a null-terminated Unicode DFS root target or a DFS link target share name string. This parameter MUST be a NULL pointer if the operation is intended for a DFS root or a DFS link and not for targets.

Level: This parameter 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 that specified in DfsInfo.
Level_101 0x00000065	Sets the storage state associated with the root, link, root target, or link target specified in DfsInfo.<100>
Level_102 0x00000066	Sets the time-out value associated with the root or link specified in DfsInfo.
Level_103 0x00000067	Sets the property flags for the root or link specified in DfsInfo.
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 root or link specified in DfsInfo. This does not apply to a root target or link target.
Level_106 0x0000006A	Sets the target state and priority for the root target or link target specified in DfsInfo. This does not apply to the DFS namespace root or link.<101>
Level_107 0x0000006B	Sets the comment, state, time-out, security descriptor information, and property flags for the 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 an 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 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 an 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.<102> The server SHOULD return error code ERROR_INVALID_PARAMETER for unsupported Level values.<103>

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

ppRootList: On success, returns a list of DFS root targets in the domain-based DFS namespace which the client will be responsible for notifying about the change in the DFS namespace. See section 3.2.4.2.3. This list MAY be empty if the server has performed the notification.<104>

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

The server MAY <105> implement this method.

If the NetrDfsSetInfo (Opnum 3) method on a server does not support a domain-based namespace, the server SHOULD support a domain-based namespace in the NetrDfsSetInfo2 (Opnum 22) method.<106><107>

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.

If the DcName parameter is not NULL, it MUST be the PDC for the domain of the domain-based DFS namespace.

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. The server MUST fail any attempt to set the property flags on a DFS link that are defined only for a DFS root.

With the Level parameter 101 and the State field in the DFS_INFO_101 structure as DFS_VOLUME_STATE_RESYNCHRONIZE, the server MUST reload the contents of the DFSMetadataCache, if maintained, for the domain-based DFS namespace that the ShareName parameter specifies. In the case of both domain-based DFS namespaces and stand-alone DFS namespaces, the server MUST check the DFS namespace it hosts locally with the DFS metadata and perform any required modifications.

With the Level parameter 101 and the State field in the DFS_INFO_101 structure as DFS_VOLUME_STATE_FORCE_SYNC, the server MUST perform a full synchronization instead of an incremental synchronization to reload the contents of the DFSMetadataCache and to identify added or deleted DFS links. This State field is supported on domainv2-based DFS namespaces and stand-alone DFS namespaces.

When level parameter 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.

The server MUST update the same fields in the DFS metadata for a domain-basedv1 DFS namespace as for the NetrDfsSetInfo (Opnum 3) method, as specified in section 3.1.4.1.5.

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

If DFS root scalability mode is not enabled for the domain-based DFS namespace, the server MUST do one of the following:

Notify other DFS root targets of the change in DFS metadata by asynchronously issuing a NetrDfsSetInfo (Opnum 3) method with the Level parameter 101 and with the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE. The returned ppRootList parameter MUST be empty.
Perform no notification of the other root targets, returning a list of DFS root targets to the client in the ppRootList parameter.

3.1.4.2.4 NetrDfsSetInfo2 (Opnum 22)

Additional resources