Share via

3.1.4.1 Protocol Version 2

  • Article

Protocol Version 2.0<56> MUST indicate to the RPC runtime that it is to perform a strict NDR consistency check at target level 5.0, as specified in [MS-RPCE] section 3.

This protocol<57> MUST indicate to the RPC runtime by means of the strict_context_handle attribute that it is to reject the use of context handles that are created by a method of an RPC interface that is different from this one, as specified in [MS-RPCE] section 3.

The methods MUST NOT throw an exception except those thrown by the underlying RPC protocol [MS-RPCE], as specified in [MS-RPCE].

Any active node in the cluster MUST have protocol server state set to read/write, as specified in section 3.1.1. As such, it MUST accept ClusAPI Protocol requests from clients that have successfully completed the initialization steps, as specified in section 3.2.3. For client requests that change the cluster state, after the client request is completed, the updated state MUST be accessible to the same or other protocol clients by means of a ClusAPI Protocol session to any active node. For client requests that change non-volatile cluster state, after the client request has completed, the updated state MUST be accessible to the same or other protocol clients by means of a ClusAPI Protocol session to any active node, even after one or all nodes have failed or restarted.

Any active node in the cluster MUST accept ClusAPI Protocol requests from valid clients. A valid client is a client that has successfully completed the initialization steps as specified in section 3.2.3. For client requests that change the cluster state, after the client request is completed, the updated cluster state MUST be accessible to the same or other protocol clients by means of a ClusAPI Protocol session to any active node.

A node that is running the cluster software but is not yet an active node in the cluster SHOULD accept ClusAPI Protocol requests that do not modify the cluster state. As such, each node SHOULD locally maintain its protocol server state, which indicates the extent to which it can accept protocol requests that operate on the cluster state. A server SHOULD support the following values for protocol server state:

None: Indicates that the node has not sufficiently initialized to accept any protocol requests.

Read-Only: Indicates that the node accepts requests that do not modify the cluster state.

Read/Write: Indicates that the node accepts all requests.

If a client has successfully completed the initialization steps, as specified in section 3.2.3, and calls a method that requires greater access than the server's current protocol server state allows, as specified in section 3.1.1, the server MUST NOT accept the method request, and it MUST fail the method with error 0x00000046 (ERROR_SHARING_PAUSED).Error codes are specified in [SYSERR].

It is implementation-specific how a server determines when to stop processing protocol requests as it ceases to be an active node. For example, a server typically ceases to be an active node when the server computer is shut down or when the server software is terminated.

If a server receives a protocol request but determines that it is unable to process that request because it is no longer an active node due to server computer shut down, the server MUST return 0x0000045B (ERROR_SHUTDOWN_IN_PROGRESS) or 0x000004E7 (ERROR_SERVER_SHUTDOWN_IN_PROGRESS). If a server receives a protocol request but determines that it is unable to process that request because it is no longer an active node due to any other reason, the server MUST return 0x000013D0 (ERROR_CLUSTER_NODE_NOT_READY) or 0x000013D1 (ERROR_CLUSTER_NODE_SHUTTING_DOWN). Note that failure of the server to respond will result in an RPC error on the client, as specified in [MS-RPCE]. The client SHOULD treat all of these responses the same.

Methods in the RPC interface require that the client have appropriate security access. ClusAPI Protocol Version 2.0 has only one level of security access: "All".

The server MUST require an access level of "All" for all methods.

The server MUST treat a method invocation as an implicit request by the client for "All" access. If a client that does not have "All" access invokes a method then the server MUST fail the method with error 0x00000005 (ERROR_ACCESS_DENIED).

The server MUST determine the level of access a client can obtain from the cluster security descriptor (specified in section 3.1.1.3). Since ClusAPI Protocol Version 2.0 supports only "All" access, if the cluster security descriptor does not permit a particular client "All" access, then the server MUST fail the method with error 0x00000005 (ERROR_ACCESS_DENIED).

For methods that return one of the following context handles, the server MUST maintain with the state represented by this context handle that the client is granted "All" access.

The server MUST NOT return any of the following context handles that do not have "All" access.

  • HCLUSTER_RPC, HRES_RPC, HGROUP_RPC, HNODE_RPC, HNETWORK_RPC, or HNETINTERFACE_RPC

RPC parameters for methods in this protocol have maximum size restrictions as follows:

Methods in RPC Opnum Order

Method

Description

ApiOpenCluster

