Directory Services

DsRoleGetPrimaryDomainInformation

The DsRoleGetPrimaryDomainInformation function retrieves state data for the computer. This data includes the state of the directory service installation and domain data.

DWORD DsRoleGetPrimaryDomainInformation(
  LPCWSTR lpServer,
  DSROLE_PRIMARY_DOMAIN_INFO_LEVEL InfoLevel,
  PBYTE* Buffer
);

Parameters

lpServer
[in] Pointer to null-terminated Unicode string that contains the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.

If this parameter refers to a Windows NT® 4.0 computer, state data can be retrieved only if the InfoLevel parameter contains DsRolePrimaryDomainInfoBasic.

InfoLevel
[in] Contains one of the DSROLE_PRIMARY_DOMAIN_INFO_LEVEL values that specify the type of data to retrieve. This parameter also determines the format of the data supplied in Buffer. The following values are currently supported.
Value Meaning
DsRolePrimaryDomainInfoBasic Buffer will receive a pointer to a DSROLE_PRIMARY_DOMAIN_INFO_BASIC structure.
DsRoleUpgradeStatus Buffer will receive a pointer to a DSROLE_UPGRADE_STATUS_INFO structure.
DsRoleOperationState Buffer will receive a pointer to a DSROLE_OPERATION_STATE_INFO structure.
Buffer
[out] Pointer to the address of a buffer that receives the requested data. The format of this data depends on the value of the InfoLevel parameter.

The caller must free this memory when it is no longer required by calling DsRoleFreeMemory.

Return Values

If the function is unsuccessful, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following values.

Return Code Description
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_ENOUGH_MEMORY A memory allocation failure occurred.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Header: Declared in Dsrole.h.
Library: Use Netapi32.lib.

See Also

DSROLE_PRIMARY_DOMAIN_INFO_BASIC, DSROLE_UPGRADE_STATUS_INFO, DSROLE_OPERATION_STATE_INFO, DsRoleFreeMemory, Directory Service Functions