Detecting Line State Changes with APRO
In serial communications programming it is often necessary to determine line state changes programmatically. The Async Professional status lights are nice to have, but they are only visual clues for you users (i.e., you cannot use them to handle different line state changes in your code). To do that, you must delve into the Async Professional trigger mechanism.

The same status events that the TApdSLController component monitors can be handled with status triggers. A trigger is a hook into the activities of the TApdComPort. Status triggers are internal flags used to fire one of several events of the TApdComPort component (i.e., OnTriggerStatus, OnTriggerModemStatus, and OnTriggerLineStatus). When a trigger condition is met, its trigger event is fired.

There are two steps required to make use of status triggers. First they must be added using the AddStatusTrigger method, and then they must be set using the SetStatusTrigger method. The trigger type (modem, line, output buffer, or transmission) is specified when the trigger is added, and the exact conditions are specified when the trigger is set. When any of the conditions are met, the general purpose OnTriggerStatus event fires. Other events fire according to the trigger type.

The status trigger types and events they fire are:


Trigger Description
stModem trigger on modem status change
stLine trigger on line status change
stOutBuffFree trigger on output buffer free value
stOutBuffUsed trigger on output buffer used value
stOutSent trigger on characters sent

A trigger type of stModem can trigger on the following state changes and fires the OnTriggerModemStatus event:


Trigger Description
msCTSDelta trigger when CT (Clear To Send) changes
msDSRDelta trigger when DSR (Data Set Ready) changes
msRingDelta trigger when a ring is detected
msDCDDelta trigger when DCD (Data Carrier Detect) changes

A trigger type of stLine can trigger on these state changes and fires the OnTriggerLineError event:


Trigger Description
lsOverrun trigger on UART overrun errors
lsParity trigger on parity errors
lsFraming trigger on framing errors
lsBreak trigger on a received line break signal

A trigger type of stOutBuffFree occurs when the output buffer has more than the specified space available and fires the OnTriggerOutBuffFree event.

A trigger type of stOutBuffUsed occurs when the output buffer has less than the specified space used and fires the OnTriggerOutBuffUsed event.

A trigger type of stOutSent occurs when any call to PutChar or PutBlock is made, including assignments to the Output property and fire the OnTriggerOutSent event.

Each trigger that is added returns a value of type Word that indicates which trigger fired the event. This result is an index into an internal trigger array. The specific value of the trigger may change between each instance of your application, so donít assume itís always the same. The following example detects changes in DCD, when the output buffer is 90% full, or when characters have been sent to the output buffer. The OnTriggerStatus event handler updates a status label when triggers are received. Except for the OutSent trigger, all the status triggers must be reset after they fire (i.e., they are "one shot" triggers and wonít fire again).

  TForm1 = class(TForm)
    ApdComPort1 : TApdComPort;
    StartBtn    : TButton;
    StatusLabel : TLabel;
    procedure StartBtnClick(Sender : TObject);
    procedure ApdComPort1TriggerStatus(CP : TObject; 
      TriggerHandle : Word);
    { Public declarations }
    DCDTrig         : Word;
    OutBuffUsedTrig : Word;
    OutSentTrig     : Word;

  Form1 : TForm1;


{$R *.DFM}

procedure TForm1.StartBtnClick(Sender : TObject);
  DCDTrig := ApdComPort1.AddStatusTrigger(stModem);
  ApdComPort1.SetStatusTrigger(DCDTrig, msDCDDelta, True);
  OutBuffUsedTrig := ApdComPort1.AddStatusTrigger(stOutBuffUsed);
  ApdComPort1.SetStatusTrigger(OutBuffUsedTrig, 500, True);
  OutSentTrig := ApdComPort1.AddStatusTrigger(stOutSent);
  ApdComPort1.SetStatusTrigger(OutSentTrig, 0, True);

procedure TForm1.ApdComPort1TriggerStatus(CP : TObject;
  TriggerHandle: Word);
  if TriggerHandle = DCDTrig then begin
    StatusLabel.Caption := 'DCD changed';
    ApdComPort1.SetStatusTrigger(DCDTrig, msDCDDelta, True);
  end else if TriggerHandle = OutBuffUsedTrig then begin
    StatusLabel.Caption := 'OutBuff has more that 500 chars pending';
    ApdComPort1.SetStatusTrigger(OutBuffUsedTrig, 500, True);
  end else if TriggerHandle = OutSentTrig then
    StatusLabel.Caption := 'Something was transmitted'


This site is not affiliated, endorsed, or otherwise associated with the entity formerly known as TurboPower Software. The owners and maintainers of were merely meager employees of the aforementioned organization, providing this site out of the pure goodness of their collective hearts. Logo

Last updated: July 22, 2003.