begin

You can use MS Visual C++ development system or other C/C++ development tools to write custom resource dlls. The example in this article uses the

Microsoft Visual c++ b version contains Unicode MFC library.

MIDL compiler version (MIDL compiler can be found in SDK)

Active Template Library (ATL) version (required by code generated by code extension sample and resource type generation wizard)

When building the compilation environment, please refer to the platform SDK, especially the chapter on preparing the build environment and the precautions for developers.

A complete resource DLL reference implementation can also be found in the platform SDK example (see SMB *** p).

Create a new resource type

To create a new resource type, you must write a resource DLL and a cluster manager extension DLL. The simple method is to run the resource type generation wizard to create a resource DLL. The wizard will declare the resource DLL framework containing the entry point and/or the exported cluster manager extension DLL.

For the complete steps of creating a resource DLL, please refer to the section of Creating a custom resource type and a custom resource DLL using the resource type AppWizard in the SDK documentation.

The generated resource DLL framework only contains the most basic failover and recovery functions. To use all the functions of a cluster environment and allow DLLs to provide specific resource information, you need to write your own code. Note that the framework code generated by the wizard contains TODO and ADDPARAM: comments to indicate specific information about where resources need to be added. As described below, you need to use the resource API to complete most customization functions.

Custom resource DLL

As mentioned earlier, the resource API contains several entry point functions, which are implemented in the resource DLL. The resource monitor uses these entry point functions to manage the resources provided by the DLL, and the resource monitor implements some callback functions. Resource DLLs use these callback functions to report status to the cluster service, or to record event logs for system administrators.

Most entry point functions are two special API entry point functions necessary for all resources-arbitration and release-which are only needed when writing arbitration resources. These two functions are not discussed in this article. The remaining entry point functions are listed below. This article will discuss their details.

Each resource DLL supported by cluster software should follow the following principles.

In an exceptional case, the resource DLL is non-reentrant for a given resource instance, that is, the Terminate entry point function should be called at any time, even if the thread in the resource DLL is in a blocking state waiting for the online or offline call to be completed.

The resource DLL is reentrant for other resource ids. If a resource DLL has multiple resource IDs, it must synchronize all the global data in the DLL.

The entry point function should not take more than milliseconds to complete the operation in the resource DLL. If an entry point function-especially Online Offline LooksAlive or Isaive-exceeds this limit, a thread should be generated to handle this time-consuming operation (note that the current wizard will generate a thread for a future version of Online, and it should also generate a thread for offline).

During the initialization of the resource DLL, the entry point function of the DLL (the standard DLL entry after the system loads the DLL) is called with the DLL_PROCESS_ATTACH flag, and then the resource monitor starts to call the entry point function of the resource API.

initiator

When the resource DLL is loaded, the resource monitor calls the startup routine. Note that only the startup entry point function is exported, and all other entry point functions implemented in the resource DLL are accessed through the function table returned by startup.

The following is the definition of the startup routine dword winapi (pset _ resource _ status _ routeset re supported by the minimum version of the lpcwstr resource type dword and the maximum version of dword). Source status PLOG _ event _ routine log event PCLRES _ function _ table * function table);

The ResourceType parameter identifies the type of resource that is started.

SetResourceStatus and LogEvent are callback functions implemented by resource monitor (these callback functions will be discussed later in this article). After calling online or offline entry point functions, if they take more than milliseconds, the resource DLL should call SetResourceStatus to inform the cluster resource status, and the resource DLL should also use logevent. T report events and errors (SetResourceStatus should be called only by Online or Offline and return ERROR_IO_PENDING only on Online or Offline).

The FunctionTable structure contains the function addresses of the remaining entry points of the resource DLL.

Please note that the starting entry point function resource DLL holds the unique location of callback functions LogEvent and SetResourceStatus.

Startup returns the following values

If the request is successful, ERROR_SUCCESS is returned.

ERROR_REVISION_MISMATCH is returned if the resource does not support versions between MinVersionSupported and MaxVersionSupported.

Operation unsuccessful. Return to Win? Error value of programming interface

In order to optimize resource operation, it is necessary to ensure that the startup can be completed within milliseconds.

Open routine

Once the startup returns successfully, the resource monitor usually calls the Open entry point function for each resource managed by the resource DLL.

The definition of the Open routine is as follows: residvinapi open (lpcwstr resourcename HKEY resource Key Resource _ Handle resource handle);

The ResourceName parameter identifies the open resource (a resource DLL can provide multiple resources of a given type). The ResourceKey parameter is specific information about resources, which is a private property and located in the cluster database. The key value is closed when open returns, so if the resource accesses the key value DLL in other entry point functions, it should call ClusterRegOpenK. Use ey or clusterregcreatekey resource handle parameters in SetResourceStatus and LogEvent callback functions.

Open uses the cluster API to open the cluster database, and obtains the resource parameters and private properties. It is very important that the resource DLL should check whether the resource is currently offline at the open entrance (a resource cannot be online on multiple nodes at the same time). If the resource is currently online, the DLL should try to take it offline (note that in this case, online and offline indicate the status of the application or service. Not a given cluster node-the resource must be truly offline and does not belong to that node). In addition, in the Open routine, the resource DLL should create a special data structure for the resource.

