3.1.4.2.124 ApiCreateEnumEx (Opnum 125)

Article
04/27/2022

(Protocol Version 3) The ApiCreateEnumEx method SHOULD <104> return two ENUM_LIST structures of equal length containing the ID and Name attributes of the requested objects of the specified enumeration type from the cluster state. Each Element in the ReturnIdEnum parameter corresponds to the ID of the element at the same offset in the ReturnNameEnum parameter.

If multiple enumeration types are indicated, the resulting ENUM_LIST contains zero or more entries of each type, and the type of each entry in the list is indicated by the ENUM_ENTRY data structure, as specified in section 2.2.3.4.

The server SHOULD accept an ApiCreateEnumEx request if its protocol server state is read-only, as specified in section 3.1.1, and the dwType parameter is CLUSTER_ENUM_NODE. The server MUST accept an ApiCreateEnumEx request if its protocol server state is read/write.

The server MUST fail this method with the ERROR_INVALID_PARAMETER (0x00000057) return value if the dwType parameter is not one of the specified values or if the dwOptions parameter is not 0x00000000.

The server SHOULD accept an ApiCreateEnumEx request if the access level associated with the hCluster context handle is at least "Read" (section 3.1.4).

 error_status_t ApiCreateEnumEx(
   [in] HCLUSTER_RPC hCluster,
   [in] DWORD dwType,
   [in] DWORD dwOptions,
   [out] PENUM_LIST* ReturnIdEnum,
   [out] PENUM_LIST* ReturnNameEnum,
   [out] error_status_t* rpc_status
 );

hCluster: An HCLUSTER_RPC (section 2.2.1.1) context handle that was obtained in a previous ApiOpenCluster (section 3.1.4.2.1) or ApiOpenClusterEx (section 3.1.4.2.116) method call.

dwType: The type of enumeration to be returned by the server. This value MUST be set to the bitwise OR operator of one or more of the following values, except as noted for CLUSTER_ENUM_INTERNAL_NETWORK.

Value	Meaning
CLUSTER_ENUM_NODE 0x00000001	The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing cluster nodes that are members of the cluster. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NODE contains the ID of the cluster node as if the CLUSCTL_NODE_GET_ID control code is sent to the node with the name in the corresponding element of the ReturnNameEnum.
CLUSTER_ENUM_RESTYPE 0x00000002	The serer MUST return an enumeration of names representing the resource types installed in the cluster as the ReturnNameEnum out parameter. The server MUST return an ENUM_LIST of equal length in the ReturnIdEnum out parameter with each element that sets dwType to CLUSTER_ENUM_RESTYPE a zero-length null-terminated Unicode string.
CLUSTER_ENUM_RESOURCE 0x00000004	The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing the cluster resources. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_RESOURCE contains the ID of the cluster resource as if the CLUSCTL_RESOURCE_GET_ID control code is sent to the resource with the name in the corresponding element of the ReturnNameEnum.
CLUSTER_ENUM_GROUP 0x00000008	The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster groups. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_GROUP contains the ID of the cluster group as if the CLUSCTL_GROUP_GET_ID control code is sent to the group with the name in the corresponding element of the ReturnNameEnum.
CLUSTER_ENUM_NETWORK 0x00000010	The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster networks. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NETWORK contains the ID of the cluster network as if the CLUSCTL_NETWORK_GET_ID control code is sent to the cluster network with the name in the corresponding element of the ReturnNameEnum.
CLUSTER_ENUM_NETINTERFACE 0x00000020	The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster network interfaces. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NETINTERFACE contains the ID of the cluster network interface as if the CLUSCTL_NETINTERFACE_GET_ID control code is sent to the cluster network interface with the name in the corresponding element of the ReturnNameEnum.
CLUSTER_ENUM_INTERNAL_NETWORK 0x80000000	Cannot be specified with any other value for this parameter. The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster networks that are used only for internal communications. Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_INTERNAL_NETWORK contains the ID of the cluster network as if the CLUSCTL_NETWORK_GET_ID control code is sent to the cluster network with the name in the corresponding element of the ReturnNameEnum.

Value

Meaning

CLUSTER_ENUM_NODE

0x00000001

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing cluster nodes that are members of the cluster.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NODE contains the ID of the cluster node as if the CLUSCTL_NODE_GET_ID control code is sent to the node with the name in the corresponding element of the ReturnNameEnum.

CLUSTER_ENUM_RESTYPE

0x00000002

The serer MUST return an enumeration of names representing the resource types installed in the cluster as the ReturnNameEnum out parameter.

The server MUST return an ENUM_LIST of equal length in the ReturnIdEnum out parameter with each element that sets dwType to CLUSTER_ENUM_RESTYPE a zero-length null-terminated Unicode string.

CLUSTER_ENUM_RESOURCE

0x00000004

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing the cluster resources.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_RESOURCE contains the ID of the cluster resource as if the CLUSCTL_RESOURCE_GET_ID control code is sent to the resource with the name in the corresponding element of the ReturnNameEnum.

CLUSTER_ENUM_GROUP

0x00000008

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster groups.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_GROUP contains the ID of the cluster group as if the CLUSCTL_GROUP_GET_ID control code is sent to the group with the name in the corresponding element of the ReturnNameEnum.

CLUSTER_ENUM_NETWORK

0x00000010

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster networks.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NETWORK contains the ID of the cluster network as if the CLUSCTL_NETWORK_GET_ID control code is sent to the cluster network with the name in the corresponding element of the ReturnNameEnum.

CLUSTER_ENUM_NETINTERFACE

0x00000020

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster network interfaces.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_NETINTERFACE contains the ID of the cluster network interface as if the CLUSCTL_NETINTERFACE_GET_ID control code is sent to the cluster network interface with the name in the corresponding element of the ReturnNameEnum.

CLUSTER_ENUM_INTERNAL_NETWORK

0x80000000

Cannot be specified with any other value for this parameter.

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, of cluster networks that are used only for internal communications.

Each element of ReturnIdEnum that sets dwType to CLUSTER_ENUM_INTERNAL_NETWORK contains the ID of the cluster network as if the CLUSCTL_NETWORK_GET_ID control code is sent to the cluster network with the name in the corresponding element of the ReturnNameEnum.

dwOptions: A 32-bit integer that specifies the options on the type of elements to return. The client MUST set this value to 0x00000000. The server MUST fail the call if this parameter is not set to 0x00000000.

ReturnIdEnum: A pointer to a PENUM_LIST (section 2.2.3.5). The pointer contains the IDs of the objects that match the enumeration type that is indicated by the dwType parameter. The server MUST allocate as much memory as is required to return the enumeration data. If the method fails, this parameter MUST be ignored.

ReturnNameEnum: A pointer to a PENUM_LIST (section 2.2.3.5). The pointer contains the name of the objects that match the enumeration type that is indicated by the dwType parameter, except where noted above. The server MUST allocate as much memory as is required to return the enumeration data. If the method fails, this parameter MUST be ignored.

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 conditions that are specified as follows.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000008 ERROR_NOT_ENOUGH_MEMORY	The server failed to allocate enough memory for the ReturnEnum parameter.
0x000000057 ERROR_INVALID_PARAMETER	The enumeration type that is specified by dwType is not valid or dwOptions is not set to 0x00000000.
0x000006D1 RPC_S_PROCNUM_OUT_OF_RANGE	The server does not support this method.

For any other condition, the server 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. However, 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.

3.1.4.2.124 ApiCreateEnumEx (Opnum 125)

Additional resources