Share via

3.1.4.5.2 NetrDfsSetDcAddress (Opnum 17)

  • Article

The NetrDfsSetDcAddress (Opnum 17) method instructs the server receiving the RPC method to use the specified DC for DFS metadata accesses for domain-based DFS namespaces.<132>

The NetrDfsSetDcAddress method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsSetDcAddress(
   [in, string] WCHAR* ServerName,
   [in, string] WCHAR* DcName,
   [in] DWORD Timeout,
   [in] DWORD Flags
 );

ServerName: The pointer to a null-terminated Unicode string. This is the host name of the server to which the RPC method is issued.

DcName: The pointer to a null-terminated Unicode DC host name string.

Timeout: The time period, in seconds, that the server uses the specified DC when storing and retrieving domain-based DFS metadata. This is valid only when the NET_DFS_SETDC_TIMEOUT bit of the Flags parameter is set.

Flags: The bit field specifying additional operations to perform. Possible values are as follows.

Value

Meaning

NET_DFS_SETDC_FLAGS

0x00000000

Indicates that no additional operation is requested.

NET_DFS_SETDC_TIMEOUT

0x00000001

Sets the time-out value based on the Timeout parameter.

NET_DFS_SETDC_INIT_PKT

0x00000002

Instructs the called server to reload its DFS metadata from the specified DC.

All other bits are reserved and MUST NOT be used. If reserved bits are specified, the server MAY fail the call with an implementation-defined failure value.<133>

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.

0x00000005

ERROR_ACCESS_DENIED

Permission to perform the operation was denied.

Servers MAY choose not to implement this method or implement it as a method with no effect that returns ERROR_SUCCESS.<134>

Otherwise, the server MUST update the DC it uses for accessing DFS metadata for the domain-based DFS namespace it is hosting with the specified DC. If no time-out is specified in the Timeout parameter (NET_DFS_SETDC_TIMEOUT is not set in the Flags parameter), the server MUST use its default time-out. The DC the server uses at the end of this time-out is implementation-defined.

When NET_DFS_SETDC_INIT_PKT is set in the Flags parameter, the server SHOULD initiate a background synchronization of the domain-based DFS namespace it is hosting with either the DC specified by this method or the default DC the server is using. This MUST be treated as functionally equivalent to receiving a NetrDfsSetInfo (Opnum 3) method with the Level parameter value 101 and the State field of DFS_INFO_101 set to DFS_VOLUME_STATE_RESYNCHRONIZE.<135>