ClusterGroupEnum function

Enumerates the resources in a group or the nodes that are the preferred owners of a group, returning the name of the resource or node with each call. The PCLUSAPI_CLUSTER_GROUP_ENUM type defines a pointer to this function.

Syntax


DWORD WINAPI ClusterGroupEnum(
  _In_    HGROUPENUM hGroupEnum,
  _In_    DWORD      dwIndex,
  _Out_   LPDWORD    lpdwType,
  _Out_   LPWSTR     lpszResourceName,
  _Inout_ LPDWORD    lpcchName
);

typedef DWORD (WINAPI *PCLUSAPI_CLUSTER_GROUP_ENUM)(
    _In_    HGROUPENUM hGroupEnum,
    _In_    DWORD      dwIndex,
    _Out_   LPDWORD    lpdwType,
    _Out_   LPWSTR     lpszResourceName,
    _Inout_ LPDWORD    lpcchName
);

Parameters

hGroupEnum [in]

A group enumeration handle returned by the ClusterGroupOpenEnum function.

dwIndex [in]

The index of the resource or node to return. This parameter should be zero for the first call to ClusterGroupEnum and then incremented for subsequent calls.

lpdwType [out]

A pointer to the type of object returned by ClusterGroupEnum. The following are valid values of the CLUSTER_GROUP_ENUM enumeration.

CLUSTER_GROUP_ENUM_CONTAINS (1)

The object is one of the resources in the group.

CLUSTER_GROUP_ENUM_NODES (2)

The object is one of the nodes in the preferred owners list of the group.

lpszResourceName [out]

A pointer to a null-terminated Unicode string containing the name of the returned resource or node.

lpcchName [in, out]

A pointer to the size of the lpszResourceName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return value

The function can returns one of the following values.

ERROR_SUCCESS

0

The operation completed successfully.

ERROR_MORE_DATA

234 (0xEA)

More data is available. This value is returned if the buffer pointed to by lpszResourceName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

ERROR_NO_MORE_ITEMS

259 (0x103)

No more data is available. This value is returned if there are no more resources or nodes to be returned.

If the operation was not successful due to a problem other than those described with the ERROR_NO_MORE_ITEMS or ERROR_MORE_DATA values, ClusterGroupEnum returns a system error code.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Do not call ClusterGroupEnum from any resource DLL entry point function. ClusterGroupEnum can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Examples

See Enumerating Objects.

Requirements

Minimum supported client

None supported

Minimum supported server

Windows Server 2008 Enterprise, Windows Server 2008 Datacenter

Header

ClusAPI.h

Library

ClusAPI.lib

DLL

ClusAPI.dll

See also

Group Management Functions
ClusterGroupCloseEnum
ClusterGroupOpenEnum

 

 

Show: