3.2.5.1 DsRolerGetPrimaryDomainInformation (Opnum 0)

  • Article

The DsRolerGetPrimaryDomainInformation (Opnum 0) method returns the requested information about the current configuration or state of the computer on which the server is running.

 DWORD DsRolerGetPrimaryDomainInformation(
   [in] handle_t hBinding,
   [in] DSROLE_PRIMARY_DOMAIN_INFO_LEVEL InfoLevel,
   [out, switch_is(InfoLevel)] PDSROLER_PRIMARY_DOMAIN_INFORMATION* DomainInfo
 );

hBinding: An RPC binding handle, as specified in [C706] section 2.3.1.

InfoLevel: The type of data requested by the client. For possible values in this enumeration, see section 2.2.7.

DomainInfo: The requested information that the server provides to the client. The value of the InfoLevel parameter indicates the type of information that is requested; information is returned in the corresponding member of the DSROLER_PRIMARY_DOMAIN_INFORMATION union.

Return Values: The method returns 0 if successful; if failed, it returns a nonzero error code as specified in [MS-ERREF]. Specifically, in addition to any other error codes, the server MUST return the following error codes for the following error conditions. Any other values transmitted in this field are implementation-specific. All nonzero values MUST be treated the same for protocol purposes.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

One or more parameters are invalid.

0x00000008

ERROR_NOT_ENOUGH_MEMORY

A memory allocation failure occurred.

This method obtains the identity and authorization information about the client from the underlying RPC runtime. Servers that implement this method SHOULD impose an authorization policy decision before performing the function.<13>

The server determines the appropriate response to the request by examining the InfoLevel parameter, setting the appropriate fields in the DomainInfo parameter and sending the response to the caller.

The following describes which fields are used and what the fields contain for each InfoLevel value.

DsRolePrimaryDomainInfoBasic

When the InfoLevel is DsRolePrimaryDomainInfoBasic, the server MUST use the DomainInfoBasic field of the DomainInfo parameter, whose type is DSROLER_PRIMARY_DOMAIN_INFO_BASIC. The result MUST be constructed in the following manner:

  1. Determine the role of the server and set the MachineRole field of DomainInfoBasic according to the ComputerRole state element. If the server ComputerRole state element indicates that it is not a stand-alone computer, set the DomainNameFlat, DomainNameDns, DomainForestName, and DomainGuid fields of the DomainInfoBasic structure according to the NetBIOSDomainName, DNSDomainName, ForestName, and DomainGUID state information. If the DomainGUID state element is non-empty, the DSROLE_PRIMARY_DOMAIN_GUID_PRESENT bit MUST be set in the Flags member of DomainInfoBasic.

  2. If the server is a stand-alone computer, set the DomainNameFlat field of DomainInfoBasic according to NetBIOSDomainName state information; and then set the other fields to NULL.

  3. If the server is a domain controller and the directory service is enabled, set the Flags member of the DomainInfoBasic structure as follows:

    1. Set the DSROLE_PRIMARY_DS_RUNNING bit.

    2. If the domain is in mixed mode, set the DSROLE_PRIMARY_DS_MIXED_MODE bit.

    3. If the server is a read-only domain controller, set the DSROLE_PRIMARY_DS_READONLY bit. The domain hosted by a read-only domain controller SHOULD<14>  be in native mode.

DsRoleUpgradeStatus

When InfoLevel is DsRoleUpgradeStatus, the server sets the requested information into the UpgradStatusInfo field of the DomainInfo parameter, whose type is DSROLE_UPGRADE_STATUS_INFO. The result MUST be constructed in the following manner:

  1. Set the OperationState field to DSROLE_UPGRADE_IN_PROGRESS if the ComputerUpgrade state element is TRUE.

  2. Set the PreviousServerState field to the PreviousServerState state element.

DsRoleOperationState

When InfoLevel is DsRoleOperationState, the server MUST return the result in the OperationStateInfo field of the DomainInfo parameter, whose type is DSROLE_OPERATION_STATE_INFO. The result MUST be constructed by setting the OperationState member of the OperationStateInfo structure according to the value of the ComputerOperationState state element.