Control Code Architecture

If you want to create your own control codes, you will need to refer to the information in this section. You do not need to know how control codes are defined in order to use them in control code functions. However, understanding the internal architecture of control codes can help you use them more efficiently.

Control codes consist of seven smaller numbers arranged to form a 32-bit value. The bit layout is shown in the following illustration:

Object Code (bits 24 31)

The 8-bit object component indicates the type of cluster object to which the control code applies. Possible values are enumerated by the CLUSTER_CONTROL_OBJECT enumeration:

All of the values except CLUS_OBJECT_USER represent object types defined by Windows Failover Clustering.

These values are shifted left CLCTL_OBJECT_SHIFT (24) bits in the cluster control value.

Global Bit (bit 23)

The global bit indicates whether the control code represents a global operation that must be performed on each cluster node. Their possible values are the following:

The CLUSCTL_RESOURCE_STORAGE_CLUSTER_DISK and CLUSCTL_RESOURCE_NETNAME_CREDS_UPDATED control codes are the only global control codes.

Modify Bit (bit 22)

The modify bit indicates whether the control code causes a modification to data that, in turn, may generate an event notification. Possible values:

User Bit (bit 21)

The user bit indicates whether the control code is user-defined or defined by Windows Failover Clustering. Possible values:

Internal/External Bit (bit 20)

The internal/external bit categorizes the control code as either internal or external. Internal control codes set this bit; external control codes do not. An internal control code can be used only by the Cluster service, meaning that applications cannot pass internal control codes as parameters to the control functions of the Cluster API. Internal control codes are typically sent by the Cluster service to notify a resource or resource typeof an event. The external control codes are used by applications to initiate an operation. Their possible values are the following:

Operation Code (bits 0 19)

The operation code describes the operation that a control code will perform. The procedures for using control codes that have different object codes but the same operation code are nearly identical. For more information, see Using Control Codes.

The following operation codes apply to all or most cluster objects:

• CLCTL_ENUM_COMMON_PROPERTIES
• CLCTL_ENUM_PRIVATE_PROPERTIES
• CLCTL_GET_CHARACTERISTICS
• CLCTL_GET_COMMON_PROPERTIES
• CLCTL_GET_COMMON_PROPERTY_FMTS
• CLCTL_GET_FLAGS
• CLCTL_GET_ID (not for resources or resource types)
• CLCTL_GET_NAME
• CLCTL_GET_PRIVATE_PROPERTIES
• CLCTL_GET_PRIVATE_PROPERTY_FMTS
• CLCTL_GET_RO_COMMON_PROPERTIES
• CLCTL_GET_RO_PRIVATE_PROPERTIES
• CLCTL_SET_COMMON_PROPERTIES
• CLCTL_SET_PRIVATE_PROPERTIES
• CLCTL_UNKNOWN
• CLCTL_VALIDATE_COMMON_PROPERTIES
• CLCTL_VALIDATE_PRIVATE_PROPERTIES

ClusAPI.h defines other operation codes that are object-specific, particularly for resources and resource types. For a complete list, see the CLCTL_CODES enumeration.

Access Code (bits 0 1)

The access code (the lower two bits of the Operation Code) indicates whether the initiator of the request requires any specific type of access to perform the operation described by the operation code. Possible values: