ClusterGroupControl function

Initiates an operation that affects a group. The operation performed depends on the control code passed to the dwControlCode parameter.

Syntax

DWORD ClusterGroupControl(
  HGROUP  hGroup,
  HNODE   hHostNode,
  DWORD   dwControlCode,
  LPVOID  lpInBuffer,
  DWORD   nInBufferSize,
  LPVOID  lpOutBuffer,
  DWORD   nOutBufferSize,
  LPDWORD lpBytesReturned
);

Parameters

hGroup

Handle to the group to be affected.

hHostNode

If non-NULL, handle to the node to perform the operation represented by the control code. If NULL, the node that owns the group performs the operation. Specifying hHostNode is optional.

dwControlCode

A group control code specifying the operation to be performed. For the syntax associated with a control code, refer to
Control Code Architecture and the following topics:

lpInBuffer

Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.

nInBufferSize

The allocated size (in bytes) of the input buffer.

lpOutBuffer

Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.

nOutBufferSize

The allocated size (in bytes) of the output buffer.

lpBytesReturned

Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpBytesReturned.

Return Value

The function returns one of the following values.

Remarks

If ClusterGroupControl returns ERROR_MORE_DATA, set nOutBufferSize to the number of bytes pointed to by lpBytesReturned and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterGroupControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Examples

The following code fragment demonstrates a call to ClusterGroupControl.

// Allocate buffer.
lpPropList = LocalAlloc( LPTR, cbAllocated );

// Initial call.
dwResult = ClusterGroupControl( hCluster,
                                NULL,
                                CLUSCTL_GROUP_GET_COMMON_PROPERTIES, 
                                NULL,
                                0,
                                lpPropList,
                                cbAllocated,
                                &cbReturned );

// If the buffer was too small, reallocate it to the necessary size,
// returned in cbReturned.
if ( dwResult == ERROR_MORE_DATA )
{
  LocalFree( lpPropList );
  cbAllocated = cbReturned;
  lpPropList = LocalAlloc( LPTR, cbAllocated );
  if ( lpPropList == NULL )
  {
    // Respond to error.
  }
  dwResult = ClusterGroupControl( hCluster,
                                  NULL,
                                  CLUSCTL_GROUP_GET_COMMON_PROPERTIES,
                                  NULL,
                                  0,
                                  lpPropList,
                                  cbAllocated,
                                  &cbReturned );
}

if ( dwResult != ERROR_SUCCESS )
{
  // Respond to error.
}

Requirements

   
Windows version None supported Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Target Platform Windows
Header clusapi.h
Library ClusAPI.lib
DLL ClusAPI.dll

See Also

Group Control Codes

OpenCluster