pascalSCADA OPM: CommPort: Class TCommPortDriver

Pascal SCADA OPM

previous page next page

Class TCommPortDriver

Description
Hierarchy
Fields
Methods
Properties

Unit

CommPort

Declaration

type TCommPortDriver = class(TComponent)

Description

The base class of an communication port driver.

:

This class was created to reduce the efforts to create new communication port drivers, both on single-thread and multi-threads environments.

To make a minimal usable communication port driver, you must overwrite only five virtual methods that do all work (don't forget of the properties/procedures/functions particular of your communication port). The methods that you must overwrite are this:

function ComSettingsOK:Boolean; virtual; Overwrite this function to check if the setting of your communication port are rigth.

procedure PortStart(var Ok:Boolean); virtual; Opens the communication port. If it was open successfully, return true on OK variable.

procedure PortStop(var Ok:Boolean); virtual; Closes the communication port. If it was closed successfully, return true on OK variable.

procedure Read(Packet:PIOPacket); virtual; abstract; Overwrite this method to read data of your communication port.

procedure Write(Packet:PIOPacket); virtual; abstract; Overwrite this method to write data on your communication port.

After do this, your communication port already is thread-safe!

Hierarchy

  • TComponent
  • TCommPortDriver

Overview

Fields

Protected FDelayBetweenCmds:Cardinal;
Protected FExclusiveDevice:Boolean;
Protected PActive:Boolean;
Protected PClearBufOnErr:Boolean;
Protected Protocols:array of TComponent;
Protected EventInterfaces:IPortDriverEventNotificationArray;

Methods

Protected procedure SetActive(v:Boolean); virtual;
Protected procedure CommError(WriteCmd:Boolean; Error:TIOResult);
Protected procedure CommPortOpened;
Protected procedure CommPortOpenError;
Protected procedure CommPortClose;
Protected procedure CommPortCloseError;
Protected procedure CommPortDisconected;
Protected procedure DoReadError(Error:TIOResult); virtual;
Protected procedure DoWriteError(Error:TIOResult); virtual;
Protected procedure DoPortOpened(sender:TObject); virtual;
Protected procedure DoPortOpenError(sender:TObject); virtual;
Protected procedure DoPortClose(sender:TObject); virtual;
Protected procedure DoPortCloseError(sender:TObject); virtual;
Protected procedure DoPortDisconnected(sender:TObject); virtual;
Protected procedure Read(Packet:PIOPacket); virtual; abstract;
Protected procedure Write(Packet:PIOPacket); virtual; abstract;
Protected procedure NeedSleepBetweenRW; virtual; abstract;
Protected procedure PortStart(var Ok:Boolean); virtual; abstract;
Protected procedure PortStop(var Ok:Boolean); virtual; abstract;
Protected function ComSettingsOK:Boolean; virtual;
Protected procedure ClearALLBuffers; virtual; abstract;
Protected procedure DoExceptionInActive;
Protected procedure RefreshLastOSError;
Public constructor Create(AOwner:TComponent); override;
Public destructor Destroy; override;
Public procedure AddProtocol(Prot:TComponent);
Public procedure DelProtocol(Prot:TComponent);
Public function IOCommandSync(Cmd:TIOCommand; ToWrite:BYTES; BytesToRead, BytesToWrite, DriverID, DelayBetweenCmds:Cardinal; CallBack:TDriverCallBack; Res1:TObject; Res2:Pointer; OnBegin:TNotifyEvent = nil; OnEnd:TNotifyEvent = nil):Cardinal; overload; deprecated;
Public function IOCommandSync(Cmd:TIOCommand; BytesToWrite:Cardinal; ToWrite:BYTES; BytesToRead, DriverID, DelayBetweenCmds:Cardinal; pkt:PIOPacket; OnBegin:TNotifyEvent = nil; OnEnd:TNotifyEvent = nil):Cardinal; overload;
Public function Lock(DriverID:Cardinal):Boolean;
Public function Unlock(DriverID:Cardinal):Boolean;
Public function ReallyActive:Boolean; virtual;

Properties

Protected property OnCommErrorReading: TCommPortErrorEvent read FOnCommErrorReading write FOnCommErrorReading;
Protected property OnCommErrorWriting: TCommPortErrorEvent read FOnCommErrorWriting write FOnCommErrorWriting;
Protected property OnCommPortOpened: TNotifyEvent read FOnCommPortOpened write FOnCommPortOpened;
Protected property OnCommPortOpenError: TNotifyEvent read FOnCommPortOpenError write FOnCommPortOpenError;
Protected property OnCommPortClosed: TNotifyEvent read FOnCommPortClosed write FOnCommPortClosed;
Protected property OnCommPortCloseError: TNotifyEvent read FOnCommPortCloseError write FOnCommPortCloseError;
Protected property OnCommPortDisconnected: TNotifyEvent read FOnCommPortDisconnected write FOnCommPortDisconnected;
Protected property ReadRetries: Cardinal read FReadRetries write SetReadRetries default 3;
Protected property WriteRetries: Cardinal read FWriteRetries write SetWriteRetries default 3;
Published property Active: Boolean read PActive write SetActive stored true default false;
Published property ClearBuffersOnCommErrors: Boolean read PClearBufOnErr write PClearBufOnErr default true;
Published property LockedBy: Cardinal read PLockedBy;
Published property Locked: Boolean read GetLocked;
Published property LastOSErrorNumber: LongInt read FLastOSErrorNumber;
Published property LastOSErrorMessage: AnsiString read FLastOSErrorMessage;
Published property CommandsPerSecond: LongInt read FCommandsSecond;
Published property TXBytes: Int64 read FTXBytes;
Published property TXBytesSecond: Int64 read FTXBytesSecond;
Published property RXBytes: Int64 read FRXBytes;
Published property RXBytesSecond: Int64 read FRXBytesSecond;
Published property LogIOActions: Boolean read FLogActions write SetLogActions default false;
Published property LogFile: AnsiString read FLogFile write SetLogFile;

Description

Fields

Protected FDelayBetweenCmds:Cardinal;
 
Protected FExclusiveDevice:Boolean;

: Stores if the communication port is exclusive (like serial port)

Protected PActive:Boolean;

: Stores the actual state of the communication port driver (Open or closed);

Protected PClearBufOnErr:Boolean;

: Stores if the buffers must be cleared after some communication error.

Protected Protocols:array of TComponent;

: Array that stores what's protocols uses this communication port driver.

See also
TProtocolDriver
Protected EventInterfaces:IPortDriverEventNotificationArray;

: Array que armazena os drivers de protocolo dependentes.

See also
TProtocolDriver

Methods

Protected procedure SetActive(v:Boolean); virtual;

///////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////// : If v = True, opens the communication port, else closes.

Protected procedure CommError(WriteCmd:Boolean; Error:TIOResult);

: Send a communication error message from the thread to the application.

Protected procedure CommPortOpened;

: Sends a message to the application/protocol thread when the communication port was open.

Protected procedure CommPortOpenError;

: Sends a message to the application/protocol thread, if communication port can't be open.

Protected procedure CommPortClose;

: Sends a message to the application/protocol thread when the communication port was close.

Protected procedure CommPortCloseError;

: Sends a message to the application/protocol thread, if the communication port can't be closed.

Protected procedure CommPortDisconected;

: Sends a message to the application/protocol thread, if the communication port was disconnected (TCP/IP).

Protected procedure DoReadError(Error:TIOResult); virtual;

///////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////// : Notifies the OnCommErrorReading event about an read error.

Protected procedure DoWriteError(Error:TIOResult); virtual;

: Notifies the OnCommErrorWriting event about an write error.

Protected procedure DoPortOpened(sender:TObject); virtual;

: Notifies the OnCommPortOpened when the communication port opens.

Protected procedure DoPortOpenError(sender:TObject); virtual;

: Notifies the OnCommPortOpenError event if a error occurs when opening communication port.

Protected procedure DoPortClose(sender:TObject); virtual;

: Notifies the OnCommPortClosed event when the communication port was closed.

Protected procedure DoPortCloseError(sender:TObject); virtual;

: Notifies the OnCommPortCloseError event if a error occurs when closing communication port.

Protected procedure DoPortDisconnected(sender:TObject); virtual;

: Notifies the OnCommPortDisconnected event when a connection is lost (usefull in TCP/IP)

Protected procedure Read(Packet:PIOPacket); virtual; abstract;

: Procedure called when is needed to read something on communication port. To create a new communication port, you must overwritten this procedure. .

Parameters
Packet
PIOPacket. Record with informations to execute the read command.
See also
TIOPacket
Protected procedure Write(Packet:PIOPacket); virtual; abstract;

: Procedure called when is needed to write something on communication port. To create a new communication port, you must overwritten this procedure. .

Parameters
Packet
PIOPacket. Record with informations to execute the write command.
See also
TIOPacket
Protected procedure NeedSleepBetweenRW; virtual; abstract;

: NeedSleepBetweenRW must be overwritten on communication ports that want's a delay between the read and write commands.

Protected procedure PortStart(var Ok:Boolean); virtual; abstract;

: PortStart is called to opens the communication port. To create a new communication port driver, this procedure must be overwritten.

Returns

Returns True in Ok param if the communication port was opened sucessfull.

See also
TDriverCommand
Protected procedure PortStop(var Ok:Boolean); virtual; abstract;

: PortStop is called to closes the communication port. To create a new communication port driver, this procedure must be overwritten.

Returns

Returns True in Ok param if the communication port was closed sucessfull.

See also
TDriverCommand
Protected function ComSettingsOK:Boolean; virtual;

: ComSettingsOK is called to check if the communication port settings are right. To create a new communication port driver, if this function was not overwritten, all combinations of settings will be invalidated and the communication port will not open.

Returns

Returns True if the communication port settings are right. False if not.

See also
TDriverCaller
Protected procedure ClearALLBuffers; virtual; abstract;

: ClearALLBuffers is called when is needed clear the input/output buffers of the communication port.

Is recommended overwriten this procedure on your communication port driver.

Protected procedure DoExceptionInActive;

: DoExceptionInActive raises an exception if the communication port is active. Call this procedure to avoid changes in properties that cannot be changed with the communication port activated.

Protected procedure RefreshLastOSError;

: RefreshLastOSError refresh the properties LastOSErrorNumber and LastOSErrorMessage with the last OS error.

Public constructor Create(AOwner:TComponent); override;

: Creates the communication port, initializing threads and internal variables.

Public destructor Destroy; override;

: Destroys the communication port, closing and removing all references of protocols to it.

See also
TProtocolDriver
AddProtocol
DelProtocol
Public procedure AddProtocol(Prot:TComponent);

: Adds a protocol driver as a dependent of the communicaton port.

Parameters
Prot
TProtocolDriver. Protocol driver to be added as a dependent.
Exceptions raised
Exception
if the Prot is not a TProtocolDriver.
See also
TProtocolDriver
Public procedure DelProtocol(Prot:TComponent);

: Removes a protocol driver of the list of dependents.

Parameters
Prot
TProtocolDriver. Protocol driver to be removed of the dependents list.
See also
TProtocolDriver
Public function IOCommandSync(Cmd:TIOCommand; ToWrite:BYTES; BytesToRead, BytesToWrite, DriverID, DelayBetweenCmds:Cardinal; CallBack:TDriverCallBack; Res1:TObject; Res2:Pointer; OnBegin:TNotifyEvent = nil; OnEnd:TNotifyEvent = nil):Cardinal; overload; deprecated;

Warning: this symbol is deprecated.

: Do a synchronous I/O request to the communication port (blocks your application until this action is done).

Parameters
Cmd
TIOCommand. The sequence of I/O to be executed.
ToWrite
BYTES. Data to be written on the communication port
BytesToRead
Cardinal. Number of bytes to be read on communication port.
BytesToWrite
Cardinal. Number of bytes to be written on communication port.
DriverID
Cardinal. Identifies the protocol that is calling the function.
DelayBetweenCmds
Cardinal. Delay in milliseconds between the commands of read and write.
CallBack
TDriverCallBack. Procedure called to return the data of the I/O command (with the write result and the bytes received).
Res1
TObject. Object to be passed to callback.
Res2
Pointer. Pointer to be passed to callback.
OnBegin
TNotifyEvent. Procedure called by the communication port before start the communication operation. It can be used to start a timer or to release a mutex of a the protocol driver to improve the tag update rates.
OnEnd
TNotifyEvent. Procedure called after finish the communication operation. Can be used to finish the cronometer or to get again the mutex of the protocol driver, freed previously by the OnBegin.
Returns

Returns the I/O command ID. Returns 0 if the communication port has been destroied or if the communication port is closed.

See also
TIOCommand
BYTES
TDriverCallBack
IOCommandASync
Public function IOCommandSync(Cmd:TIOCommand; BytesToWrite:Cardinal; ToWrite:BYTES; BytesToRead, DriverID, DelayBetweenCmds:Cardinal; pkt:PIOPacket; OnBegin:TNotifyEvent = nil; OnEnd:TNotifyEvent = nil):Cardinal; overload;

: Do a synchronous I/O request to the communication port (blocks your application until this action is done).

Parameters
Cmd
TIOCommand. The sequence of I/O to be executed.
BytesToWrite
Cardinal. Number of bytes to be written on communication port.
ToWrite
BYTES. Data to be written on the communication port
BytesToRead
Cardinal. Number of bytes to be read on communication port.
DriverID
Cardinal. Identifies the protocol that is calling the function.
DelayBetweenCmds
Cardinal. Delay in milliseconds between the commands of read and write.
pkt
PIOPacket. Structure that will return informations about the command execution. If Nil you will not able to check result of the command.
OnBegin
TNotifyEvent. Procedure called by the communication port before start the communication operation. It can be used to start a timer or to release a mutex of a the protocol driver to improve the tag update rates.
OnEnd
TNotifyEvent. Procedure called after finish the communication operation. Can be used to a timer or to get again the mutex of the protocol driver, freed previously by the OnBegin.
Returns

Returns the I/O command ID. Returns 0 if the communication port has been destroied or if the communication port is closed.

See also
TIOCommand
BYTES
TDriverCallBack
IOCommandASync
Public function Lock(DriverID:Cardinal):Boolean;

: Locks the communication port for exclusive use.

Parameters
DriverID
Cardinal. Identifies who wants exclusive access.
Returns

True if the communicaton port was locked, False if not.

Public function Unlock(DriverID:Cardinal):Boolean;

: Remove the exclusive access on communication port.

Parameters
DriverID
Cardinal. Identifies who has the exclusive access on communication port.
Returns

True if the communication port was released to be used on non-exclusive access.

Public function ReallyActive:Boolean; virtual;

: Return true if the communication port is open really.

Properties

Protected property OnCommErrorReading: TCommPortErrorEvent read FOnCommErrorReading write FOnCommErrorReading;

: Event called when a read error occurs on communication port.

Protected property OnCommErrorWriting: TCommPortErrorEvent read FOnCommErrorWriting write FOnCommErrorWriting;

: Event called when a write error occurs on communication port.

Protected property OnCommPortOpened: TNotifyEvent read FOnCommPortOpened write FOnCommPortOpened;

: Event called when the communication port was open.

Protected property OnCommPortOpenError: TNotifyEvent read FOnCommPortOpenError write FOnCommPortOpenError;

: Event called when the communication was not open successfully.

Protected property OnCommPortClosed: TNotifyEvent read FOnCommPortClosed write FOnCommPortClosed;

: Event called when the communication port was closed.

Protected property OnCommPortCloseError: TNotifyEvent read FOnCommPortCloseError write FOnCommPortCloseError;

: Event called when the communication was not closed successfully.

Protected property OnCommPortDisconnected: TNotifyEvent read FOnCommPortDisconnected write FOnCommPortDisconnected;

: Event called when the communication port has been disconected.

Protected property ReadRetries: Cardinal read FReadRetries write SetReadRetries default 3;

: Number of read retries.

Protected property WriteRetries: Cardinal read FWriteRetries write SetWriteRetries default 3;

: Number of write retries.

Published property Active: Boolean read PActive write SetActive stored true default false;

: Opens (True) or close (False) the communication port.

Published property ClearBuffersOnCommErrors: Boolean read PClearBufOnErr write PClearBufOnErr default true;

:If True, clears the input/output buffers of communication port if an I/O error has been found.

Published property LockedBy: Cardinal read PLockedBy;

:Identification of who have exclusive access on communication port.

Published property Locked: Boolean read GetLocked;

:Returns True if the communication port was locked for exclusive access.

Published property LastOSErrorNumber: LongInt read FLastOSErrorNumber;

: The last error code registered by the OS.

Published property LastOSErrorMessage: AnsiString read FLastOSErrorMessage;

: The last error message registered by the OS.

Published property CommandsPerSecond: LongInt read FCommandsSecond;

: How many I/O commands are processed by second. Updated every 1 second.

Published property TXBytes: Int64 read FTXBytes;

: Total of bytes sent (written).

Published property TXBytesSecond: Int64 read FTXBytesSecond;

: Total of bytes sent on the last second.

Published property RXBytes: Int64 read FRXBytes;

: Total of bytes received (received).

Published property RXBytesSecond: Int64 read FRXBytesSecond;

: Total of bytes received on the last second.

Published property LogIOActions: Boolean read FLogActions write SetLogActions default false;

: Enable/disables the log of I/O actions of the communication port.

Published property LogFile: AnsiString read FLogFile write SetLogFile;

: File to store the log of I/O actions of the communication port.

Author

Generated by PasDoc 0.14.0.
previous page start next page