TROEventReceiver

Overview

The Event Receiver component is used on the client to enable receiving callback events from the server.

Depending on the channel type, this will be done by regularly polling the server for new events or, if the Channel supports active sending of events, by simply awaiting events to be sent from the server.

Location

Implements

 

constructor Create  override

Creates a new instance.

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

Activate

Activates and will start receiving events.

procedure Activate

Active

Specifies whether the event receiver is currently processing events (true), or not (false).

This property must be set to true before any actual event processing will occur.

property Active: boolean read write

AreEventHandlersRegistered

Checks whether the passed event handlers are currently registered.

function AreEventHandlersRegistered(const aEventIDs: array of string; const aEventHandlers: array of TObject): boolean

Parameters:

  • aEventIDs: array of strings with names event syncs, they are defined in _Intf file.
  • aEventHandlers: An array of objects that will be registered to receive the events. Each of the objects must implement the respective event sink interfaces defined in your _Intf unit.

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

Channel

The channel to be used for receiving events. Unless the channel type is explicitly designed for consecutive requests (such as the Super TCP Channel), it is recommended that you use a different channel instance from the one used for your regular communication.

property Channel:

CheckProperties

Validates the event receiver properties.

procedure CheckProperties(CheckServiceName: boolean)

Parameters:

  • CheckServiceName: Validate ServiceName or not

ClientID

The unique identifier for the client connected to the service.

property ClientID: TGUID read write

Deactivate

Deactivates and will stop receiving events.

procedure Deactivate

Dispatch  protected reintroduce

This method is called whenever the client channel receives an event from the server. If your client channel supports the IROActiveEventChannel interface, you will receive only one event at a time and the aStream parameter will hold the IROMessage data, otherwise aStream may contain multiple events data.

procedure Dispatch(aStream: TStream; aCaller: TThread)

Parameters:

  • aStream: Stream that contains the event data
  • aCaller: Thread that calls this method

EventHandlersIsRegistered  deprecated

Checks if event handlers are already registered

function EventHandlersIsRegistered(const EventIDs: array of string; const EventHandlers: array of TObject): boolean

Parameters:

  • EventIDs: array of strings with names event syncs, they are defined in _Intf file.
  • EventHandlers: An array of objects that will be registered to receive the events. Each of the objects must implement the respective event sink interfaces defined in your _Intf unit.

FireEvents  protected virtual

procedure FireEvents(EventsDataStream: TStream)

Parameters:

  • EventsDataStream:

GetObject  protected

Returns self.

function GetObject: TObject

Interval

The interval, in milliseconds, at which the receiver will poll for new events. Default is 30,000 (30 seconds).

property Interval: integer read write

Invoke_GetEventsData  protected

This method is used to acquire events data from the server. It is used if the client channel does not support the IROActiveEventChannel and cannot notify the TROEventReceiver about incoming events data itself, in this case, TROEventReceiver calls this method in a background thread to obtain events from the server. When this method receives new events, it stores them in the EventsData stream and returns the received events count.

function Invoke_GetEventsData(out EventsData: TROBinaryMemoryStream): Integer

Parameters:

  • EventsData: Binary stream that holds the event data

Invoke_RegisterEventClient  protected

Notifies the server that the client can handle event types specified by the EventTypes parameter.

procedure Invoke_RegisterEventClient(const EventTypes: string)

Parameters:

  • EventTypes: Holds a comma-separated list of event types that the client can recieve from the server.

Invoke_UnregisterEventClient  protected

Notifies the server that the client cannot receive events with the specified types any more.

procedure Invoke_UnregisterEventClient(const EventTypes: string)

Parameters:

  • EventTypes: Holds a comma-separated list of event types that the client cannot recieve from the server anymore.

IsEventHandlerRegistered

Checks whether the passed event handler is currently registered.

function IsEventHandlerRegistered(const aEventID: string; const aEventHandler: TObject): boolean

Parameters:

  • aEventID: Event
  • aEventHandler: Event handler

IsRetained

Returns true if anObject is retained by Self.

function IsRetained(const anObject: TObject): boolean

Parameters:

  • anObject: Object to check

