Getting Object Properties

An cluster object's properties determine its identity and behavior in the cluster. Applications typically retrieve an object's properties to discover how the object is currently configured.

The Failover Cluster API provides many ways to get the properties of an object. The standard order of preference for cluster-aware applications recommends using control codes if possible. Therefore, the procedures described below use control codes exclusively. If you are writing a resource DLL, you should use the cluster database access functions and the cluster utility functions to work with properties.

The following generalized procedure describes how to use control codes to retrieve the properties for any object. Substitute the name of the object (node, network, netinterface, group, resource, or restype ) for <Object>.

To retrieve <Object> properties:

1. Allocate an output buffer to receive the property list.

2. Call the control code function for the object, Cluster<Object>Control, specifying one of the following control codes as the dwControlCode parameter.

   Properties to Retrieve	Control Code to Use
   Commonread/write properties	CLUSCTL_<OBJECT>_GET_COMMON_PROPERTIES
   Common read-only properties	CLUSCTL_<OBJECT>_GET_RO_COMMON_PROPERTIES
   Private read/write properties	CLUSCTL_<OBJECT>_GET_PRIVATE_PROPERTIES
   Private read-only properties	CLUSCTL_<OBJECT>_GET_RO_PRIVATE_PROPERTIES

    

   For more information on using control codes see Getting Information with Control Codes.

3. If Cluster<Object>Control returns ERROR_MORE_DATA, reallocate the output buffer according to the size returned by the lpcbBytesReturned parameter.

4. If Cluster<Object>Control returns ERROR_SUCCESS, the output buffer contains a property list for the object. Parse the property list to retrieve individual property names and values - see Parsing Property Lists.

To obtain a list of the read/write common or private properties of an object, use the CLUSCTL_<OBJECT>_ENUM_COMMON_PROPERTIES and CLUSCTL_<OBJECT>_ENUM_PRIVATE_PROPERTIES control codes.

Example Code

The following example retrieves the read/write common properties of a resource and returns the value of a specified property. This example calls other example functions presented elsewhere in this documentation. To locate these example functions, see the Index of Examples.

#include <windows.h>

//////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETRWCDWORDPROPERTY_CPP
#define _CLUSDOCEX_RESGETRWCDWORDPROPERTY_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_ResGetRWCDwordProperty
//
//  Retrieves the value of a specified read-write common resource
//  property of type DWORD.
//
//  Arguments:
//
//      IN  LPWSTR  lpszResName    Name of the resource.
//
//      IN  LPWSTR  lpszPropName   Name of the read-write common 
//                                 DWORD property to get.
//
//      OUT LPDWORD lpdwPropValue  Returns the property value.
//
//  Return Value:
//      System error code
//  
//--------------------------------------------------------------------
DWORD ClusDocEx_ResGetRWCDwordProperty(
    IN LPWSTR lpszResName, 
    IN LPWSTR lpszPropName,
    OUT LPDWORD lpdwPropValue
)
{
    HCLUSTER hCluster = NULL;
    HRESOURCE hResource = NULL;
    LPVOID lpPropList = NULL;
    DWORD dwResult = ERROR_SUCCESS; 
    DWORD cbPropListSize = 0;
        

//  For the ClusDocEx_OpenLocalClusterWithName function, 
//  see "Using Object Handles".

    hCluster = ClusDocEx_OpenLocalClusterWithName();

    if( hCluster == NULL )
    {
        goto endf;
    }

    hResource = OpenClusterResource( hCluster, lpszResName );

    if( hResource == NULL )
    {
        goto endf;
    }


//  For the ClusDocEx_ResGetControlCodeOutput function, 
//  see "Getting Information with "Control Codes".

    lpPropList = ClusDocEx_ResGetControlCodeOutput(
                     hResource,
                     NULL,
                     CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES,
                     &amp;cbPropListSize );

    if( dwResult != ERROR_SUCCESS )
    {
        goto endf;
    }


//  ResUtilFindDwordProperty is one of the cluster utility functions.

    dwResult = ResUtilFindDwordProperty(
                   lpPropList,
                   cbPropListSize,
                   lpszPropName,
                   lpdwPropValue );

endf:

    if( dwResult != ERROR_SUCCESS )
    {
        ClusDocEx_DebugPrint( L"ClusDocEx_ResGetRWCDwordProperty", dwResult );
    }


//  Free the buffer allocated by ClusDocEx_ResGetControlCodeOutput.

    LocalFree( lpPropList );

    if( hResource ) CloseClusterResource( hResource );

    if( hCluster ) CloseCluster( hCluster );

    return dwResult;
}
//  end ClusDocEx_ResGetRWCDwordProperty
//--------------------------------------------------------------------
#endif