3.1.4.2.26 ApiChangeResourceGroup (Opnum 25)

  • Article

(Protocol Version 3) The ApiChangeResourceGroup method moves the designated resource and all the resources in its dependency tree out of its current group and into the designated group. The nonvolatile cluster state is updated to reflect this change.

The server MUST fail this method if the resource is already a member of the group designated by hGroup. In this event, the server MUST return ERROR_ALREADY_EXISTS.

The server MUST fail this method using ERROR_RESOURCE_ONLINE if the destination group is hosted on another node and hResource or any of its dependents are not in the Offline or Failed state.

The server MUST fail this method using ERROR_HOST_NODE_NOT_RESOURCE_OWNER if the destination group is currently hosted by a different node than the current group and if the node hosting the destination group is not a possible owner for the resource or any of its dependents (no DLL, or not in possible owner's list).

The server MUST fail this method using ERROR_CLUSTER_GROUP_SINGLETON_RESOURCE if the resource has indicated via its characteristics that only one resource of its type is permitted in a group and a resource of that type already exists in the destination group.

The server fails this method using ERROR_CLUSTER_RESOURCE_LOCKED_STATUS if either the group that owns the specified resource is in locked mode or the specified target group is in locked mode, as specified in section 3.1.1.1.4.

The resource state sequence number MUST be monotonically incremented when the resource is transferred to another group.

The server MUST accept an ApiChangeResourceGroup request for processing 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 hResource context handle is "All" and that the access level associated with the hGroup context handle is "All" (section 3.1.4).

 error_status_t ApiChangeResourceGroup(
   [in] HRES_RPC hResource,
   [in] HGROUP_RPC hGroup,
   [out] error_status_t *rpc_status
 );

hResource: An HRES_RPC (section 2.2.1.4) context handle that was obtained in a previous ApiOpenResource (section 3.1.4.2.9), ApiOpenResourceEx (section 3.1.4.2.119), or ApiCreateResource (section 3.1.4.2.10) method call.

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

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: The method MUST return the following error codes for the specified conditions.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Success.

0x00000006

ERROR_INVALID_HANDLE

Either the hResource parameter does not represent a valid HRES_RPC (section 2.2.1.4) context handle or the hGroup parameter does not represent a valid HGROUP_RPC (section 2.2.1.3) context handle.

0x000000B7

ERROR_ALREADY_EXISTS

See the preceding text for when this error can occur.

0x0000138E

ERROR_RESOURCE_NOT_AVAILABLE

The resource represented by the hResource parameter no longer exists in the nonvolatile cluster state.

0x00001394

ERROR_GROUP_NOT_AVAILABLE

The group represented by the hGroup parameter no longer exists in the nonvolatile cluster state.

0x0000139B

ERROR_RESOURCE_ONLINE

See the preceding text for details of when this error can occur.

0x00001735

ERROR_CLUSTER_GROUP_SINGLETON_RESOURCE

See the preceding text for details of when this error can occur.

0x00001397

ERROR_HOST_NODE_NOT_RESOURCE_OWNER

The operation failed because the destination group is currently hosted by a different node than the current group, and the node hosting the destination group is not a possible owner for the resource (or at least one of the resource's dependents).

0x00001728

ERROR_QUORUM_NOT_ALLOWED_IN_THIS_GROUP

Quorum resource cannot reside in the available storage group.

0x0000173C

ERROR_CLUSTER_USE_SHARED_VOLUMES_API

The group or resource cannot be directly manipulated. Use shared volume APIs to perform the required operation.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values that are not listed in the preceding table the same, except as specified in section 3.2.4.6.