TApxComPort.OnTriggerAvail

TApxComPort

property OnTriggerAvail : TTriggerAvailEvent
TTriggerAvailEvent = procedure(
  CP : TObject; Count : Word) of object;

Defines an event handler that is called whenever a certain amount of serial input data is available for processing.

This event is generated when data has been transferred into the dispatcher buffer.

CP is the TApxComPort component that generated the trigger. Count is the actual number of bytes that are available to read at the instant the event is generated. Your event handler should process exactly Count bytes of input (by calling GetChar or GetBlock). It should not use CharReady in a loop to process all available bytes since additional bytes may have transferred into the buffer while the event handler is active, and removing those bytes could interfere with the dispatcher's data tracking mechanism.

If several parts of the same application are using the same comport component and each part installs its own OnTriggerAvail handler (as would occur if a terminal window and a file transfer protocol were both in use), the Async Professional CLX dispatcher takes pains to ensure that all of them can read the same data. Even if the first handler to get control calls GetChar to read Count bytes of data, the second and subsequent handlers will also be able to read the same bytes of data by calling GetChar. After all of the OnTriggerAvail handlers have returned, the dispatcher determines the largest number of characters read by any of the handlers and removes those characters from the dispatcher buffer. If any data remains in the buffer, the dispatcher immediately generates another OnTriggerAvail event. Hence, if one handler reads fewer characters than the other handlers, it will miss seeing the characters it did not read on its first opportunity.

Caution: Be sure to process the exact number of bytes passed in the Count parameter of this handler. If you process fewer bytes, you risk losing characters to another component extracting data during the event (such as the terminal). If you process more than Count bytes, you risk receiving events for overlapping data—which may eventually lead to an EBufferIsEmpty exception.The following example collects incoming data until it finds a carriage return character (ASCII 13). If the incoming data stream contained "TurboPower Software", ApxComPortTriggerAvail would be called one or more times until the entire string except was received. ApxComPortTriggerData would then be called and could process the complete string. ApxComPortTriggerAvail would then be called again with the and any other data that followed it. ApxComPortTriggerData would not be called again in this example, because the handler disables the data trigger.

const
  S : string = '';
...
  CRTrig := ApxComPort.AddDataTrigger(#13, False);
...
procedure TMyForm.ApxComPortTriggerData(
  CP : TObject; TriggerHandle : Word);
begin
  if TriggerHandle = CRTrig then begin
    ...do something with S
    ApxComPort.RemoveTrigger(TriggerHandle);
  end;
end;
procedure TMyForm.ApxComPortTriggerAvail(
  CP : TObject; Count : Word);
var
  I : Word;
begin
  for I := 1 to Count do
    S := S + ApxComPort.GetChar;
end;

See also: OnTrigger, OnTriggerData