Share via

3.1.4.2.156 ApiGroupSetControl (Opnum 174)

  • Article

The ApiGroupSetControl method<143> provides for arbitrary communication and control between an application and an instance of a group. This method instructs the server to initiate, on the specified group set, an operation that is defined by the specified control code. The operation is performed on the node hosting the group set.

The server MUST require that the access level associated with the hGroupSet context handle is "All" (section 3.1.4), if and only if the bitwise AND of dwControlCode and 0x00400000 is not equal to zero, except as otherwise specified for particular control codes in section 3.1.4.3.8.

 error_status_t
 ApiGroupSetControl (
   [ in ] HGROUPSET_RPC hGroupSet,
   [ in ] DWORD dwControlCode,
   [ in, unique, size_is(nInBufferSize) ] UCHAR *lpInBuffer,
   [ in ] DWORD nInBufferSize,
   [ out, size_is(nOutBufferSize), length_is(*lpBytesReturned) ] UCHAR *lpOutBuffer,
   [ in, range(0, MAX_CLUSTER_CONTROL_CODE_BUFFER_SIZE) ] DWORD nOutBufferSize,
   [ out ] DWORD *lpBytesReturned,
   [ out ] DWORD *lpcbRequired,
   [ out ] error_status_t *rpc_status
 );

hGroupSet: An HGROUPSET_RPC (section 2.2.1.11) context handle that is obtained in a previous ApiOpenGroupSet (section 3.1.4.2.147) or ApiCreateGroupSet (section 3.1.4.2.146) method call.

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

Value/code

Description

CLUSCTL_GROUPSET_GET_ID

0x08000039

Retrieves the unique ID for the group set.

CLUSCTL_GROUPSET_GET_RO_COMMON_PROPERTIES

0x08000055

Retrieves the read-only common property values for the designated group set.

CLUSCTL_GROUPSET_GET_COMMON_PROPERTIES

0x08000059

Retrieves all common property values for the designated group set.

CLUSCTL_GROUPSET_GET_GROUPS

0x08002D71

Retrieves the list of groups for the designated group set.

CLUSCTL_GROUPSET_GET_PROVIDER_GROUPS

0x08002D75

Retrieves the list of provider groups for the designated group set.

CLUSCTL_GROUPSET_GET_PROVIDER_GROUPSETS

0x08002D79

Retrieves a list of the provider group sets for the designated group set.

CLUSCTL_GROUPSET_SET_COMMON_PROPERTIES

0x0840005E

Sets the common property values for the designated group set.

lpInBuffer: The input data for the operation that is specified by dwControlCode. See section 3.1.4.3.8 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. 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.

0x00000522

ERROR_PRIVILEGE_NOT_HELD

A required privilege is not held by the client.

0x000013D1

ERROR_CLUSTER_NODE_SHUTTING_DOWN

The cluster node is shutting down.

0x00001767

ERROR_GROUPSET_NOT_AVAILABLE

The cluster group set is not available for any further requests.

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.