3.1.4.1 Protocol Version 2
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:
A cluster name or node name MUST be a null-terminated Unicode string that does not exceed 32 bytes.
Cluster registry key and value names have size limitations as specified in [MS-RRP].
Methods in RPC Opnum Order
Method |
Description |
---|---|
Obtains an HCLUSTER_RPC context handle to a cluster, enabling the client to issue subsequent methods pertaining to the specified cluster. Opnum: 0 |
|
Instructs the server to free the context specified by the HCLUSTER_RPC context handle previously obtained by ApiOpenCluster. Opnum: 1 |
|
Changes the name of the cluster. Opnum: 2 |
|
Queries the cluster name and the host name of the node acting as an RPC interface server. Opnum: 3 |
|
Queries version information about the cluster and the protocol server software. Opnum: 4 |
|
Queries the quorum configuration for the cluster. Opnum: 5 |
|
Changes the quorum configuration for the cluster. Opnum: 6 |
|
Queries an enumeration of named objects from the cluster state. Opnum: 7 |
|
Obtains an HRES_RPC context handle to a resource, enabling the client to issue subsequent methods pertaining to the specified resource. Opnum: 8 |
|
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 |
|
Removes the specified resource from the non-volatile cluster state. Opnum: 10 |
|
Instructs the server to free the context specified by the HRES_RPC context handle previously obtained by ApiOpenResource. Opnum: 11 |
|
Queries the current state of the specified resource. Opnum: 12 |
|
Changes the name of the specified resource. Opnum: 13 |
|
Queries the unique identifier (UID) of the specified resource. Opnum: 14 |
|
Queries a string identifying the resource type of the designated resource. Opnum: 15 |
|
Initiates a failure of the specified resource. Tests the recovery policy associated with the resource. Opnum: 16 |
|
Instructs the server to bring the specified resource to the online state. Opnum: 17 |
|
Instructs the server to bring the specified resource to the offline state. Opnum: 18 |
|
Instructs the server to add a simple dependency between the two specified resources. Opnum: 19 |
|
Instructs the server to remove the dependency between the two specified resources. Opnum: 20 |
|
Determines whether the specified resource can be dependent on another specified resource. Opnum: 21 |
|
Queries an enumeration of the resources on which the specified resource depends. Opnum: 22 |
|
Adds the specified node to the set of nodes that can host the specified resource. Opnum: 23 |
|
Removes the specified node from the set of nodes that can host the specified resource. Opnum: 24 |
|
Moves the specified resource from its current group to the specified group. Opnum: 25 |
|
Adds the specified resource type to the non-volatile cluster state. Opnum: 26 |
|
Removes the specified resource type from the non-volatile cluster state. Opnum: 27 |
|
Obtains a context handle for the root key of the cluster registry. Opnum: 28 |
|
Creates a key in the cluster registry and returns a context handle for the created key. Opnum: 29 |
|
Opens and returns a context handle to a key in the cluster registry. Opnum: 30 |
|
Obtains, by index, the name of a subkey of a key in the cluster registry. Opnum: 31 |
|
Sets the data stored in a value in the cluster registry. Opnum: 32 |
|
Deletes a value from the cluster registry. Opnum: 33 |
|
Queries the data stored in a value in the cluster registry. Opnum: 34 |
|
Deletes a key from the cluster registry. Opnum: 35 |
|
Retrieve, by index, a value under a key in the cluster registry. Opnum: 36 |
|
Close a cluster registry key. Opnum: 37 |
|
Queries information about a key in the cluster registry. Opnum: 38 |
|
Sets the security descriptor of a key in the cluster registry. Opnum: 39 |
|
Retrieves the security descriptor of a key in the cluster registry. Opnum: 40 |
|
Obtains an HGROUP_RPC context handle to a group, enabling the client to issue subsequent methods pertaining to the specified group. Opnum: 41 |
|
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 |
|
Removes the specified group from the non-volatile cluster state. Opnum: 43 |
|
Instructs the server to free the context specified by the HGROUP_RPC context handle previously obtained by ApiOpenGroup. Opnum: 44 |
|
Queries the current state of the specified group. Opnum: 45 |
|
Changes the name of the specified group. Opnum: 46 |
|
Queries the UID of the specified group. Opnum: 47 |
|
Queries the unique identifier (UID) of the specified node. Opnum: 48 |
|
Instructs the server to bring the specified group to the ClusterGroupOnline state. Opnum: 49 |
|
Instructs the server to bring the specified resource to the ClusterGroupOffline state. Opnum: 50 |
|
Instructs the server to move the group to another node in the cluster. Opnum: 51 |
|
Instructs the server to move the group to the specified node. Opnum: 52 |
|
Queries an enumeration of the resources that are contained in the specified group. Opnum: 53 |
|
Sets a list of nodes, in order of preference, indicating where the specified group is hosted. Opnum: 54 |
|
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 |
|
Instructs the server to free the context specified by the HNOTIFY_RPC context handle previously obtained by ApiCreateNotify. Opnum: 56 |
|
Registers an event filter mask with the specified notification port whose scope covers all objects in the cluster. Opnum: 57 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified node. Opnum: 58 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified group. Opnum: 59 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified resource. Opnum: 60 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster registry key. Opnum: 61 |
|
Re-registers an event filter mask with the specified notification port whose scope is limited to the specified node. Opnum: 62 |
|
Re-registers an event filter mask with the specified notification port whose scope is limited to the specified group. Opnum: 63 |
|
Re-registers an event filter mask with the specified notification port whose scope is limited to the specified resource. Opnum: 64 |
|
Retrieves the next event from the specified notification port. Opnum: 65 |
|
Obtains an HNODE_RPC context handle to a node, enabling the client to issue subsequent methods pertaining to the specified node. Opnum: 66 |
|
Instructs the server to free the context specified by the HNODE_RPC context handle previously obtained by ApiOpenNode. Opnum: 67 |
|
Queries the current state of the specified node. Opnum: 68 |
|
Instructs the server to pause group failover activity on the specified node. Opnum: 69 |
|
Instructs the server to resume group failover activity on the specified node. Opnum: 70 |
|
Instructs the server to remove the specified node as a configured node in the cluster. Opnum: 71 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Reserved for local use. Opnum: 80 |
|
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 |
|
Instructs the server to free the context specified by the HNETWORK_RPC context handle previously obtained by ApiOpenNetwork. Opnum: 82 |
|
Queries the current state of the specified cluster network. Opnum: 83 |
|
Changes the name of the specified cluster network. Opnum: 84 |
|
Queries an enumeration of cluster network interface objects that are installed on the specified cluster network. Opnum: 85 |
|
Queries the unique ID of the specified cluster network. Opnum: 86 |
|
Sets the priority ordered list of internal cluster networks to use for internal cluster communication. Opnum: 87 |
|
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 |
|
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 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network. Opnum: 90 |
|
Re-registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network. Opnum: 91 |
|
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 |
|
Instructs the server to free the context specified by the HNETINTERFACE_RPC context handle previously obtained by ApiOpenNetInterface. Opnum: 93 |
|
Queries the current state of the specified cluster network interface. Opnum: 94 |
|
Queries the name of a cluster network interface for a specified node and cluster network. Opnum: 95 |
|
Queries the unique ID of the specified cluster network interface. Opnum: 96 |
|
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 |
|
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 |
|
Registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network interface. Opnum: 99 |
|
Re-registers an event filter mask with the specified notification port whose scope is limited to the specified cluster network interface. Opnum: 100 |
|
Queries an enumeration of named cluster objects that are associated with a particular node. Opnum: 101 |
|
Queries version information about the cluster and the protocol server software. Opnum: 102 |
|
Queries an enumeration of named cluster objects associated with the specified resource type. Opnum: 103 |
|
Instructs the server to make a backup copy of the cluster configuration data. Opnum: 104 |
|
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 |
|
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 |
|
Instructs the server to complete any outstanding ApiGetNotify calls as a precursor to closing the notification port. Opnum: 107 |
|
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.