Partager via

Control Code Architecture

  • Article

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:

Name Value
CLUS_OBJECT_CLUSTER
 0x40
CLUS_OBJECT_GROUP
 0x04
CLUS_OBJECT_NETWORK
 0x10
CLUS_OBJECT_NETINTERFACE
 0x20
CLUS_OBJECT_NODE
 0x08
CLUS_OBJECT_RESOURCE
 0x01
CLUS_OBJECT_RESOURCE_TYPE
 0x02
CLUS_OBJECT_USER
 0x80

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:

Name Value
CLUS_NOT_GLOBAL
 0x0
CLUS_GLOBAL<<CLCTL_GLOBAL_SHIFT
 0x800000

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:

Name Value
CLUS_NO_MODIFY
 0x0
CLUS_MODIFY<<CLCTL_MODIFY_SHIFT
 0x400000

User Bit (bit 21)

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

Name Value
CLCTL_CLUSTER_BASE
 0x0
CLCTL_USER_BASE
 0x200000

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:

Name Value
External
 0x0
Internal (1<<CLCTL_INTERNAL_SHIFT)
 0x100000

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:

Name Value
CLUS_ACCESS_ANY
 0x0
CLUS_ACCESS_READ
 0x1
CLUS_ACCESS_WRITE
 0x2