3.1.4.2.7 ApiSetQuorumResource (Opnum 6)

  • Article

(Protocol Version 3) The ApiSetQuorumResource method instructs the server to change the cluster's quorum configuration information. The process of changing the quorum configuration information and synchronizing the change with other cluster nodes is achieved through implementation-specific methods and protocols between servers.

The cluster SHOULD support the following types of quorum: Shared Disk, Majority of Nodes, Hybrid, and Witness. The cluster SHOULD NOT support the Local style of quorum.

If a resource is designated by the hResource parameter, it has the following attributes:

  • The resource MUST return CLUS_CHAR_QUORUM, as specified in section 2.2.2.4, when queried for its characteristics.

  • The resource MUST support the CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO_EX resource control, as specified in section 3.1.4.3.1.45.

  • The resource MUST NOT indicate that it is in maintenance, as specified in section 3.1.4.3.1.42.

  • The resource MUST NOT have any other resources dependent on it.

The configuration database is stored in a directory on the storage device represented by hResource. The path is specified via the lpszDeviceName parameter and MUST be one of the following values:

  • NULL, indicating that the server MUST use a default partition and directory path on the storage device represented by hResource.

  • A drive letter, indicating that the server MUST use a default directory path on the partition that corresponds to the specified drive letter.

  • A fully qualified path (drive letter and path), indicating that the server MUST place the quorum configuration data in this area.

If a resource is designated by the hResource parameter, then upon successful completion of this method, the server SHOULD designate that resource as a core resource. If a different resource is associated with the quorum configuration information at the time of this method invocation (due to a previous call to ApiSetQuorumResource), then upon successful completion of this method the server SHOULD remove the core resource designation from that different resource.

The server MUST accept an ApiSetQuorumResource request only if its protocol server state is read/write, as specified in section 3.1.1.

If dwMaxQuorumLogSize is set to "0x00000000", then the server SHOULD require that the client's access level is "All" (section 3.1.4). If dwMaxQuorumLogSize is not set to "0x00000000", then the server SHOULD require that the access level associated with the hResource context handle is "All".

 error_status_t ApiSetQuorumResource(
   [in] HRES_RPC hResource,
   [in, string] LPCWSTR lpszDeviceName,
   [in] DWORD dwMaxQuorumLogSize,
   [out] error_status_t *rpc_status
 );

hResource: An HRES_RPC context handle that was obtained in a previous ApiOpenResource, ApiOpenResourceEx, or ApiCreateResource method call. If the dwMaxQuorumLogSize parameter is set to 0x00000000, hResource MUST be set to a handle of a current quorum resource.

lpszDeviceName: A Unicode string identifying a directory on the disk (when the hResource parameter represents a storage device) where the cluster stores its configuration database. If the dwMaxQuorumLogSize parameter is set to 0x00000000, this parameter SHOULD be set to an empty string by clients and ignored by servers.

dwMaxQuorumLogSize:  A 32-bit integer contains one of the following values:

  • 0x00000000, indicating that the quorum type is to be set to Majority of Nodes quorum.

  • 0x00000400, indicating that the quorum type is to be set to either Hybrid or Witness quorum. To select Hybrid quorum, the client MUST set the hResource parameter to a context handle representing a storage class resource and set the lpszDeviceName parameter as described in the preceding paragraphs. Otherwise, for the quorum type to be set to Witness, the client MUST set the hResource parameter to a context handle representing a resource of type "File Share Witness" or "Cloud Witness", and the lpszDeviceName parameter to the null Unicode string (0x0000).

  • Any other value indicates that the quorum type is set to Disk quorum. The hResource parameter represents a storage class resource and the lpszDeviceName parameter as described in the preceding paragraphs.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults, and returned control to the client without encountering any communication faults. This value is separate from the value returned by the method and does not represent the success of the method. The client MUST treat all nonzero values the same, except as specified in section 3.2.4.6.

Return Values: The method MUST return the following error codes for the conditions that are specified as follows.

For any other condition, the server MUST return a value that is not listed in the following table. The client MUST behave in one consistent, identical manner for all values that are not listed.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Success.

0x00000006

ERROR_INVALID_HANDLE

The hResource parameter does not represent a valid HRES_RPC context handle.

0x0000138C

ERROR_RESOURCE_NOT_ONLINE

The resource represented by HRES_RPC is not in the ClusterResourceOnline state.

0x0000139D

ERROR_NOT_QUORUM_CAPABLE

The server is not capable of participating in a quorum.

0x0000139F

ERROR_INVALID_STATE

The resource represented by HRES_RPC is in a maintenance state, as described in either section 2.2.3.14 or section 2.2.3.15.

0x000013CD

ERROR_DEPENDENCY_NOT_ALLOWED

The resource represented by HRES_RPC has other resources dependent on it.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values that are not listed in the preceding table the same, except as specified in section 3.2.4.6.