Obtains an HCLUSTER_RPC context handle to a cluster, enabling the client to issue subsequent methods pertaining to the specified cluster.

Opnum: 0

ApiCloseCluster

Instructs the server to free the context specified by the HCLUSTER_RPC context handle previously obtained by ApiOpenCluster.

Opnum: 1

ApiSetClusterName

Changes the name of the cluster.

Opnum: 2

ApiGetClusterName

Queries the cluster name and the host name of the node acting as an RPC interface server.

Opnum: 3

ApiGetClusterVersion

Queries version information about the cluster and the protocol server software.

Opnum: 4

ApiGetQuorumResource

Queries the quorum configuration for the cluster.

Opnum: 5

ApiSetQuorumResource

Changes the quorum configuration for the cluster.

Opnum: 6

ApiCreateEnum

Queries an enumeration of named objects from the cluster state.

Opnum: 7

ApiOpenResource

Obtains an HRES_RPC context handle to a resource, enabling the client to issue subsequent methods pertaining to the specified resource.

Opnum: 8

ApiCreateResource

Creates an instance of a cluster resource in the non-volatile cluster state for the specified resource type. Returns an HRES_RPC context handle to the resource, enabling the client to issue subsequent methods pertaining to the specified resource.

Opnum: 9

ApiDeleteResource

Removes the specified resource from the non-volatile cluster state.

Opnum: 10

ApiCloseResource

Instructs the server to free the context specified by the HRES_RPC context handle previously obtained by ApiOpenResource.

Opnum: 11

ApiGetResourceState

Queries the current state of the specified resource.

Opnum: 12

ApiSetResourceName

Changes the name of the specified resource.

Opnum: 13

ApiGetResourceId

Queries the unique identifier (UID) of the specified resource.

Opnum: 14

ApiGetResourceType

Queries a string identifying the resource type of the designated resource.

Opnum: 15

ApiFailResource

Initiates a failure of the specified resource. Tests the recovery policy associated with the resource.

Opnum: 16

ApiOnlineResource

Instructs the server to bring the specified resource to the online state.

Opnum: 17

ApiOfflineResource

Instructs the server to bring the specified resource to the offline state.

Opnum: 18

ApiAddResourceDependency

Instructs the server to add a simple dependency between the two specified resources.

Opnum: 19

ApiRemoveResourceDependency

Instructs the server to remove the dependency between the two specified resources.

Opnum: 20

ApiCanResourceBeDependent

Determines whether the specified resource can be dependent on another specified resource.

Opnum: 21

ApiCreateResEnum

Queries an enumeration of the resources on which the specified resource depends.

Opnum: 22

ApiAddResourceNode

Adds the specified node to the set of nodes that can host the specified resource.

Opnum: 23

ApiRemoveResourceNode

Removes the specified node from the set of nodes that can host the specified resource.

Opnum: 24

ApiChangeResourceGroup

Moves the specified resource from its current group to the specified group.

Opnum: 25

ApiCreateResourceType

Adds the specified resource type to the non-volatile cluster state.

Opnum: 26

ApiDeleteResourceType

Removes the specified resource type from the non-volatile cluster state.

Opnum: 27

ApiGetRootKey

Obtains a context handle for the root key of the cluster registry.

Opnum: 28

ApiCreateKey

Creates a key in the cluster registry and returns a context handle for the created key.

Opnum: 29

ApiOpenKey

Opens and returns a context handle to a key in the cluster registry.

Opnum: 30

ApiEnumKey

Obtains, by index, the name of a subkey of a key in the cluster registry.

Opnum: 31

ApiSetValue

Sets the data stored in a value in the cluster registry.

Opnum: 32

ApiDeleteValue

Deletes a value from the cluster registry.

Opnum: 33

ApiQueryValue

Queries the data stored in a value in the cluster registry.

Opnum: 34

ApiDeleteKey

Deletes a key from the cluster registry.

Opnum: 35

ApiEnumValue

Retrieve, by index, a value under a key in the cluster registry.

Opnum: 36

ApiCloseKey

Close a cluster registry key.

Opnum: 37

ApiQueryInfoKey

Queries information about a key in the cluster registry.

Opnum: 38

ApiSetKeySecurity

Sets the security descriptor of a key in the cluster registry.

Opnum: 39

ApiGetKeySecurity

Retrieves the security descriptor of a key in the cluster registry.

Opnum: 40

ApiOpenGroup

