3.1.4.2.55 ApiSetGroupNodeList (Opnum 54)

(Protocol Version 3) The ApiSetGroupNodeList method sets the specified list of nodes on which the designated group prefers to be hosted.

The server MUST overwrite any existing data in the set with the designated list. The set is emptied as specified in protocol version-specific information later in this section. The server SHOULD append, in any order, the remaining nodes to the list if the designated list does not include all configured nodes in the cluster.

The server SHOULD use the set when making placement decisions for the designated group. The server SHOULD place the group on the first node in the list when the group is moved by using the ApiMoveGroup method. The server SHOULD use the next node in the list, relative to the node that is currently hosting the group, if the group moves due to group and/or resource failure.

If cchListSize is not greater than 1 or if multiSzNodeList is NULL, then the server MUST treat the input as an empty node list. Otherwise, the server MUST return ERROR_INVALID_PARAMETER (0x00000057) if multiSzNodeList is not terminated by at least one Unicode NULL character, where the terminating character is determined by cchListSize. If the two preceding conditions are not met, the server MUST return ERROR_ASSERTION_FAILURE (0x0000029c) if any individual string in multiSzNodeList is not a valid node ID. The server MUST accept any other input.

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

The server MUST require that the access level associated with the hGroup context handle is "All" (section 3.1.4).

 error_status_t ApiSetGroupNodeList(
   [in] HGROUP_RPC hGroup,
   [in, unique, size_is(cchListSize)] 
     wchar_t* multiSzNodeList,
   [in] DWORD cchListSize,
   [out] error_status_t *rpc_status
 );

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

multiSzNodeList: A pointer to a buffer that contains a MULTI_SZ string of the IDs of the nodes in the preferred list. The node IDs are returned by ApiGetNodeId.

cchListSize: The total number of characters, including all terminating NULL characters, in multiSzNodeList.

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.
0x00000057 ERROR_INVALID_PARAMETER	Refer to the processing rules included earlier in this section for details about this return value.
0x0000055C ERROR_SPECIAL_GROUP	Cannot perform this operation on this built-in special group (section 3.1.1.1.4).
0x00001394 ERROR_GROUP_NOT_AVAILABLE	The cluster group is not available for new requests.

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 section 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.