Share via

3.1.4.2.4 NetrDfsSetInfo2 (Opnum 22)

  • Article

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.