Directory Services

DsGetDcOpen

The DsGetDcOpen function opens a new domain controller enumeration operation.

DWORD WINAPI DsGetDcOpen(
  LPCTSTR DnsName,
  ULONG OptionFlags,
  LPCTSTR SiteName,
  GUID* DomainGuid,
  LPCTSTR DnsForestName,
  ULONG DcFlags,
  PHANDLE RetGetDcContext
);

Parameters

DnsName
[in] 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.
OptionFlags
[in] 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.
Value Meaning
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.
SiteName
[in, optional] Pointer to a null-terminated string that contains the name of site the client is in. This parameter is optional and may be NULL.
DomainGuid
[in, optional] 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.
DnsForestName
[in, optional] 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.
DcFlags
[in] 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.
Value Meaning
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_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.
DS_WRITABLE_REQUIRED Requires that the enumerated domain controllers be writable; that is, host a writable copy of the directory service (for Windows 2000 or later domain controllers) or of SAM (for domain controllers prior to Windows 2000). A domain controllers prior to Windows 2000 is writable only if it is a primary domain controller. All Windows 2000 domain controllers are writable.
RetGetDcContext
[out] 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 Values

Returns ERROR_SUCCESS if successful or a Win32 or RPC error otherwise. Possible error values include the following.
Return Code Description
ERROR_INVALID_FLAGS Either OptionFlags or DcFlags contain invalid flags.
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_ENOUGH_MEMORY A memory allocation failure occurred.

Requirements

Client: Included in Windows XP.
Server: Included in Windows Server 2003.
Unicode: Implemented as Unicode and ANSI versions on Windows XP.
Header: Declared in Dsgetdc.h.
Library: Use Netapi32.lib.

See Also

DsGetDcNext, DsGetDcClose, Enumerating Domain Controllers, Directory Service Functions