3.1.4.2.19 ApiOfflineResource (Opnum 18)

(Protocol Version 3) The ApiOfflineResource method instructs the server to make the specified resource inactive or unavailable.

For a successful completion of this method, the server MUST execute any implementation-specific methods and protocols between servers in order to transition the specified resource to the ClusterResourceOffline state, as specified in section 3.1.4.2.13.

The server MUST fail this method with ERROR_INVALID_STATE (0x0000139F) if the specified resource is not in the ClusterResourceOnline state, the ClusterResourceOffline state, or the ClusterResourceFailed state, as specified in section 3.1.4.2.13.

Otherwise, the server MUST update the persistent state in the configuration of the resource to be ClusterResourceOffline, indicating that the cluster SHOULD NOT attempt to maintain the resource in the ClusterResourceOnline state.

If the resource is in the ClusterResourceOffline state, the server MUST complete the method with ERROR_SUCCESS (0x00000000). If the resource is in the ClusterResourceFailed state, the server MUST complete the method with ERROR_RESOURCE_FAILED (0x000013AE).

The server MUST adhere to the rules of dependency relations, as specified in section 3.1.1.1.2. In particular, if there are one or more resources with a simple dependency on the designated resource, the server MUST first bring offline the resources that depend on the designated resource before it brings offline the designated resource. If the designated resource is in a complex dependency set, and if it is the only resource in that set that is online, the server MUST first bring offline the resources that depend on the designated resource's complex dependency set before it brings offline the designated resource.

Depending on how the resource type of the designated resource specifies the procedure of bringing the resource offline, the server MAY complete this method while the offline procedure is executed asynchronously. In this case, the server MUST transition the resource to the ClusterResourceOfflinePending state, as specified in section 3.1.4.2.13, and return 0x000003E5 (ERROR_IO_PENDING). After the completion of the offline procedure, depending on whether the procedure succeeded or failed, the server MUST set the resource state to ClusterResourceOffline or ClusterResourceFailed, respectively.

If the server executes the full offline procedure synchronously, and if the resource fails to come offline, the server MUST return a nonzero error code other than 0x000003E5 (ERROR_IO_PENDING) and set the resource state to ClusterResourceFailed.

Whether the offline procedure is executed synchronously or asynchronously, if the resource fails to come offline and its state is thus set to ClusterResourceFailed, the server SHOULD NOT attempt recovery action. Recovery actions SHOULD NOT be triggered when the resource persistent state is ClusterResourceOffline and the current resource state is ClusterResourceFailed or ClusterResourceOffline. Recovery actions are configured and executed by using implementation-specific methods between servers.

The server fails this method using the error ERROR_CLUSTER_RESOURCE_LOCKED_STATUS if the designated resource, or any resources that need to be made offline according to the dependency relations, are in locked mode as specified in section 3.1.1.1.4.

The server MUST accept an ApiOfflineResource request only if its protocol server state is read/write, as specified in section 3.1.1.

The server MUST require that the access level associated with the hResource context handle is "All" (section 3.1.4).

 error_status_t ApiOfflineResource(
   [in] HRES_RPC hResource,
   [out] error_status_t *rpc_status
 );

hResource: An HRES_RPC (section 2.2.1.4) context handle that is 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.

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	The data that is pointed to by the hResource parameter does not represent a valid HRES_RPC (section 2.2.1.4) context handle.
0x000003E5 ERROR_IO_PENDING	The resource is in the process of becoming inactive or unavailable. The resource transitioned to the ClusterResourceOfflinePending state.
0x0000138E ERROR_RESOURCE_NOT_AVAILABLE	The cluster resource is not available.
0x0000139F ERROR_INVALID_STATE	The resource represented by hResource is not in the ClusterResourceOnline state, the ClusterResourceOffline state, or the ClusterResourceFailed state, as specified in section 3.1.4.2.13.
0x000013AE ERROR_RESOURCE_FAILED	The resource represented by hResource is in the ClusterResourceFailed state, as specified in section 3.1.4.2.13.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in section 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.