Using Object Handles

Most of the Cluster Object Management Functions require an object handle as an input parameter. Therefore, one of the first steps in any object management routine is to obtain a handle to the object, and one of the last steps is to close the handle.

The following table lists cluster object handles and the functions used to obtain the handles (note that the Failover Cluster API does not define handles for resource types).










Network interface










The following generalized procedure applies to opening a handle to any object. Substitute the name of the object (that is, node, network, network interface, group, or resource) for <Object>.

Aa372959.wedge(en-us,VS.85).gifTo open an object handle

  1. Review the recommendations and cautions related to object handles. See LPC and RPC Handles.
  2. Open a cluster handle by calling OpenCluster
  3. Open the object handle by calling OpenCluster. Pass the cluster handle obtained from step 1 as well as the name of the object.
  4. Be sure to close any handles you no longer need. However, never close a cluster handle while object handles obtained from it are still in use.


The following example provides two functions: ClusDocEx_OpenLocalClusterWithName and ClusDocEx_ResAddPossibleOwner. The first function returns an RPC cluster handle by using GetComputerName to supply a name for OpenCluster. The second function illustrates a call to AddClusterResourceNode, which requires a resource handle and a node handle.



//  ClusDocEx_OpenLocalClusterWithName
//  Gets the name of the local node, then 
//  uses this name to open a cluster handle.
//  Returns an RPC cluster handle or NULL if unsuccessful.
HCLUSTER ClusDocEx_OpenLocalClusterWithName()

  HCLUSTER hCluster        = NULL;
  DWORD    dwResult        = ERROR_SUCCESS;
  DWORD    cchNameSize     = MAX_COMPUTERNAME_LENGTH + 1;
  LPWSTR   lpszClusterName = (LPWSTR) LocalAlloc( LPTR, 
                                                  cchNameSize * sizeof( WCHAR ) );

  if( lpszClusterName != NULL )

    //  Get the name of the local node.
    //  Using a name instead of NULL in OpenCluster 
    //  creates an RPC handle.

    if( GetComputerName( lpszClusterName, &cchNameSize ) )
      hCluster = OpenCluster( lpszClusterName );

    dwResult = GetLastError();
    LocalFree( lpszClusterName );

  SetLastError( dwResult );

  return hCluster;
//  end ClusDocEx_OpenLocalClusterWithName


//  ClusDocEx_ResAddPossibleOwner()
//  Adds a node to a resource's list of possible owner nodes.
//  Arguments:
//      IN LPWSTR lpszResourceName  Name of the resource.
//      IN LPWSTR lpszNodeName      Name of the new possible owner.
//      IN LPWSTR lpszClusterName   Specifies the cluster name
//                                  Can be NULL.
//  Return Value:
//      Returns ERROR_SUCCESS if successful, 
//      otherwise returns a system error code.
DWORD ClusDocEx_ResAddPossibleOwner( IN LPWSTR lpszResourceName,
                               IN LPWSTR lpszNodeName,
                               IN LPWSTR lpszClusterName

  HCLUSTER  hCluster  = NULL;
  HNODE     hNode     = NULL;
  HRESOURCE hResource = NULL;
  DWORD     dwResult  = ERROR_SUCCESS;

//  Using a name produces an RPC handle.

  if( lpszClusterName == NULL )
    hCluster = ClusDocEx_OpenLocalClusterWithName();
    hCluster = OpenCluster( lpszClusterName );

//  Verify handle before proceeding.

  if( hCluster == NULL )
    //  Handle error.
    dwResult = GetLastError();
    goto endf;

  hResource = OpenClusterResource( hCluster, lpszResourceName );

  if( hResource == NULL )
    //  Handle error.
    dwResult = GetLastError();
    goto endf;

  hNode = OpenClusterNode( hCluster, lpszNodeName );

  if( hNode == NULL )
    //  Handle error.
    dwResult = GetLastError();
    goto endf;

//  Add the node to the resource's possible owners list.

  dwResult = AddClusterResourceNode( hResource, hNode );

//  Note that hResource and hNode were obtained from the 
//  same cluster handle. Thus they are both guaranteed 
//  to be LPC or RPC handles. The cluster handle in this
//  implementation will always be an RPC handle.


//  Close all handles. Close the cluster handle last.

  if( hNode!= NULL )     CloseClusterNode( hNode );
  if( hResource!= NULL ) CloseClusterResource( hResource );
  if( hCluster!= NULL )  CloseCluster( hCluster );

  return dwResult;

//  end ClusDocEx_ResAddPossibleOwner