Online

The Online entry point function marks a resource as available for use.

DWORD WINAPI Online(
  RESID ResourceId,   
  PHANDLE EventHandle 
);
 

Parameters

ResourceId

[in] Resource identifier for the resource to be made available.

EventHandle

[in, out] On input, EventHandle is NULL. Usually, this is a handle to a system object, such as a process. On output, EventHandle contains a handle that is signaled when the resource detects a failure. For example, if EventHandle represents a process and the process is terminated, the EventHandle is signaled and the Resource Monitor will be notified.

EventHandle can also be set to NULL on output, indicating that the resource does not support asynchronous event notification.

Return Values

ERROR_SUCCESS

The operation was successful, and the resource is now online.

ERROR_RESOURCE_NOT_AVAILABLE

The resource was arbitrated with some other systems, and one of the other systems won the arbitration.

ERROR_IO_PENDING

The request is pending and a thread has been activated to process the online request.

Notes to Implementers

Refresh the private properties of the resource to be brought online in your Online entry point function. It is important to get a more recent copy of the properties you initially received from your Open entry point function in the event that changes have occurred since that time. To refresh these private properties, call ClusterResourceControl twice, passing CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES in the dwControlCode parameter for the first call and CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES for the second call.

Make your implementation of Online take less than 300 milliseconds to complete if at all possible. However, if your implementation requires more than 300 milliseconds:

1. Start a separate thread to complete the request.
2. Return ERROR_IO_PENDING immediately.
3. Make the thread that is processing the request periodically report status information to the Resource Monitor by calling the SetResourceStatus callback function. Keep calling SetResourceStatus until one of these situations occurs:
   • The resource is placed in the ClusterResourceOnline state.
   • The request has exceeded the three minute default time limit. A time out causes the Resource Monitor to call Terminate to abort the online request. The time limit is stored in the PendingTimeout common property.

Return a valid handle in EventHandle to use event notification to inform the Resource Monitor of a resource's state. When a resource DLL supports event notification, the Resource Monitor will still call its IsAlive function to thoroughly check for status but will not call LooksAlive.

Whenever possible, do not handle node-specific properties. If you must maintain node-specific properties, record them in the cluster database under a local machine key based on the node identifier. You can retrieve the node identifier by calling GetClusterNodeId.

For example, your resource DLL for managing a disk resource may need to maintain different drive names for each node if the nodes maintain different numbers of disks. That is, the physical drive may assume one name on one node and a different name on another node. Handle this situation by having cluster database keys for each of the node's computer names, and parse for additional parameters under the node-specific cluster database keys which are based on the node identifier.

Example

In Cluster Server's File Share resource DLL, Online uses the resource identifier in ResourceId as an index into a resource table that keeps track of all resources handled by the DLL. Online retrieves the address of the resource structure for the appropriate resource and uses the information in this resource structure to call the Win32 function NetShareAdd to add the share name to the server.

QuickInfo

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