ResUtilEnumResources function (resapi.h)

Article
02/22/2024

Enumerates all of the resources in the local cluster and initiates a user-defined operation for each resource. The PRESUTIL_ENUM_RESOURCES type defines a pointer to this function.

Syntax

DWORD ResUtilEnumResources(
  [in] HRESOURCE           hSelf,
  [in] LPCWSTR             lpszResTypeName,
  [in] LPRESOURCE_CALLBACK pResCallBack,
  [in] PVOID               pParameter
);

Parameters

[in] hSelf

Optional handle to a cluster resource. The callback function is not invoked for a resource identified by hSelf.

[in] lpszResTypeName

Optional pointer to a name of a resource type that narrows the scope of resources to enumerate. If lpszResTypeName is specified, only resources of the specified type are enumerated.

[in] pResCallBack

Pointer to a user-defined function which will be called for each enumerated resource. This function must conform to the definition of the ResourceCallback callback function (note that parameter names are not part of the definition; they have been added here for clarity):

DWORD (*LPRESOURCE_CALLBACK)( 
  HRESOURCE hSelf, 
  HRESOURCE hEnum, 
  PVOID pParameter 
);

[in] pParameter

A generic buffer that allows you to pass any kind of data to the callback function. ResUtilEnumResources does not use this parameter at all, it merely passes the pointer to the callback function. Whether you can pass NULL for the parameter depends on how the callback function is implemented.

Return value

If the operation succeeds or if pResCallBack returns ERROR_NO_MORE_ITEMS, the function returns ERROR_SUCCESS.

If the operation fails, the function immediately halts the enumeration and returns the value returned by the callback function.

Remarks

ResUtilEnumResources is a convenient and easy-to-use alternative to the ClusterResourceEnum function.

ResUtilEnumResources must be run on a cluster node because it only connects to the local cluster. The ResUtilEnumResourcesEx function allows you to specify a remote cluster.

The following example uses ResUtilEnumResources to list the names and states of all resources in the cluster.

//////////////////////////////////////////////////////////////////////
//  ClusDocEx_EnumDemo.cpp
//
//  Uses the ResUtilEnumResources function to list the names and 
//  states of all cluster resources.
//
//  To compile and run this example you will need two other examples 
//  from the documentation:  ClusDocEx.h (see "ClusDocEx.h") and 
//  ClusDocEx_GetControlCodeOutput.cpp (see "Getting Information with 
//  Control Codes").
// 
//////////////////////////////////////////////////////////////////////
#include "ClusDocEx.h"
#include "ClusDocEx_GetControlCodeOutput.cpp"

DWORD
MyCallbackFunction(
    HRESOURCE hSelf,
    HRESOURCE hCurrentEnum,
    PVOID pData );

LPRESOURCE_CALLBACK g_pMyCallbackFunction = &MyCallbackFunction;

int main( void )
{
    wprintf( L"\n\nResource (State)\n----------------\n" );
    DWORD dwResult = ResUtilEnumResources( 
                         NULL, 
                         NULL, 
                         g_pMyCallbackFunction, 
                         NULL );
    if( dwResult != ERROR_SUCCESS )
    {
        ClusDocEx_DebugPrint( L"ResUtilEnumResources returned an error.", dwResult );
        return 1;
    }
    else
        return 0;
}

DWORD
MyCallbackFunction(
    HRESOURCE hSelf,
    HRESOURCE hCurrentEnum,
    PVOID pData )
{
    DWORD dwResult           = ERROR_SUCCESS,
          cbNameSize         = 0, 
          dwState            = 0;

    WCHAR* pszState    = NULL;
    WCHAR* pszEnumName = ClusDocEx_ResGetControlCodeOutput(
                            hCurrentEnum,
                            NULL,
                            CLUSCTL_RESOURCE_GET_NAME,
                            &cbNameSize );
    if( pszEnumName == NULL )
    {
        dwResult = GetLastError();
        goto EndFunc;
    }

    dwState = GetClusterResourceState(
                  hCurrentEnum,
                  NULL,
                  NULL,
                  NULL,
                  NULL );
    switch( dwState )
    {
    case ClusterResourceOnline:
        pszState = L"Online";
        break;
    case ClusterResourceOffline:
        pszState = L"Offline";
        break;
    case ClusterResourcePending:
        pszState = L"Pending";
        break;
    case ClusterResourceOnlinePending:
        pszState = L"OnlinePending";
        break;
    case ClusterResourceOfflinePending:
        pszState = L"OfflinePending";
        break;
    case ClusterResourceFailed:
        pszState = L"Failed";
        break;
    case ClusterResourceInitializing:
        pszState = L"Initializing";
        break;
    default:
        pszState = L"Unknown";
        break;
    }
    wprintf( L"%ls (%ls)\n", pszEnumName, pszState );

EndFunc:
    LocalFree( pszEnumName );
    return dwResult;
}

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Target Platform	Windows
Header	resapi.h
Library	ResUtils.lib
DLL	ResUtils.dll