3.1.4.2.78 ApiGroupControl (Opnum 77)

Article
04/27/2022

(Protocol Version 3) The ApiGroupControl method instructs the server to initiate, on the specified group, an operation that is defined by the specified control code. The operation is performed on the node hosting the group.

The server MUST require that the access level associated with the hGroup 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 ApiGroupControl(
   [in] HGROUP_RPC hGroup,
   [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
 );

hGroup: An HGROUP_RPC context handle that is obtained in a previous ApiOpenGroup, ApiOpenGroupEx, or ApiCreateGroup method call.

dwControlCode: Indicates the operation to perform on the group. It MUST be one of the following values:

Value	Meaning
CLUSCTL_GROUP_UNKNOWN 0x3000000	Verifies that control codes for the group are being processed.
CLUSCTL_GROUP_GET_CHARACTERISTICS 0x3000005	Retrieves the intrinsic characteristics associated with the group.
CLUSCTL_GROUP_GET_FLAGS 0x3000009	Retrieves the flags that are set for the group.
CLUSCTL_GROUP_GET_NAME 0x3000029	Retrieves the name of the group.
CLUSCTL_GROUP_GET_ID 0x3000039	Retrieves the unique ID for the group.
CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES 0x3000051	Retrieves a list of the common property names for the designated group.
CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES 0x3000055	Retrieves the read-only common property values for the designated group.
CLUSCTL_GROUP_GET_COMMON_PROPERTIES 0x3000059	Retrieves all common property values for the designated group.
CLUSCTL_GROUP_SET_COMMON_PROPERTIES 0x340005E	Sets the common property values for the designated group.
CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES 0x3000061	Validates that the values supplied for the common properties are acceptable for the designated group.
CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS 0x3000065	Retrieves a list of the common property formats for the designated group.
CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES 0x3000079	Retrieves a list of the private property names for the designated group.
CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES 0x300007D	Retrieves the read-only private property values for the designated group.
CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES 0x3000081	Retrieves all private property values for the designated group.
CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES 0x3400086	Sets the private property values for the designated group.
CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES 0x3000089	Validates that the supplied property list is valid.
CLUSCTL_GROUP_GET_STATE_CHANGE_TIME 0x03002d5d	Gets the last time the group changed state.
CLUSCTL_GROUP_CHECK_FOR_STABLE_ONLINE_OR_TERMINAL_FAILED 0x0300228D	Retrieves the group state.
CLUSCTL_GROUP_SET_CCF_FROM_MASTER 0x03402D86	Stores the common property values for the designated group.

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 it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in Appendix E of [C706].

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 group that is designated by hGroup 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.

For any other condition, this method returns 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 section 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) 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.

Share via

3.1.4.2.78 ApiGroupControl (Opnum 77)

Additional resources