Note that if the resource is a quorum resource, the cluster API is not available in the Open routine.

Open returns the following values

If the operation is successful, the resource identification (RESID) is returned.

If the operation is unsuccessful and returns NULL, SetLastError should be called to indicate the error.

If Open returns an error (returns NULL), the resource will be unmanageable, so Open should only return an error in very rare cases (for example, it cannot allocate memory for the resource).

For the optimization of resources, ensure that the opening of the implementation will be completed within milliseconds.

Online program

When the resource is opened, the resource monitor calls the Online entry point function to bring the resource online.

The Online routine is defined as dword winapi online (resid resourceid p handle event handler);

The ResourceId parameter is passed to the entry function, which is the unique identifier of the resource (the same as the value returned by the Open entry function). The resource DLL can return the EventHandle parameter to the resource monitor to asynchronously inform the resource monitor of its own status. If the EventHandle parameter is not singal, the resource monitor will periodically call the LooksAlive entry function of the resource DLL to check the resource status. If you don't want this method to interfere with resources, the DLL should return a valid handle in the EventHandle parameter. You can notify the resource monitor of any state change by returning a valid EventHandle resource DLL.

Each resource type must have its own online portal function. This different implementation is needed, because different types of resources have different requirements. For example, connecting a disk online is completely different from connecting an ordinary application. Connecting a disk requires loading a disk to verify the disk signature, and connecting an application online only requires calling CreateProcess.

Online returns the following values

If the operation is successful and the resource now returns ERROR_SUCCESS online.

If the resource is exclusive to other systems and one of them has exclusive rights, ERROR_RESOURCE_NOT_AVAILABLE is returned.

If the request is waiting and a thread has been activated to process the request, ERROR_IO_PENDING is returned.

If the operation is unsuccessful, Online returns the Win error value.

In order to optimize the operation of resources and ensure that the execution of online routines can complete processing in milliseconds. If not, you should immediately return ERROR_IO_PENDING to the resource monitor SetResourceStatus callback function (the address of this function is saved in the startup entry function) to indicate the resource status. Once the resource is online, the worker thread should be suspended or suspended for future use.

If the resource cannot be online for any reason, the resource DLL should use the LogEvent callback function to record the event log, and should call the SetResourceStatus function SetResourceStatus to indicate the online or offline status of the resource. Cluster resources can be in one of the following states.

Online-Status Code Cluster resource online

Offline-Status code Cluster resource is offline.

Failed-status code ClusterResourceFailed

Waiting for online-status code ClusterResourceOnlinePending

Waiting to go offline-status code ClusterResourceOfflinePending

For more information about SetResourceStatus, please refer to the platform SDK.

If the resource is still not online after a few minutes, the resource monitor will call the Terminate entry function to abort the operation. If a resource needs to use Cluster exe, the cluster manager of the cluster API, or other management tools for more than minutes, you can modify the public properties of PendingTimeout by using the control code clusctl _ resource _ set _ m. _ properties (for more information about the public and private properties of the ClusterResourceControl code, please refer to the platform SDK documentation.

LooksAlive and IsAlive routines

Once the resource is online, the resource monitor will periodically check the status of the resource. The resource monitor uses lookalive and isaive entry functions to do this. The resource monitor uses lookalive for temporary inspection and isaive for thorough inspection.

Lookalive routine is defined as boolwinapi lookalive (resid resourceid);

The Isave routine is defined as bool winapi isave (resid resourceid);

In these two routines, the ResourceId parameter uniquely identifies the checked resource instance. Usually, Lookalive is used for simple checking (for example, whether the process is still running, whether the file * * * still exists, and so on). ), and the resource manager can call Lookalive frequently. If you don't want the resource DLL to be interrupted by it, you can return a valid EventHandle (as mentioned above) in the Online routine, and then use this handle to inform the resource monitor of the resource status.

The IsAlive entry function calculates more detailed resource status and is executed by the resource monitor (which cannot be stopped). The resource DLL should thoroughly check the resource to see if it works properly. For example, the database resource should check whether the database can be written to the disk, so as to query and update the disk.

LooksAlive returns the following values

Returns TRUE if the resource may be online and available.

If the resource is not working properly, LooksAlive returns FALSE.

IsAlive returns the following values

Returns TRUE if the resource is online and working properly.

Returns FALSE if the resource is not working properly.

For optimization purposes, the IsAlive entry function should be completed within milliseconds. As mentioned above, a separate worker thread should be created to complete the inspection of resources. The worker thread will then publish the status so that IsAlive can get it and return it to the resource manager.

Note that LooksAlive cannot exceed milliseconds under any circumstances. In most cases, it should not exceed milliseconds. IsAlive is a little longer, but even if it is called asynchronously, other resource entry functions managed by the resource monitor in the same thread will wait for IsAlive to return to the derived thread directly, which cannot improve this situation, so IsAlive should be completed within milliseconds.

Offline program

