3.1.4.2.123 ApiCreateNodeEnumEx (Opnum 124)

  • Article

(Protocol Version 3) The ApiCreateNodeEnumEx method SHOULD<103> 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 lists are indicated by the ENUM_ENTRY data structure, as specified in section 2.2.3.4.

The server SHOULD accept an ApiCreateNodeEnumEx request if its protocol server state is read-only, and the server MUST accept the request for processing if it is in the read/write state, as specified in section 3.1.1.

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 ApiCreateNodeEnumEx request if the access level associated with the hNode context handle is at least "Read" (section 3.1.4).

 error_status_t ApiCreateNodeEnumEx(
   [in] HNODE_RPC hNode,
   [in] DWORD dwType,
   [in] DWORD dwOptions,
   [out] PENUM_LIST* ReturnIdEnum,
   [out] PENUM_LIST* ReturnNameEnum,
   [out] error_status_t* rpc_status
 );

hNode: An HNODE_RPC context handle that was obtained in a previous ApiOpenNode (Opnum 66) or ApiOpenNodeEx (Opnum 118) 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:

Value

Meaning

CLUSTER_NODE_ENUM_NETINTERFACES

0x00000001

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing one or more cluster network interfaces installed on the specified node.

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

CLUSTER_NODE_ENUM_GROUPS

0x00000002

The server MUST return an enumeration of names, in ReturnNameEnum, and an enumeration of IDs, in ReturnIdEnum, representing one or more cluster groups currently owned by the specified node.

Each element of ReturnIdEnum that sets dwType to CLUSTER_NODE_ENUM_GROUPS contains the ID of the cluster group as if the CLUSCTL_GROUP_GET_ID control code is sent to the cluster group represented by 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 an ENUM_LIST (section 2.2.3.5) that contains 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 an ENUM_LIST (section 2.2.3.5) that contains the names 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.

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.

0x000000057

ERROR_INVALID_PARAMETER

The dwType parameter is not one of the specified values, or the dwOptions parameter is not 0x00000000.

0x000006D1

RPC_S_PROCNUM_OUT_OF_RANGE

The server does not support this method.

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