Share via

3.1.4.5.1 NetrDfsGetDcAddress (Opnum 16)

  • Article

The NetrDfsGetDcAddress (Opnum 16) method returns the DC host name that is used by the DFS server to which the RPC method is issued.<126> The client MUST use this DC to create a domain-based DFS namespace, add a root target to a domain-based DFS namespace, remove a root target from a domain-based DFS namespace, or remove a domain-based DFS namespace.

The NetrDfsGetDcAddress method uses the following MIDL syntax.

 NET_API_STATUS NetrDfsGetDcAddress(
   [in, string] WCHAR* ServerName,
   [in, out, string] WCHAR** DcName,
   [in, out] BOOLEAN* IsRoot,
   [in, out] unsigned long* Timeout
 );

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

DcName: A null-terminated Unicode string that contains the DC host name when the NetrDfsGetDcAddress method is successful.<128>

IsRoot: A pointer to a Boolean value, set to TRUE on return if the server hosts any DFS root target, and FALSE otherwise.<129>

Timeout: A pointer to an unsigned 32-bit integer value indicating the count of seconds for which the server will use the DC that is returned to access DFS metadata.<130>

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.

A server MAY<131> implement this method if it supports domain-based DFS namespaces.

In the DcName parameter, the server SHOULD return the host name of the DC it is using to access DFS metadata for any domain-based DFS namespace that the server is hosting. If the server is not currently using a DC, it MUST determine a DC and return its name.

The server SHOULD also return a time-out value, in seconds, that is equal to the length of time that the server will be using the DC in the Timeout parameter, assuming that another RPC method does not change it.

The server uses the IsRoot parameter to specify whether it supports the ability to host more than one DFS namespace, and to indicate whether it is currently hosting a DFS namespace. If the server supports the ability to host more than one DFS namespace, it MUST return a value of FALSE in the IsRoot parameter, regardless of whether it is actually hosting a DFS namespace. If the server does not support the ability to host more than one DFS namespace, and if it currently hosts a DFS namespace, it SHOULD return a value of TRUE in the IsRoot parameter; otherwise, it SHOULD return FALSE.