LegacyEvents

Enables or disables legacy events mode for the receiver. Default is true. Legacy mode is less secure and is not compatible with .NET servers. It is recommended to set this property to false for new projects.

property LegacyEvents: Boolean read write

MaximumMessagesPerPoll

property MaximumMessagesPerPoll: word read write

Message

The message format used to decode the events received. Because events are handled based on the ClientID stored in the message, it is recommended to assign the same message that you are also using for your regular communication or to manually sync the ClientID between the two messages.

property Message:

OnActivate

Fired when the event receiver has been activated and will start receiving events.

property OnActivate: TNotifyEvent read write

OnDeactivate

Fired when the event receiver has been deactivated and will stop receiving events.

property OnDeactivate: TNotifyEvent read write

OnPollException

Fired when the event receiver has encountered an error while polling for events.

Because event polling happens in a background thread, exceptions that occur during polling will not automatically bubble up to the main application and show an exception dialog. As such, it is important to handle this event of the Event Receiver in order to be notified of any problems that might arise during event polling.

property OnPollException: TROOnEventExceptionEvent read write
delegate: procedure OnPollException(Sender: TObject; anException: Exception)

OnTimerTick

procedure OnTimerTick(Dummy: Cardinal)

Parameters:

  • Dummy:

RegisterEventHandler

Registers on the server class which implements an event handler for a particular event sink on the client.

procedure RegisterEventHandler(const EventID: string; const EventHandler: TObject)

Parameters:

  • EventID: string wich names event sync, it is defined in _Intf file.
  • EventHandler: class which implements event sync interface.

RegisterEventHandlers (array of string, array of TObject)  overload

Registers on the server array of classes which implements an event handlers for a particular event sinks on the client.

procedure RegisterEventHandlers(const EventIDs: array of string; const EventHandlers: array of TObject)

Parameters:

  • EventIDs: An array of strings containing the IDs of the events you want to subscribe to. Event ID constants are generated in the Intf unit of your library for each defined Event Sink, and start with EID.
  • EventHandlers: array of classes which implements event syncs interfaces.

ReleaseObject

Takes away the hold of anObject set by RetainObject.

procedure ReleaseObject(const anObject: TObject)

Parameters:

  • anObject: Object to release

RetainObject

Sets the hold of anObject.

procedure RetainObject(const anObject: TObject)

Parameters:

  • anObject: Object to hold

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned RO components.

procedure ROFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Disables destruction notification for specified RO component.

procedure RORemoveFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

ServersideRegisterEvents

property ServersideRegisterEvents: Boolean read write

ServiceName

The name of the Service from where events are to be received.

property ServiceName: string read write

SynchronizeInvoke

Whether events will be fired in the context of the main VCL thread (true, default) or not (false). By default, the Event Receiver will synchronize all events back to the main VCL thread, which makes it safe to access the user interface from your event handler code.

If UI access is not needed, and your event handlers are implemented in a thread-safe fashion, you can disable this property to gain performance by having events fire in the thread where they were received. Also, if you are performing lengthy operations in your event handlers, your UI might freeze while event handlers execute and block the main VCL thread (which is responsible for user interaction); disable this property to avoid that.

property SynchronizeInvoke: Boolean read write

UnregisterEventHandler (string)  overload

Used to unregister an event handler previously registered via RegisterEventHandlers.

procedure UnregisterEventHandler(const EventIDs: string)

Parameters:

  • EventIDs: name of event sync

UnregisterEventHandler (string, TObject)  overload

procedure UnregisterEventHandler(const anEventID: string; const anEventHandler: TObject)

Parameters:

  • anEventID:
  • anEventHandler:

UnregisterEventHandler (TObject)  overload

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandler(const EventHandler: TObject)

Parameters:

  • EventHandler: An object that was registered to receive the events.

UnregisterEventHandlers (array of string)  overload

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandlers(const EventIDs: array of string)

Parameters:

  • EventIDs: array of strings with names event syncs, they are defined in _Intf file.

UnregisterEventHandlersByObject

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandlersByObject(const EventHandler: array of TObject)

Parameters:

  • EventHandler: An array of objects that were registered to receive the events.

 

