Class TkdResource
Unit
kdclxcore
Declaration
type TkdResource = class(TComponent)
Description
Resource class TkdResource is the ultimate ancestor for all components modelling hardware resources in KylixDriver Application Library. The class provides no specific members for actual hardware access, rather it represents a detailed framework that allows its descendants to equally establish their working sessions with the GDD and to have the opportunities to be plainly registered in the system. Although TkdResource class has dozens of methods and properties, relevant members are documented only.Methods
Overview
Description
TkdResource redefines Create so that, for hardware resources, Create also: 1. checks that the resource is maintained on the same owner as the hardware device with which the communication is about to be established; 2. checks that the resource can not be created if the hardware device is being currently serviced; 3. establishes all necessary IOCTL codes to communicate with the GDD; 4. establishes the registration priority and performs additional functionality.
TkdResource redefines Destroy so that, for hardware resources, Destroy also checks that the resource can not be detached from the resources list of the hardware device and freed while the hardware device is being currently serviced.
CheckResourceDataReadiness method is internally called by RegisterResource
method and is intended for checking the presence of necessary data the resource needs to be registered with. Descendants override this method to check the sufficiency of all data attributes required to be provided before the registration of the resource. The method must return True to confirm data readiness, otherwise False. CheckResourceDataReadiness is the first method that is automatically called by RegisterResource
in the whole registration sequence.
GetFileAccMode method determines the access mode for the GDD's main device file (/dev/kdmodule0) when the resource is registered in the GDD. The access mode is set read-only by default and there is no need for descendants (except for TkdDirectMemoryRange
class) to override this method.
TkdResource redefines GetParentComponent so that the corresponding TkdCustomCard
instance is always the parent.
GetRegisteredParamsPointer method fills up some structure with data required for the registration of the resource and provides the GDD with the pointer to this structure. TkdResource hosts the uniform structure of record type. For each of currently supported classes this structure keeps: 1. common class identifier field and 2. structured fields for instance specific data by classes. Each resources can be distinguished in the GDD by its unique class identifier. All future descendants have to override this method to provide their own instance specific data and override GetResourceUniqueId
method to provide their own class identifiers. GetRegisteredParamsPointer is the third method that is automatically called by RegisterResource
in the whole registration sequence. The method has to return True on success, otherwise False has to be returned.
GetRegisterPriority method has to be overridden by each descendant to return the specific registration priority of the hardware resource type it models. Due to resources can depend on and refer to each other there can be currently four types of registration priorities: dependent3l_registration_priority
, dependent2l_registration_priority
, dependent1l_registration_priority
and independent_registration_priority
.
GetResourceModuleNode method must be overridden by each descendant to return 0 and all future descendants must be arranged to return 0 as well.
GetResourceUniqueId method has to be overridden by each descendant to return the specific identifier of the hardware resource type the resource models.
OnGetRegisteredParamsPointerFail method is called immediately after (and only if) GetRegisteredParamsPointer
method unsuccessfully completes (by returning False).
OnPreRegisterResourceFail method is called immediately after (and only if) PreRegisterResource
method unsuccessfully completes (by returning False). The method can be overridden to implement some cleanup code if preparation for the registration of the resource has failed.
OnRegisterResourceFail method is called immediately after (and only if) PostRegisterResource
method unsuccessfully completes (by returning False). The method can be overridden to implement some cleanup code if the registration of the resource has failed.
PostRegisterResource method is internally called by RegisterResource
method and can be overridden to: 1. determine whether the resource has been successfully registered or not, 2. perform supplementary actions after the resource has been successfully registered. The method has to return True if the resource is successfully registered, otherwise False. The RegisteredParams argument is the address of the structure that contains data with which the resource was posted to registration. IoctlResult parameter allows to determine whether the resource has been actually registered. If IoctlResult is 0 then the resource is registered, otherwise the LastError
property contains an appropriate error code. PostRegisterResource is the fourth method that is automatically called in the whole registration sequence.
PostUnregisterResource method is internally called by UnregisterResource
method and can be overridden to perform supplementary actions after the resource has been unregistered. PostUnregisterResource is the second method that is automatically called in the whole unregistration sequence.
PreRegisterResource method is internally called by RegisterResource
method and can be overridden to perform preparatory actions for the registration of the resource. It has to return True if the preparation has succeeded, otherwise False.
PreUnregisterResource method is internally called by UnregisterResource
method and can be overridden to perform preparatory actions before the unregistration of the resource. PreUnregisterResource is the first method that is automatically called in the whole unregistration sequence.
RaiseOnAddResource method is introduced empty and can be overridden to allow the resource, for some reason, to raise a meaningful exception to prevent from attaching it to the resources list of the hardware device by AddResource
method of TkdInterrupt
class.
RaiseOnRemoveItem method is introduced empty and can be overridden to allow the resource, for some reason, to raise a meaningful exception to prevent from detaching it from the resources list of the hardware device by RemoveItem
method of TkdInterrupt
class.
RegisterResource method registers the resource in the system and establishes the instant working session with the GDD.
SetIOCTLCodes method introduces two common IOCTL codes to communicate with the GDD: 1. for the registration of the resource; 2: for the unregistration of the resource. Descendants override this method to introduce their own IOCTL codes.
SetName method is overridden to automatically update all references by name to the resource from other resources.
UnregisterResource method unregisters the resource in the system and closes the current working session with the GDD.
Properties
Overview
Description
CustomCard property is an accessor for obtaining the pointer to the hardware device instance the resource belongs to.
Description property hosts remarks you specify for the resource. This property may be useful for keeping any design-time information that is actual for all the life-time of a Kylix project.
Handle property is an accessor for obtaining the unique identifier of the resource. This value is automatically assigned.
LastError property is an accessor for obtaining the code of the last error returned by the GDD.
RegisterPriority property is an accessor for obtaining the specific registration priority of the hardware resource type the resource models.
ResourceHexId property is an accessor for obtaining the hexadecimal string representation of ResourceId
property value. It can be used to identify each particular resource while debugging during communication session with the GDD.
ResourceId property is an accessor for obtaining the specific identifier of the hardware resource, the handle of the resource.
ResourceRegistered property is an accessor for determining whether or not the resource is currently registered in the system. The result is True if the resource is registered.