3.1.4.2.18 ApiOnlineResource (Opnum 17)

(Protocol Version 3) The ApiOnlineResource method instructs the server to make the specified resource active or available on the node that currently owns it.

For a successful completion of this method, the server MUST execute any implementation-specific methods and protocols between servers to transition the specified resource to the ClusterResourceOnline 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 either the ClusterResourceInitializing, ClusterResourceOnline, ClusterResourceOffline, or 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 ClusterResourceOnline. Thereafter, the cluster SHOULD continue to take appropriate steps to maintain this resource in the ClusterResourceOnline state, regardless of the success or failure of this immediate attempt.

If the designated resource is in the ClusterResourceOnline state, the server MUST complete the method with ERROR_SUCCESS (0x00000000).

If the designated resource is in the ClusterResourceInitializing state, the server MUST first transition the resource to the ClusterResourceOffline state before attempting to transition the resource to the ClusterResourceOnline state.

The server MUST adhere to the rules of dependency relations, as specified in section 3.1.1.1.2. In particular, if the specified resource has one or more simple dependencies, the server MUST first bring online the resources that this resource depends on. If the specified resource has one or more complex dependencies, the server MUST bring online at least one resource in each set of resources in each complex dependency relation.

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

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

Whether the online procedure is executed synchronously or asynchronously, if the resource fails to come online and its state is thus set to ClusterResourceFailed, the server SHOULD attempt recovery action, such as attempting to bring the resource online again on the same node or attempting to bring the resource online on a different node. Recovery actions SHOULD be triggered when the resource persistent state is ClusterResourceOnline but the current resource state is ClusterResourceFailed or ClusterResourceOffline. Recovery actions are configured and executed by using implementation-specific methods between servers. The server MUST update the resource state in accordance with the success or failure of the recovery actions.

The server SHOULD store, in the resource configuration in the nonvolatile cluster state, preferences for and limitations on how and where (for example, which owner node) a resource can come online. The server SHOULD customize the online procedure according to these policies. These policies are configured and executed by using implementation-specific methods between servers.

The cluster, meaning one or more active cluster nodes, SHOULD monitor the health of all resources that are online in the cluster. In this manner, the cluster detects resource failure if a resource is expected to be online. If the cluster detects that a resource has failed, the cluster SHOULD attempt to perform recovery actions, such as attempting to bring the resource online again on the same node or attempting to bring the resource online on a different node. Resource health detection and recovery actions are executed by using implementation-specific mechanisms and methods between servers.

The server fails this method using the error ERROR_CLUSTER_RESOURCE_LOCKED_STATUS if the resource or any of its providers are in locked mode, as specified in section 3.1.1.1.4.

The server MUST accept an ApiOnlineResource 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 ApiOnlineResource(
   [in] HRES_RPC hResource,
   [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.

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 functional. The resource transitioned to the ClusterResourceOnlinePending state.
0x00000046 ERROR_SHARING_PAUSED	Either the node that owns the designated resource is in the ClusterNodePaused state or the current protocol server state of the server is not read/write.
0x0000138E ERROR_RESOURCE_NOT_AVAILABLE	The cluster resource is not available.
0x0000139F ERROR_INVALID_STATE	The group or resource is not in the correct state to perform the requested operation.
0x00001736 ERROR_CLUSTER_RESOURCE_PROVIDER_FAILED	The resource failed to come online due to the failure of one or more provider resources.

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.