Obtains an HGROUP_RPC context handle to a group, enabling the client to issue subsequent methods pertaining to the specified group.

Opnum: 41

ApiCreateGroup

Creates an instance of a cluster group in the non-volatile cluster state. Returns an HGROUP_RPC context handle to the group, enabling the client to issue subsequent methods pertaining to the specified group.

Opnum: 42

ApiDeleteGroup

Removes the specified group from the non-volatile cluster state.

Opnum: 43

ApiCloseGroup

Instructs the server to free the context specified by the HGROUP_RPC context handle previously obtained by ApiOpenGroup.

Opnum: 44

ApiGetGroupState

Queries the current state of the specified group.

Opnum: 45

ApiSetGroupName

Changes the name of the specified group.

Opnum: 46

ApiGetGroupId

Queries the UID of the specified group.

Opnum: 47

ApiGetNodeId

Queries the unique identifier (UID) of the specified node.

Opnum: 48

ApiOnlineGroup

Instructs the server to bring the specified group to the ClusterGroupOnline state.

Opnum: 49

ApiOfflineGroup

Instructs the server to bring the specified resource to the ClusterGroupOffline state.

Opnum: 50

ApiMoveGroup

Instructs the server to move the group to another node in the cluster.

Opnum: 51

ApiMoveGroupToNode

Instructs the server to move the group to the specified node.

Opnum: 52

ApiCreateGroupResourceEnum

Queries an enumeration of the resources that are contained in the specified group.

Opnum: 53

ApiSetGroupNodeList

Sets a list of nodes, in order of preference, indicating where the specified group is hosted.

Opnum: 54

ApiCreateNotify

Obtains an HNOTIFY_RPC context handle to a notification port, enabling the client to issue subsequent methods pertaining to the events in the cluster.

Opnum: 55

ApiCloseNotify

Instructs the server to free the context specified by the HNOTIFY_RPC context handle previously obtained by ApiCreateNotify.

Opnum: 56

ApiAddNotifyCluster

Registers an event filter mask with the specified notification port whose scope covers all objects in the cluster.

Opnum: 57

ApiAddNotifyNode

Registers an event filter mask with the specified notification port whose scope is limited to the specified node.

Opnum: 58

ApiAddNotifyGroup

Registers an event filter mask with the specified notification port whose scope is limited to the specified group.

Opnum: 59

ApiAddNotifyResource

Registers an event filter mask with the specified notification port whose scope is limited to the specified resource.

Opnum: 60

ApiAddNotifyKey

Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster registry key.

Opnum: 61

ApiReAddNotifyNode

Re-registers an event filter mask with the specified notification port whose scope is limited to the specified node.

Opnum: 62

ApiReAddNotifyGroup

Re-registers an event filter mask with the specified notification port whose scope is limited to the specified group.

Opnum: 63

ApiReAddNotifyResource

Re-registers an event filter mask with the specified notification port whose scope is limited to the specified resource.

Opnum: 64

ApiGetNotify

Retrieves the next event from the specified notification port.

Opnum: 65

ApiOpenNode

Obtains an HNODE_RPC context handle to a node, enabling the client to issue subsequent methods pertaining to the specified node.

Opnum: 66

ApiCloseNode

Instructs the server to free the context specified by the HNODE_RPC context handle previously obtained by ApiOpenNode.

Opnum: 67

ApiGetNodeState

Queries the current state of the specified node.

Opnum: 68

ApiPauseNode

Instructs the server to pause group failover activity on the specified node.

Opnum: 69

ApiResumeNode

Instructs the server to resume group failover activity on the specified node.

Opnum: 70

ApiEvictNode

Instructs the server to remove the specified node as a configured node in the cluster.

Opnum: 71

ApiNodeResourceControl

Instructs the server to initiate an operation on the specified resource based on the specified control code. The operation is executed on the specified node.

Opnum: 72

ApiResourceControl

Instructs the server to initiate an operation on the specified resource based on the specified control code. The operation is executed on the node hosting the group that contains the resource.

Opnum: 73

ApiNodeResourceTypeControl

Instructs the server to initiate an operation on the specified resource type based on the specified control code. The operation is executed on the specified node.

Opnum: 74

ApiResourceTypeControl

Instructs the server to initiate an operation on the specified resource type based on the specified control code. The operation is executed on the node where the HCLUSTER_RPC context handle was obtained.

Opnum: 75

ApiNodeGroupControl

Instructs the server to initiate an operation on the specified group based on the specified control code. The operation is executed on the specified node.