So far, the discussion of entry function is about customizing a well-behaved resource DLL from the core. The following entry functions provide a mechanism for ending and unloading resources. The first is the offline function.

The offline function is defined as dword winapi offline (resid resourceid);

The ResourceId parameter uniquely identifies the resource. When the resource is offline, the resource monitor calls this entry function. Once offline, the cluster client can no longer use the resource.

Offline returns the following values

If the resource offline request completes successfully, ERROR_SUCCESS is returned.

If the request is still waiting and a thread has been activated to handle the offline request, ERROR_IO_PENDING is returned.

If the operation cannot be completed for other reasons, Win error code should be returned.

The resource DLL should gracefully close the resource and return from the portal within milliseconds. If the offline routine is implemented beyond this limit, it should return ERROR_IO_PENDING and generate a thread to complete the offline request. The thread should use the SetResourceStatus callback to continuously update the resource status of the resource monitor until the resource status is ClusterResourceOffline.

If the resource is not closed normally within the PendingTimeout, or the Offline function returns a Win error code, the resource monitor will call the Terminate entry function to terminate the resource forcibly.

Shutdown routine

The Close entry function is used to close a resource and can only be called once for a resource. Close should be used to transform the structure allocated by the Open Offline ResourceControl or ResourceTypeControl entry function. If the resource to be closed is still not offline, call Terminate to force it to go offline.

The closing routine is defined as Void WinAPI Close (ResidResourceID);

The resource id parameter is the unique identifier of the closed resource.

Close has no return value.

The resource DLL should shut down the resource within milliseconds, but if this limit is exceeded, the cluster service will handle it in an appropriate way.

routine

The Terminate entry function will immediately terminate a process that did not shut down normally when calling Offline.

The termination routine is defined as void winapi terminate (resid resourceid);

ResourceId is the unique identifier of a resource that is forced offline. If the thread of the resource DLL is waiting for the resource to go offline or taking the resource offline normally, the offline operation of the thread will be abandoned and the resource will be forced offline.

Terminate did not return a value.

ResourceControl and ResourceTypeControl routines

The entry functions of ResourceControl and ResourceTypeControl are optional, but Microsoft suggests to implement these two functions to support ClusterResourceControl code management tools (such as cluster manager and Cluster Exe) and cluster-supporting applications to use ClusterresourceControl and ClusterResourceTypeC. Control functions specifically communicate with resources, for example, these functions can be used to set properties (public and private), request operations, and so on. When the manager or cluster-aware application calls any ClusterResourceXXXXControl function, the resource manager will call ResourceControl or ResourceTypeControl respectively and get the correct control code. The incoming resource DLL that implements these two routines will execute control requests or set resource properties according to control codes. For the unprocessed control code, the resource DLL should return the correct state (ERROR_INVALID_FUNCTION state) to the resource monitor. In this case, if there is a default processing action, the resource monitor will execute it.

The ResourceControl routine is defined as dword winapi resource control (the number of bytes returned by the control code lpvoid in buffer dword in buffer size lpvoid out buffer dword out buffer size lpdword);

The ResourceId parameter is the identification of the affected resource, and the ControlCode represents the control code of the operation to be performed. For a list of valid values of this parameter, please refer to the "Resource Control Code" chapter of platform SDK.

InBuffer is the buffer pointer of the incoming data used in this operation. InBufferSize is its byte size. OutBuffer is a buffer pointer to the data returned by the operation. OutBufferSize is its byte size. Note that if the operation does not need data or does not return data, InBuffer and OutBuffer can be empty.

BytesReturned is the number of bytes of actual data in OutBuffer.

ResourceControl returns the following values

If the operation specified by ControlCode completes successfully, it returns ERROR_SUCCESS (although the actual return depends on the control code).

ERROR_INVALID_FUNCTION is returned if the resource DLL does not support the operation indicated by ControlCode, or if the request must be processed by the resource monitor.

If the operation is unsuccessful, a Win error code will be returned.

The ResourceTypeControl routine is defined as dword winapi resource type control (lpcwstr resource type name dword control code lpvoid in buffer dword in buffer size lpvoid). out buffer DWORD out buffer size lpd word bytes returned)；

The ResourceTypeName is the identification of the resource type affected by the operation, and the ControlCode is the control code of the operation to be performed. For a list of valid values of control code parameters, please refer to the resource control code of platform SDK.

InBuffer is the buffer pointer of the incoming data used in this operation. InBufferSize is its byte size. OutBuffer is a buffer pointer to the data returned by the operation. OutBufferSize is its byte size. Note that if the operation does not need data or does not return data, InBuffer and OutBuffer can be empty.

BytesReturned is the actual size of the result data returned in the OutBuffer buffer.

ResourceTypeControl returns the following values

If the operation indicated by ControlCode completes successfully, ResourceTypeControl will return ERROR_SUCCESS (although the actual return value depends on the control code).

ERROR_INVALID_FUNCTION is returned if the resource DLL does not support the operation specified by ControlCode, or if the request must be processed by the resource monitor.

Lishi Xinzhi/Article/program/net/20 13 1 1/ 13753