ResourceControl

The ResourceControl entry point function performs an operation that applies to a resource.

DWORD WINAPI ResourceControl(
  RESID ResourceId,     
  DWORD ControlCode,    
  LPVOID InBuffer,      
  DWORD InBufferSize,   
  LPVOID OutBuffer,     
  DWORD OutBufferSize,  
  LPDWORD BytesReturned 
);
 

Parameters

ResourceId

[in] Resource identifier of the affected resource.

ControlCode

[in] Control code that represents the operation to be performed. For a list of the valid values for the ControlCode parameter, see Control Codes for Resources.

InBuffer

[in] Pointer to a buffer containing data to be used in the operation. InBuffer can be NULL if no data is required.

InBufferSize

[in] Size, in bytes, of the buffer pointed to by InBuffer.

OutBuffer

[out] Pointer to a buffer containing data resulting from the operation. OutBuffer can be NULL if the operation does not need to return data.

OutBufferSize

[in] Size, in bytes, of the available space pointed to by OutBuffer.

BytesReturned

[out] Number of bytes in the buffer pointed to by OutBuffer that actually contain data.

Return Values

ERROR_SUCCESS

The operation associated with ControlCode was completed successfully.

ERROR_INVALID_FUNCTION

The resource DLL may not support the operation represented by ControlCode. In some cases this is a signal to the Resource Monitor for it to process the request.

If the operation was unsuccessful, ResourceControl returns a Win32 error value.

Notes to Implementers

ResourceControl should be implemented by all resource DLLs. However, it is not necessary to provide code to handle all of the control codes that are defined for resources. As a minimum, you should support the following control codes that manipulate private properties:

• CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES
• CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
• CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES
• CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES
• CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

Without support for CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES, you will not be able to set nonstring private properties on a newly created resource using the command-line tool CLUSTER.EXE. Without support for CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES, you will not be able to validate the properties before setting them.

Without support for CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES, Cluster Administrator will not be able to automatically validate your private properties before setting them.

If resources handled by your resource DLL have required dependencies, you must support CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES.

If your resource DLL needs to replicate a portion of the system registry, you must support CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.

Support for any of the other control codes is optional. To determine how and why to support a particular control code, see its reference entry in the documentation. It is preferable not to provide support for some of the codes because they depend on the standard processing that the Resource Monitor supplies. In particular, do not include support for CLUSCTL_RESOURCE_GET_CHARACTERISTICS because it is important not to override the processing provided by the Resource Monitor.

To request that the Resource Monitor process a control code, return ERROR_INVALID_FUNCTION. You can return this value for a control code regardless of whether you include support for the code in ResourceControl. Some resource DLLs support a control code to augment the functionality that the Resource Monitor supplies.

If at all possible, make your implementation of ResourceControl finish in less than 300 milliseconds.

QuickInfo

  Version: Use Windows NT Server Enterprise Edition 4.0.
  Windows CE: Unsupported.
  Header: Declared in resapi.h.