To perform an operation using a control code, an application calls one of the following control code functions defined in the Cluster API:
When a call is made to ClusterGroupControl, ClusterNodeControl, ClusterNetworkControl, or ClusterNetInterfaceControl, the Cluster Service performs the operation and returns to the caller. When a call is made to either ClusterResourceControl or ClusterResourceTypeControl, the Cluster Service calls the Resource Monitor to perform the operation. The Resource Monitor will in turn call the resource DLL's ResourceControl or ResourceTypeControl entry point function.
The Resource Monitor always gives the resource DLL the opportunity to process a control code and performs the processing only if the resource DLL is unable to do so. The following situations indicate when a resource DLL might request the help of the Resource Monitor in processing a control code:
Resource DLLs can choose whether or not to support most of the resource and resource type control codes. However, they should support at least the following control codes for manipulating private properties:
There are two other control codes that a resource DLL must support under certain conditions: CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES and CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS. If a resource DLL handles resources that have required dependencies, the DLL must support CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES. If a resource DLL needs to replicate a portion of the system registry, it must support CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.
Resource DLLs can fully or partially support a control code. With full support, the resource DLL performs the operation described by the control code without help from the Resource Monitor. With partial support, the resource DLL and the Resource Monitor work together to perform the operation.
The control code functions share some of the same parameters and operate in a similar fashion. In addition to the control code that describes the operation to be performed, the functions include an input buffer to hold information needed for processing and an output buffer to hold information resulting from the processing in the parameter list.
Depending on the operation, either the input buffer or the output buffer may be unused. Operations to retrieve data typically do not use input buffers; operations to update data typically do not use output buffers. For example, the CLUSCTL_RESOURCE_GET_FLAGS control code is used to retrieve the attributes that can be set for a resource. When an application calls ClusterResourceControl with this control code and a null input buffer parameter, the function returns an output buffer with a bitmask indicating the flags that are set for the resource. The CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code updates the common properties of a resource. The new property settings must be passed in the input buffer when ClusterResourceControl is called. The output buffer is unused.
Data in the input and output buffers must fall on a DWORD boundary. Cluster Server defines several structures that can be used to work with data passed to or from a control code function. There are structures that describe specific types of data values, such as CLUSPROP_SZ to describe a character string and CLUSPROP_BINARY to describe binary data. These structures are used as entries in value and property lists, arrays that describe multiple data values.
For information about the layout of property and value lists, see About Property Lists and About Value Lists.
For information about individual structures, see Cluster Structures.