Active

Specifies whether the event receiver is currently processing events (true), or not (false).

This property must be set to true before any actual event processing will occur.

property Active: boolean read write

Channel

The channel to be used for receiving events. Unless the channel type is explicitly designed for consecutive requests (such as the Super TCP Channel), it is recommended that you use a different channel instance from the one used for your regular communication.

property Channel:

ClientID

The unique identifier for the client connected to the service.

property ClientID: TGUID read write

Interval

The interval, in milliseconds, at which the receiver will poll for new events. Default is 30,000 (30 seconds).

property Interval: integer read write

LegacyEvents

Enables or disables legacy events mode for the receiver. Default is true. Legacy mode is less secure and is not compatible with .NET servers. It is recommended to set this property to false for new projects.

property LegacyEvents: Boolean read write

MaximumMessagesPerPoll

property MaximumMessagesPerPoll: word read write

Message

The message format used to decode the events received. Because events are handled based on the ClientID stored in the message, it is recommended to assign the same message that you are also using for your regular communication or to manually sync the ClientID between the two messages.

property Message:

ServersideRegisterEvents

property ServersideRegisterEvents: Boolean read write

ServiceName

The name of the Service from where events are to be received.

property ServiceName: string read write

SynchronizeInvoke

Whether events will be fired in the context of the main VCL thread (true, default) or not (false). By default, the Event Receiver will synchronize all events back to the main VCL thread, which makes it safe to access the user interface from your event handler code.

If UI access is not needed, and your event handlers are implemented in a thread-safe fashion, you can disable this property to gain performance by having events fire in the thread where they were received. Also, if you are performing lengthy operations in your event handlers, your UI might freeze while event handlers execute and block the main VCL thread (which is responsible for user interaction); disable this property to avoid that.

property SynchronizeInvoke: Boolean read write

 

constructor Create  override

Creates a new instance.

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

Activate

Activates and will start receiving events.

procedure Activate

AreEventHandlersRegistered

Checks whether the passed event handlers are currently registered.

function AreEventHandlersRegistered(const aEventIDs: array of string; const aEventHandlers: array of TObject): boolean

Parameters:

  • aEventIDs: array of strings with names event syncs, they are defined in _Intf file.
  • aEventHandlers: An array of objects that will be registered to receive the events. Each of the objects must implement the respective event sink interfaces defined in your _Intf unit.

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CheckProperties

Validates the event receiver properties.

procedure CheckProperties(CheckServiceName: boolean)

Parameters:

  • CheckServiceName: Validate ServiceName or not

Deactivate

Deactivates and will stop receiving events.

procedure Deactivate

Dispatch  protected reintroduce

This method is called whenever the client channel receives an event from the server. If your client channel supports the IROActiveEventChannel interface, you will receive only one event at a time and the aStream parameter will hold the IROMessage data, otherwise aStream may contain multiple events data.

procedure Dispatch(aStream: TStream; aCaller: TThread)

Parameters:

  • aStream: Stream that contains the event data
  • aCaller: Thread that calls this method

EventHandlersIsRegistered  deprecated

Checks if event handlers are already registered

function EventHandlersIsRegistered(const EventIDs: array of string; const EventHandlers: array of TObject): boolean

Parameters:

  • EventIDs: array of strings with names event syncs, they are defined in _Intf file.
  • EventHandlers: An array of objects that will be registered to receive the events. Each of the objects must implement the respective event sink interfaces defined in your _Intf unit.

FireEvents  protected virtual

procedure FireEvents(EventsDataStream: TStream)

Parameters:

  • EventsDataStream:

GetObject  protected

Returns self.

function GetObject: TObject

Invoke_GetEventsData  protected

This method is used to acquire events data from the server. It is used if the client channel does not support the IROActiveEventChannel and cannot notify the TROEventReceiver about incoming events data itself, in this case, TROEventReceiver calls this method in a background thread to obtain events from the server. When this method receives new events, it stores them in the EventsData stream and returns the received events count.

function Invoke_GetEventsData(out EventsData: TROBinaryMemoryStream): Integer

