3.1.4.2.129 ApiOnlineGroupEx (Opnum 130)

  • Article

(Protocol Version 3) The ApiOnlineGroupEx method SHOULD<109> instruct the server to make all the resources in the designated group active or available on the node that is hosting the group. The persistent state of the group is set to Online and is updated in the nonvolatile cluster state.

The server MUST handle this method in the same manner as ApiOnlineGroup (section 3.1.4.2.50) except as follows:

  • If the CLUSAPI_GROUP_ONLINE_IGNORE_RESOURCE_STATUS flag is set in the dwOnlineFlags parameter, the server MUST ignore the locked mode value of the group designated by the hGroup parameter.

  • If the CLUSAPI_GROUP_ONLINE_SYNCHRONOUS flag is set in the dwOnlineFlags parameter, the server MUST perform the operation synchronously to bring the group designated by the hGroup parameter online.

  • If the CLUSAPI_GROUP_ONLINE_BEST_POSSIBLE_NODE flag is set in the dwOnlineFlags parameter, the server MUST determine the best possible node that will host the group designated by the hGroup parameter.

  • If the CLUSAPI_GROUP_ONLINE_IGNORE_AFFINITY_RULE flag is set in the dwOnlineFlags parameter, the server MUST ignore the affinity rule of the group designated by the hGroup parameter.

  • For each resource contained in the group designated by the hGroup parameter that is not in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST provide the buffer specified by the lpInBuffer parameter to the server implementation-specific object that controls the resource operation while bringing the resource online.

The server MUST accept an ApiOnlineGroupEx request only if it is in the read/write state, as specified in section 3.1.1.

The server MUST require that the access level associated with the hGroup parameter is "All" (section 3.1.4).

 error_status_t ApiOnlineGroupEx(
   [in] HGROUP_RPC hGroup,
   [in] DWORD dwOnlineFlags,
   [in, size_is(cbInBufferSize)] BYTE* lpInBuffer,
   [in] DWORD cbInBufferSize,
   [out] error_status_t *rpc_status
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous call to ApiOpenGroup (section 3.1.4.2.42), ApiOpenGroupEx (section 3.1.4.2.118), or ApiCreateGroup (section 3.1.4.2.43).

dwOnlineFlags: A bitwise-OR of zero or more of the following flags.

Value

Description

0x00000001

CLUSAPI_GROUP_ONLINE_IGNORE_RESOURCE_STATUS

The server MUST ignore the locked mode of the group as specified in section 3.1.1.1.4.

0x00000002

CLUSAPI_GROUP_ONLINE_SYNCHRONOUS

The server MUST perform the operation synchronously to bring the group online.<110>

0x00000004

CLUSAPI_GROUP_ONLINE_BEST_POSSIBLE_NODE

The server MUST determine the best possible node that will host the group when it is brought online.<111>

0x00000008

CLUSAPI_GROUP_ONLINE_IGNORE_AFFINITY_RULE

The server MUST ignore the affinity rule of the group.<112>

lpInBuffer: A pointer to a buffer that the server will provide to implementation-specific objects that control the resource operations for each resource in the group. The client SHOULD set this parameter to a PROPERTY_LIST (section 2.2.3.10). For each value in this list, the client SHOULD set the property name to the name of the resource type of one of the resources in the group. The client MAY provide a buffer that does not have a property value corresponding to each resource type in the group, and the client MAY provide a buffer that has multiple property values for the same resource type. Except for the following property values, the server MUST treat all property values provided by the client identically.

Property Name

CLUSTER_PROPERTY_FORMAT

Value

Description

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000004

Reserved for local use.

cbInBufferSize: The size in bytes of the buffer pointed to by the lpInBuffer parameter.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: This method MUST return the same error codes as specified for ApiOnlineGroup (section 3.1.4.2.50), in addition to the following return value.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

The dwOnlineFlags parameter is not one of the specified values.