Opnum: 76

ApiGroupControl

Instructs the server to initiate an operation on the specified group based on the specified control code. The operation is executed on the node hosting the group.

Opnum: 77

ApiNodeNodeControl

Instructs the server to initiate an operation on the specified node based on the specified control code. The operation is executed on the specified node.

Opnum: 78

ApiNodeControl

Instructs the server to initiate an operation on the specified node based on the specified control code. The operation is executed on the node where the HNODE_RPC context handle was obtained.

Opnum: 79

Opnum80NotUsedOnWire

Reserved for local use.

Opnum: 80

ApiOpenNetwork

Obtains an HNETWORK_RPC context handle to a cluster network, enabling the client to issue subsequent methods pertaining to the specified cluster network.

Opnum: 81

ApiCloseNetwork

Instructs the server to free the context specified by the HNETWORK_RPC context handle previously obtained by ApiOpenNetwork.

Opnum: 82

ApiGetNetworkState

Queries the current state of the specified cluster network.

Opnum: 83

ApiSetNetworkName

Changes the name of the specified cluster network.

Opnum: 84

ApiCreateNetworkEnum

Queries an enumeration of cluster network interface objects that are installed on the specified cluster network.

Opnum: 85

ApiGetNetworkId

Queries the unique ID of the specified cluster network.

Opnum: 86

ApiSetNetworkPriorityOrder

Sets the priority ordered list of internal cluster networks to use for internal cluster communication.

Opnum: 87

ApiNodeNetworkControl

Instructs the server to initiate an operation on the specified cluster network based on the specified control code. The operation is executed on the specified node.

Opnum: 88

ApiNetworkControl

Instructs the server to initiate an operation on the specified cluster network based on the specified control code. The operation is executed on the node where the HNETWORK_RPC context handle was obtained.

Opnum: 89

ApiAddNotifyNetwork

Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network.

Opnum: 90

ApiReAddNotifyNetwork

Re-registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network.

Opnum: 91

ApiOpenNetInterface

Obtains an HNETINTERFACE_RPC context handle to a cluster network interface, enabling the client to issue subsequent methods pertaining to the specified cluster network interface.

Opnum: 92

ApiCloseNetInterface

Instructs the server to free the context specified by the HNETINTERFACE_RPC context handle previously obtained by ApiOpenNetInterface.

Opnum: 93

ApiGetNetInterfaceState

Queries the current state of the specified cluster network interface.

Opnum: 94

ApiGetNetInterface

Queries the name of a cluster network interface for a specified node and cluster network.

Opnum: 95

ApiGetNetInterfaceId

Queries the unique ID of the specified cluster network interface.

Opnum: 96

ApiNodeNetInterfaceControl

Instructs the server to initiate an operation on the specified cluster network interface based on the specified control code. The operation is executed on the specified node.

Opnum: 97

ApiNetInterfaceControl

Instructs the server to initiate an operation on the specified cluster network interface based on the specified control code. The operation is executed on the node where the HNETINTERFACE_RPC context handle was obtained.

Opnum: 98

ApiAddNotifyNetInterface

Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network interface.

Opnum: 99

ApiReAddNotifyNetInterface

Re-registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network interface.

Opnum: 100

ApiCreateNodeEnum

Queries an enumeration of named cluster objects that are associated with a particular node.

Opnum: 101

ApiGetClusterVersion2

Queries version information about the cluster and the protocol server software.

Opnum: 102

ApiCreateResTypeEnum

Queries an enumeration of named cluster objects associated with the specified resource type.

Opnum: 103

ApiBackupClusterDatabase

Instructs the server to make a backup copy of the cluster configuration data.

Opnum: 104

ApiNodeClusterControl

Instructs the server to initiate an operation on the specified cluster based on the specified control code. The operation is executed on the specified node.

Opnum: 105

ApiClusterControl

Instructs the server to initiate an operation on the specified cluster based on the specified control code. The operation is executed on the node where the HCLUSTER_RPC context handle was obtained.

Opnum: 106

ApiUnblockGetNotifyCall

Instructs the server to complete any outstanding ApiGetNotify calls as a precursor to closing the notification port.

Opnum: 107

ApiSetServiceAccountPassword

Changes the password associated with the operational identity of the cluster service.

Opnum: 108

In the preceding table, the phrase "Reserved for local use" means that the client MUST NOT send the opnum and that the server behavior is undefined because it does not affect interoperability.