ResUtilEnumResources function

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 WINAPI ResUtilEnumResources(
  _In_  HRESOURCE hSelf,
  _In_  LPCWSTR lpszResTypeName,
  _In_  LPRESOURCE_CALLBACK pResCallBack,
  _In_  PVOID pParameter
);

typedef DWORD (WINAPI *PRESUTIL_ENUM_RESOURCES)(
    _In_  HRESOURCE hSelf,
    _In_  LPCWSTR lpszResTypeName,
    _In_  LPRESOURCE_CALLBACK pResCallBack,
    _In_  PVOID pParameter
);

Parameters

hSelf [in]

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

lpszResTypeName [in]

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.

pResCallBack [in]

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 
);
pParameter [in]

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

Minimum supported client

None supported

Minimum supported server

Windows Server 2003 Enterprise, Windows Server 2003 Datacenter

Header

ResApi.h

Library

ResUtils.lib

DLL

ResUtils.dll

See also

Resource Utility Functions
OpenCluster
ClusterOpenEnum
ResourceCallback

 

 

Show:
© 2014 Microsoft