3.1.4.2.135 ApiOfflineResourceEx (Opnum 136)

  • Article

(Protocol Version 3) The ApiOfflineResourceEx SHOULD<121> instruct the server to make the designated resource inactive or unavailable on the node that currently owns it.

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

  • If the CLUSAPI_RESOURCE_OFFLINE_IGNORE_RESOURCE_STATUS flag is set in the dwOfflineFlags parameter, the server MUST ignore the locked mode value of the resource designated by the hResource parameter as well as the locked mode value of any of its dependent resources as specified in section 3.1.1.1.2.

  • If the CLUSAPI_RESOURCE_OFFLINE_FORCE_WITH_TERMINATION flag is set in the dwOfflineFlags parameter, the server MUST shut down the resource designated by the hResource parameter.

  • If the CLUSAPI_RESOURCE_OFFLINE_DO_NOT_UPDATE_PERSISTENT_STATE flag is set in the dwOfflineFlags parameter, the server MUST not update the persistent state of the resource designated by the hResource parameter when it is brought offline.

  • If the resource designated by the hResource parameter is in the ClusterResourceOnline state (section 3.1.4.2.13), then the server MUST provide the buffer designated by the lpInBuffer parameter to the server implementation-specific object that controls the resource operation while bringing the resource offline. The server MUST also provide this buffer to the server implementation-specific objects for any of the designated resource's dependent resources that are also in the ClusterResourceOnline state. How the server provides this buffer is implementation-specific.

The server MUST accept an ApiOfflineResourceEx 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 hResource parameter is "All" (section 3.1.4).

 error_status_t ApiOfflineResourceEx(
   [in] HRES_RPC hResource,
   [in] DWORD dwOfflineFlags,
   [in, size_is(cbInBufferSize)] BYTE* lpInBuffer,
   [in] DWORD cbInBufferSize,
   [out] error_status_t *rpc_status
 );

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

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

Value

Description

0x00000001

CLUSAPI_RESOURCE_OFFLINE_IGNORE_RESOURCE_STATUS

The server MUST ignore the locked mode value of the resource as well as the locked mode value of any of its dependent resources as specified in section 3.1.1.1.2.

0x00000002

CLUSAPI_RESOURCE_OFFLINE_FORCE_WITH_TERMINATION

The server MUST shut down the resource.

0x00000004

CLUSAPI_RESOURCE_OFFLINE_DO_NOT_UPDATE_PERSISTENT_STATE

The server MUST not update the persistent state of the resource when it is brought offline.<122>

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

0x00000000

For a resource of resource type "Virtual Machine" that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST turn off the corresponding virtual machine.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000001

For a resource of resource type "Virtual Machine" that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST save the corresponding virtual machine.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000002

For a resource of resource type "Virtual Machine" that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST shut down the corresponding virtual machine.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000003

For a resource of resource type "Virtual Machine" that is in the ClusterResourceOnline state (section 3.1.4.2.13), the server MUST forcibly shut down the corresponding virtual machine.

Virtual Machine

CLUSPROP_FORMAT_DWORD

0x00000000

Reserved.

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 returned by the ApiOfflineResource (section 3.1.4.2.19) method, in addition to the following return value.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

The dwOfflineFlags parameter is not one of the specified values.