CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code

Under certain circumstances, the cluster sends the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code to a resource DLL immediately before calling the Offline or Terminate entry-point function, providing the DLL with the reason for the state change. Because the control code is internal, applications cannot use it in a control code function.

Parameters

This control code has no parameters.

Return value

This control code does not return a value.

Remarks

ClusAPI.h defines the 32 bits of CLUSCTL_RESOURCE_STATE_CHANGE_REASON (0x0150004e) as follows.

Component Bit location Value
Object code
24 31
CLUS_OBJECT_RESOURCE (0x1)
Global bit
23
CLUS_NOT_GLOBAL (0x0)
Modify bit
22
CLUS_MODIFY (0x1)
User bit
21
CLCTL_CLUSTER_BASE (0x0)
Type bit
20
Internal (0x1)
Operation code
0 23
CLCTL_STATE_CHANGE_REASON (0x50004e)
Access code
0 1
CLUS_ACCESS_WRITE (0x2)

For more information, see Control Code Architecture.

Resource DLL Support

Optional. By default, resource DLLs do not receive the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code under any circumstances. To receive the control code, a resource DLL must report the following characteristic: CLUS_CHAR_REQUIRES_STATE_CHANGE_REASON.

For information on how to report characteristics for your resource DLL see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.

The CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code gives resource DLLs the option of implementing different shutdown procedures in response to different shutdown conditions. For example, a resource DLL may implement a graceful, clean shutdown under most circumstances, but if the Cluster service stops unexpectedly, the DLL may implement a fast and dirty brute-force shutdown to facilitate faster failover.

To support CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code in your resource DLL, perform the following steps:

  • Initialize a CLUSCTL_RESOURCE_STATE_CHANGE_REASON_STRUCT structure for each resource managed by the resource DLL. Typically this structure is included in the resource DLL's resource structure.

  • In your implementation of ResourceControl:

    • Handle the CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code and return a value that includes CLUS_CHAR_REQUIRES_STATE_CHANGE_REASON.
    • Handle the CLUSCTL_RESOURCE_STATE_CHANGE_REASON control code and store the reason code passed in the lpInBuffer parameter in the eReason member of the resource structure.
  • When implementing Offline and Terminate, read the eReason member of the resource structure and, if this member is not eResourceStateChangeReasonUnknown (from the CLUSTER_RESOURCE_STATE_CHANGE_REASON enumeration), perform any necessary operations. Before returning from Offline or Terminate, reset the eReason member of the resource structure to eResourceStateChangeReasonUnknown.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Requirements

Minimum supported client
None supported
Minimum supported server
Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Header
ClusAPI.h

See also

Internal Resource Control Codes

ResourceControl

CLUSCTL_RESOURCE_STATE_CHANGE_REASON_STRUCT

CLUSTER_RESOURCE_STATE_CHANGE_REASON