3.1.4.2.139 ApiCreateGroupEnum (Opnum 143)

(Protocol Version 3) The ApiCreateGroupEnum method SHOULD<126> return an enumeration of groups from the current set of groups in the cluster.

The server MUST accept an ApiCreateGroupEnum request only if it is in the read/write state, as specified in section 3.1.1.

The server SHOULD accept an ApiCreateGroupEnum request if the access level associated with the hCluster parameter is "Read" (section 3.1.4).

 error_status_t ApiCreateGroupEnum(
   [in] HCLUSTER_RPC hCluster,
   [in, unique, size_is(cbProperties)] 
     UCHAR* pProperties,
   [in] DWORD cbProperties,
   [in, unique, size_is(cbRoProperties)] 
     UCHAR* pRoProperties,
   [in] DWORD cbRoProperties,
   [out] PGROUP_ENUM_LIST* ppResultList,
   [out] error_status_t *rpc_status
 );

hCluster: A valid context handle to the cluster from which the client wishes to obtain a group enumeration.

pProperties: A MULTI_SZ list containing a list of names of common properties requested by the client. For each GROUP_ENUM_ENTRY (section 2.2.3.25) in the resulting GROUP_ENUM_LIST (section 2.2.3.26), the server MUST return a PROPERTY_LIST (section 2.2.3.10) containing a Property Value (section 2.2.3.10.1) for each property name specified by the client in the pProperties parameter. If the client sets the pProperties parameter to a single NULL-terminated Unicode string equaling "*", then the server MUST return a PROPERTY_LIST containing a Property Value for each of the common properties of the group, as would be returned by a call to CLUSCTL_GROUP_GET_COMMON_PROPERTIES (section 3.1.4.3.3.8).

cbProperties: The size in bytes of the property list buffer pointed to by the pProperties parameter.

pRoProperties: A MULTI_SZ list containing a list of names of common read-only properties requested by the client. For each GROUP_ENUM_ENTRY (section 2.2.3.25) in the resulting GROUP_ENUM_LIST (section 2.2.3.26), the server MUST return a PROPERTY_LIST (section 2.2.3.10) containing a Property Value (section 2.2.3.10.1) for each property name specified by the client in the pRoProperties parameter. If the client sets the pRoProperties parameter to a single NULL-terminated Unicode string equaling "*", then the server MUST return a PROPERTY_LIST containing a Property Value for each of the common read-only properties of the group, as would be returned by a call to CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES (section 3.1.4.3.3.7).

cbRoProperties: The size in bytes of the property list buffer pointed to by the pRoProperties parameter.

ppResultList: A pointer to the enumerated group list as specified in GROUP_ENUM_LIST (section 2.2.3.26). Each entry in the list is specified by a GROUP_ENUM_ENTRY (section 2.2.3.25).

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: This method MUST return the following values for the following conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	The method completed successfully.
0x00000057 ERROR_INVALID_PARAMETER	The client specified a property name in the pProperties or pRoProperties parameters that is not the name of a group common or private property, respectively.

For any other condition, the server returns a value that is not one of the values listed in the preceding table. Clients MUST treat all such values identically, with the exception of errors specified in section 3.2.4.6, which are recoverable errors for which the client SHOULD initiate the reconnect procedure.