DsGetDcOpenW function (dsgetdc.h)

Article
02/09/2023

The DsGetDcOpen function opens a new domain controller enumeration operation.

Syntax

DSGETDCAPI DWORD DsGetDcOpenW(
  [in]           LPCWSTR DnsName,
  [in]           ULONG   OptionFlags,
  [in, optional] LPCWSTR SiteName,
  [in, optional] GUID    *DomainGuid,
  [in, optional] LPCWSTR DnsForestName,
  [in]           ULONG   DcFlags,
  [out]          PHANDLE RetGetDcContext
);

Parameters

[in] DnsName

Pointer to a null-terminated string that contains the domain naming system (DNS) name of the domain to enumerate the domain controllers for. This parameter cannot be NULL.

[in] OptionFlags

Contains a set of flags that modify the behavior of the function. This can be zero or a combination of one or more of the following values.

DS_ONLY_DO_SITE_NAME

Only site-specific domain controllers are enumerated.

DS_NOTIFY_AFTER_SITE_RECORDS

The DsGetDcNext function will return the ERROR_FILEMARK_DETECTED value after all of the site-specific domain controllers are retrieved. DsGetDcNext will then enumerate the second group, which contains all domain controllers in the domain, including the site-specific domain controllers contained in the first group.

[in, optional] SiteName

Pointer to a null-terminated string that contains the name of site the client is in. This parameter is optional and may be NULL.

[in, optional] DomainGuid

Pointer to a GUID value that contains the identifier of the domain specified by DnsName. This identifier is used to handle the case of a renamed domain. If this value is specified and the domain specified in DnsName is renamed, this function attempts to enumerate domain controllers in the domain that contains the specified identifier. This parameter is optional and may be NULL.

[in, optional] DnsForestName

Pointer to a null-terminated string that contains the name of the forest that contains the DnsName domain. This value is used in conjunction with DomainGuid to enumerate the domain controllers if the domain has been renamed. This parameter is optional and may be NULL.

[in] DcFlags

Contains a set of flags that identify the type of domain controllers to enumerate. This can be zero or a combination of one or more of the following values.

DS_FORCE_REDISCOVERY

Forces cached domain controller data to be ignored. When this flag is not specified, DsGetDcOpen obtains the domain controller enumeration from cached domain controller data.

DS_GC_SERVER_REQUIRED

Requires that the enumerated domain controllers be global catalog servers for the forest of domains with this domain as the root. This flag cannot be combined with the DS_PDC_REQUIRED flag.

DS_KDC_REQUIRED

Requires that the enumerated domain controllers currently be running the Kerberos Key Distribution Center service. This flag cannot be combined with the DS_PDC_REQUIRED or DS_GC_SERVER_REQUIRED flags.

DS_ONLY_LDAP_NEEDED

Specifies that the enumerated servers are LDAP servers. The servers are not necessarily domain controllers. No other services are implied to be present at each enumerated server. The servers do not necessarily have a writable config container nor a writable schema container. The servers may not necessarily be used to create or modify security principles. This flag may be used with the DS_GC_SERVER_REQUIRED flag to enumerate LDAP servers that also host a global catalog server. In that case, the enumerated global catalog servers are not necessarily domain controllers and other services are implied to be present at each server. If this flag is specified, the DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED, and DS_KDC_REQUIRED flags are ignored.

DS_PDC_REQUIRED

Requires that the enumerated domain controllers be the primary domain controllers for the domain. This flag cannot be combined with the DS_GC_SERVER_REQUIRED flag.

[out] RetGetDcContext

Pointer to a HANDLE value that receives the domain controller enumeration context handle. This handle is used with the DsGetDcNext function to identify the domain controller enumeration operation. This handle is passed to DsGetDcClose to close the domain controller enumeration operation.

Return value

Returns ERROR_SUCCESS if successful or a Win32 or RPC error otherwise. Possible error values include the following.

Remarks

Note

The dsgetdc.h header defines DsGetDcOpen as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsgetdc.h
Library	Netapi32.lib
DLL	Netapi32.dll