Parameters:

  • EventsData: Binary stream that holds the event data

Invoke_RegisterEventClient  protected

Notifies the server that the client can handle event types specified by the EventTypes parameter.

procedure Invoke_RegisterEventClient(const EventTypes: string)

Parameters:

  • EventTypes: Holds a comma-separated list of event types that the client can recieve from the server.

Invoke_UnregisterEventClient  protected

Notifies the server that the client cannot receive events with the specified types any more.

procedure Invoke_UnregisterEventClient(const EventTypes: string)

Parameters:

  • EventTypes: Holds a comma-separated list of event types that the client cannot recieve from the server anymore.

IsEventHandlerRegistered

Checks whether the passed event handler is currently registered.

function IsEventHandlerRegistered(const aEventID: string; const aEventHandler: TObject): boolean

Parameters:

  • aEventID: Event
  • aEventHandler: Event handler

IsRetained

Returns true if anObject is retained by Self.

function IsRetained(const anObject: TObject): boolean

Parameters:

  • anObject: Object to check

OnTimerTick

procedure OnTimerTick(Dummy: Cardinal)

Parameters:

  • Dummy:

RegisterEventHandler

Registers on the server class which implements an event handler for a particular event sink on the client.

procedure RegisterEventHandler(const EventID: string; const EventHandler: TObject)

Parameters:

  • EventID: string wich names event sync, it is defined in _Intf file.
  • EventHandler: class which implements event sync interface.

RegisterEventHandlers (array of string, array of TObject)  overload

Registers on the server array of classes which implements an event handlers for a particular event sinks on the client.

procedure RegisterEventHandlers(const EventIDs: array of string; const EventHandlers: array of TObject)

Parameters:

  • EventIDs: An array of strings containing the IDs of the events you want to subscribe to. Event ID constants are generated in the Intf unit of your library for each defined Event Sink, and start with EID.
  • EventHandlers: array of classes which implements event syncs interfaces.

ReleaseObject

Takes away the hold of anObject set by RetainObject.

procedure ReleaseObject(const anObject: TObject)

Parameters:

  • anObject: Object to release

RetainObject

Sets the hold of anObject.

procedure RetainObject(const anObject: TObject)

Parameters:

  • anObject: Object to hold

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned RO components.

procedure ROFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Disables destruction notification for specified RO component.

procedure RORemoveFreeNotification(AComponent: TComponent)

Parameters:

  • AComponent: component

UnregisterEventHandler (string)  overload

Used to unregister an event handler previously registered via RegisterEventHandlers.

procedure UnregisterEventHandler(const EventIDs: string)

Parameters:

  • EventIDs: name of event sync

UnregisterEventHandler (string, TObject)  overload

procedure UnregisterEventHandler(const anEventID: string; const anEventHandler: TObject)

Parameters:

  • anEventID:
  • anEventHandler:

UnregisterEventHandler (TObject)  overload

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandler(const EventHandler: TObject)

Parameters:

  • EventHandler: An object that was registered to receive the events.

UnregisterEventHandlers (array of string)  overload

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandlers(const EventIDs: array of string)

Parameters:

  • EventIDs: array of strings with names event syncs, they are defined in _Intf file.

UnregisterEventHandlersByObject

Used to unregister one or more event handlers previously registered via RegisterEventHandlers.

procedure UnregisterEventHandlersByObject(const EventHandler: array of TObject)

Parameters:

  • EventHandler: An array of objects that were registered to receive the events.

 

OnActivate

Fired when the event receiver has been activated and will start receiving events.

property OnActivate: TNotifyEvent read write

OnDeactivate

Fired when the event receiver has been deactivated and will stop receiving events.

property OnDeactivate: TNotifyEvent read write

OnPollException

Fired when the event receiver has encountered an error while polling for events.

Because event polling happens in a background thread, exceptions that occur during polling will not automatically bubble up to the main application and show an exception dialog. As such, it is important to handle this event of the Event Receiver in order to be notified of any problems that might arise during event polling.

property OnPollException: TROOnEventExceptionEvent read write
delegate: procedure OnPollException(Sender: TObject; anException: Exception)

See Also