Units
Class Hierarchy
Classes, Interfaces and Objects
Types
Enumerations
Variables
Constants
Functions and Procedures
Identifiers

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

Publicconstructor Create(AOwner: TComponent); override;
Publicdestructor Destroy; override;
Protectedfunction CheckResourceDataReadiness: Boolean; virtual;
Protectedfunction GetFileAccMode: Integer; virtual;
Publicfunction GetParentComponent: TComponent; override;
Protectedfunction GetRegisteredParamsPointer: Pointer; virtual;
Protectedfunction GetRegisterPriority: Byte; virtual; abstract;
Protectedfunction GetResourceModuleNode: Byte; virtual; abstract;
Protectedfunction GetResourceUniqueId: LongWord; virtual; abstract;
Protectedprocedure OnGetRegisteredParamsPointerFail; virtual;
Protectedprocedure OnPreRegisterResourceFail; virtual;
Protectedprocedure OnRegisterResourceFail; virtual;
Protectedfunction PostRegisterResource(RegisteredParams: Pointer; IoctlResult: Integer): Boolean; virtual;
Protectedprocedure PostUnregisterResource(IoctlResult: Integer); virtual;
Protectedfunction PreRegisterResource: Boolean; virtual;
Protectedprocedure PreUnregisterResource; virtual;
Protectedprocedure RaiseOnAddResource; virtual;
Protectedprocedure RaiseOnRemoveItem; virtual;
Protectedfunction RegisterResource: Boolean;
Protectedprocedure SetIOCTLCodes; virtual;
Protectedprocedure SetName(const NewName: TComponentName); override;
Protectedprocedure UnregisterResource;

Description

Publicconstructor Create(AOwner: TComponent); override;

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.

Publicdestructor Destroy; override;

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.

Protectedfunction CheckResourceDataReadiness: Boolean; virtual;

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.

Protectedfunction GetFileAccMode: Integer; virtual;

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.

Publicfunction GetParentComponent: TComponent; override;

TkdResource redefines GetParentComponent so that the corresponding TkdCustomCard instance is always the parent.

Protectedfunction GetRegisteredParamsPointer: Pointer; virtual;

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.

Protectedfunction GetRegisterPriority: Byte; virtual; abstract;

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.

Protectedfunction GetResourceModuleNode: Byte; virtual; abstract;

GetResourceModuleNode method must be overridden by each descendant to return 0 and all future descendants must be arranged to return 0 as well.

Protectedfunction GetResourceUniqueId: LongWord; virtual; abstract;

GetResourceUniqueId method has to be overridden by each descendant to return the specific identifier of the hardware resource type the resource models.

Protectedprocedure OnGetRegisteredParamsPointerFail; virtual;

OnGetRegisteredParamsPointerFail method is called immediately after (and only if) GetRegisteredParamsPointer method unsuccessfully completes (by returning False).

Protectedprocedure OnPreRegisterResourceFail; virtual;

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.

Protectedprocedure OnRegisterResourceFail; virtual;

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.

Protectedfunction PostRegisterResource(RegisteredParams: Pointer; IoctlResult: Integer): Boolean; virtual;

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.

Protectedprocedure PostUnregisterResource(IoctlResult: Integer); virtual;

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.

Protectedfunction PreRegisterResource: Boolean; virtual;

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.

Protectedprocedure PreUnregisterResource; virtual;

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.

Protectedprocedure RaiseOnAddResource; virtual;

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.

Protectedprocedure RaiseOnRemoveItem; virtual;

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.

Protectedfunction RegisterResource: Boolean;

RegisterResource method registers the resource in the system and establishes the instant working session with the GDD.

Protectedprocedure SetIOCTLCodes; virtual;

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.

Protectedprocedure SetName(const NewName: TComponentName); override;

SetName method is overridden to automatically update all references by name to the resource from other resources.

Protectedprocedure UnregisterResource;

UnregisterResource method unregisters the resource in the system and closes the current working session with the GDD.

Properties

Overview

Publicproperty CustomCard: TkdCustomCard;
Publishedproperty Description: TStrings;
Publicproperty Handle: LongInt;
Publicproperty LastError: LongWord;
Publicproperty RegisterPriority: Byte;
Publicproperty ResourceHexId: String;
Publicproperty ResourceId: LongWord;
Publicproperty ResourceRegistered: Boolean;

Description

Publicproperty CustomCard: TkdCustomCard;

CustomCard property is an accessor for obtaining the pointer to the hardware device instance the resource belongs to.

Publishedproperty Description: TStrings;

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.

Publicproperty Handle: LongInt;

Handle property is an accessor for obtaining the unique identifier of the resource. This value is automatically assigned.

Publicproperty LastError: LongWord;

LastError property is an accessor for obtaining the code of the last error returned by the GDD.

Publicproperty RegisterPriority: Byte;

RegisterPriority property is an accessor for obtaining the specific registration priority of the hardware resource type the resource models.

Publicproperty ResourceHexId: String;

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.

Publicproperty ResourceId: LongWord;

ResourceId property is an accessor for obtaining the specific identifier of the hardware resource, the handle of the resource.

Publicproperty ResourceRegistered: Boolean;

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.