3.1.4.2.106 ApiClusterControl (Opnum 106)

Article
04/27/2022

(Protocol Version 3) The ApiClusterControl method instructs the server to initiate, on the specified cluster, an operation that is defined by the specified control code. The operation is executed on the node where the specified cluster context handle was obtained.

The server MUST require that the access level associated with the hCluster context handle is "All" (section 3.1.4), if and only if the bitwise AND of dwControlCode and 0x00400000 is not equal to zero.

 error_status_t ApiClusterControl(
   [in] HCLUSTER_RPC hCluster,
   [in] DWORD dwControlCode,
   [in, unique, size_is(nInBufferSize)] UCHAR *lpInBuffer,
   [in] DWORD nInBufferSize,
   [out, size_is(nOutBufferSize), 
     length_is (*lpBytesReturned)] UCHAR *lpOutBuffer,
   [in] DWORD nOutBufferSize,
   [out] DWORD *lpBytesReturned,
   [out] DWORD *lpcbRequired,
   [out] error_status_t *rpc_status
 );

hCluster: An HCLUSTER_RPC context handle that is obtained in a previous ApiOpenCluster or ApiOpenClusterEx method call.

dwControlCode: Indicates the operation to perform on the cluster. Must be one of the following values.

Value	Meaning
CLUSCTL_CLUSTER_UNKNOWN 0x07000000	Verifies that control codes for the cluster are being processed.
CLUSCTL_CLUSTER_GET_FQDN 0x0700003D	Retrieves the FQDN of the cluster.
CLUSCTL_CLUSTER_CHECK_VOTER_EVICT 0x07000045	Queries the cluster to determine whether evicting the specified node will cause the cluster to lose quorum.
CLUSCTL_CLUSTER_CHECK_VOTER_DOWN 0x07000049	Queries the cluster to determine whether taking the specified resource offline or stopping the specified active node will cause the cluster to lose quorum.
CLUSCTL_CLUSTER_SHUTDOWN 0x0700004D	Instructs the server to stop the cluster service on every active node.
CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES 0x07000051	Retrieves a list of the common property names for the designated cluster.
CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES 0x07000055	Retrieves the read-only common property values for the designated cluster.
CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES 0x07000059	Retrieves all common property values for the designated cluster.
CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES 0x0740005E	Sets the common property values for the designated cluster.
CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES 0x07000061	Validates that the values supplied for the common property are acceptable for the designated cluster.
CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS 0x07000065	Retrieves a list of the common property formats for the designated cluster.
CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES 0x07000079	Retrieves a list of the private property names for the designated cluster.
CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES 0x0700007D	Retrieves the read-only private property values for the designated cluster.
CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES 0x07000081	Gets the private property values for the designated cluster.
CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES 0x07400086	Sets the private property values for the designated cluster.
CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES 0x07000089	Validates that the supplied private property list is valid.
CLUSCTL_CLUSTER_GET_SHARED_VOLUME_ID 0x07000291	Verifies that the file path is on the cluster shared volume and retrieves a unique volume identifier corresponding to that volume.
CLUSCTL_CLUSTER_UPGRADE_CLUSTER_VERSION 0x074000ce	Upgrades the operational version of the cluster.
CLUSCTL_CLUSTER_CLEAR_UPGRADE_IN_PROGRESS 0x074000d2	Indicates that the current upgrade to the cluster operational version is no longer in progress.
CLUSCTL_CLUSTER_IS_READY_FOR_UPGRADE 0x070000d5	Determines whether all nodes in a cluster support an upgrade to a higher operational version.
CLUSCTL_CLUSTER_SET_ACCOUNT_ACCESS 0x074000f2	Updates SIDs on the cluster security descriptor.
CLUSCTL_CLUSTER_SET_DNS_DOMAIN 0x0740030a	Sets the DNS suffix with which Cluster Name Object (CNO) and Virtual Computer Object (VCO) are registered into DNS.
CLUSCTL_CLUSTER_GET_OS_AND_OS_VERSION_INFO 0x07002101	Gets the operating system (OS) name and OS version info on a machine.
CLUSCTL_CLUSTER_NODE_REPLACEMENT 0x070021F1	Replaces existing node with new node.
CLUSCTL_CLUSTER_GET_CLUSTER_UTILIZATION 0x07002115	Retrieves the utilization information for the designated cluster.
CLUSCTL_CLUSTER_NOTIFY_INFRASTRUCTURE_SOFS_CHANGED 0x07402d92	Instructs the server to inform every active node in the cluster that SOFS changed.
CLUSCTL_CLUSTER_CREATE_INFRASTRUCTURE_FILESERVER 0x074023F2	Instructs the server to create file server for the cluster set.
CLUSCTL_CLUSTER_REMOVE_INFRASTRUCTURE_FILESERVER 0x074023F6	Instructs the server to remove the file server from the cluster set.
CLUSCTL_CLUSTER_ENUM_AFFINITY_RULE_NAMES 0x09402ddd	Enumerates the affinity rule names in the cluster.<95>

lpInBuffer: The input data for the operation that is specified by dwControlCode. See the following sections for the data structures that are required for each dwControlCode.

nInBufferSize: The size, in bytes, of the buffer that is specified by lpInBuffer.

lpOutBuffer: The output data for the operation that is specified by dwControlCode. The output buffer MUST be allocated and provided by the client.

nOutBufferSize: The available size of the buffer that is specified by lpOutBuffer, as allocated by the client.

lpBytesReturned: On successful completion of the method, the server MUST set lpBytesReturned to the number of bytes that are written to the lpOutBuffer buffer.

lpcbRequired: If nOutBufferSize indicates that the buffer that is specified by lpOutBuffer is too small for the output data, the server MUST return 0x000000EA (ERROR_MORE_DATA) and set lpcbRequired to the number of bytes that are required for the output buffer. If the method completes successfully and lpBytesReturned is 0x00000000 then the server MUST set lpcbRequired to 0x00000000. In any other condition the client MUST ignore lpcbRequired after this method completes.

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 specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000001 ERROR_INVALID_FUNCTION	The cluster that is designated by hCluster does not support the operation that is designated by dwControlCode.
0x0000000D ERROR_INVALID_DATA	The input data was invalid or was incorrectly formatted.
0x00000057 ERROR_INVALID_PARAMETER	The input data was invalid or was incorrectly formatted.
0x000000EA ERROR_MORE_DATA	The nOutBufferSize parameter indicates that the buffer that is pointed to by lpOutBuffer is not large enough to hold the data that resulted from the operation.
0x00001739 ERROR_CLUSTER_NOT_SHARED_VOLUME	See section 3.1.4.3.7.17 for details about when this error can occur.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in 3.2.4.6 as recoverable errors, and initiate the reconnect procedure as specified in section 3.2.4.6.

Upon receiving this message, the server MUST:

Determine the number of bytes that are required for lpOutBuffer. If the size indicated by nOutBufferSize is less than the number of bytes that are required for lpOutBuffer, return ERROR_MORE_DATA (0x000000EA), except as specified in the following sub-sections where a different value is returned, and set lpcbRequired to the number of bytes that are required for the output buffer.
Return either ERROR_INVALID_DATA or ERROR_INVALID_PARAMETER if the input data is invalid or incorrectly formatted. The client MUST treat these two error codes the same.

Partager via

3.1.4.2.106 ApiClusterControl (Opnum 106)

Ressources supplémentaires