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


 

constructor Create  override

Standard component constructor

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

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

function AreEventHandlersRegistered(const anEventIDs: array of string; const anEventHandlers: array of TObject): Boolean

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: array of classes which implements event syncs interfaces.

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

AsyncPolling

property AsyncPolling: 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: TROTransportChannel read write

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

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

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

function EventHandlersIsRegistered(const anEventIDs: array of string; const anEventHandlers: array of TObject): Boolean

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: array of classes which implements event syncs interfaces.

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

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

function IsEventHandlerRegistered(const anEventID: string; const anEventHandler: TObject): Boolean

Parameters:

  • anEventID: 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.
  • anEventHandler: array of classes which implements event syncs interfaces.

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: TROMessage read write

Notification  protected override    (declared in TROChannelAwareComponent)

Forwards notification messages to all owned components.

procedure Notification(AComponent: TComponent; Operation: TOperation)

Parameters:

  • AComponent: component
  • Operation: operation

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

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

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

Parameters:

  • anEventID: 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.
  • anEventHandler: array of classes which implements event syncs interfaces.

RegisterEventHandlers (array of string, array of TObject)  overload

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

procedure RegisterEventHandlers(const anEventIDs: array of string; const anEventHandlers: array of TObject)

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: 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 components.

procedure ROFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure RORemoveFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

SendRemoveNotification  protected    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure SendRemoveNotification(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 (TObject)  overload

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

procedure UnregisterEventHandler(const anEventHandler: TObject)

Parameters:

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

UnregisterEventHandler (string, TObject)  overload

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

Parameters:

  • anEventID:
  • anEventHandler:

UnregisterEventHandler (string)  overload

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

procedure UnregisterEventHandler(const anEventIDs: string)

Parameters:

  • anEventIDs: An array of objects that were 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 anEventIDs: array of string)

Parameters:

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

UnregisterEventHandlersByObject

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

procedure UnregisterEventHandlersByObject(const anEventHandlers: array of TObject)

Parameters:

  • anEventHandlers: 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

AsyncPolling

property AsyncPolling: 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: TROTransportChannel read write

ClientID

The unique identifier for the client connected to the service.

property ClientID: TGUID read

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: TROMessage read write

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

Standard component constructor

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner

Activate

Activates and will start receiving events.

procedure Activate

AreEventHandlersRegistered

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

function AreEventHandlersRegistered(const anEventIDs: array of string; const anEventHandlers: array of TObject): Boolean

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: array of classes which implements event syncs interfaces.

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

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

function EventHandlersIsRegistered(const anEventIDs: array of string; const anEventHandlers: array of TObject): Boolean

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: array of classes which implements event syncs interfaces.

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

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

function IsEventHandlerRegistered(const anEventID: string; const anEventHandler: TObject): Boolean

Parameters:

  • anEventID: 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.
  • anEventHandler: array of classes which implements event syncs interfaces.

IsRetained

Returns true if anObject is retained by Self.

function IsRetained(const anObject: TObject): Boolean

Parameters:

  • anObject: Object to check

Notification  protected override    (declared in TROChannelAwareComponent)

Forwards notification messages to all owned components.

procedure Notification(AComponent: TComponent; Operation: TOperation)

Parameters:

  • AComponent: component
  • Operation: operation

OnTimerTick

procedure OnTimerTick(Dummy: Cardinal)

Parameters:

  • Dummy:

RegisterEventHandler

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

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

Parameters:

  • anEventID: 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.
  • anEventHandler: array of classes which implements event syncs interfaces.

RegisterEventHandlers (array of string, array of TObject)  overload

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

procedure RegisterEventHandlers(const anEventIDs: array of string; const anEventHandlers: array of TObject)

Parameters:

  • anEventIDs: 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.
  • anEventHandlers: 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 components.

procedure ROFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure RORemoveFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

SendRemoveNotification  protected    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure SendRemoveNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

UnregisterEventHandler (TObject)  overload

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

procedure UnregisterEventHandler(const anEventHandler: TObject)

Parameters:

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

UnregisterEventHandler (string, TObject)  overload

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

Parameters:

  • anEventID:
  • anEventHandler:

UnregisterEventHandler (string)  overload

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

procedure UnregisterEventHandler(const anEventIDs: string)

Parameters:

  • anEventIDs: An array of objects that were 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 anEventIDs: array of string)

Parameters:

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

UnregisterEventHandlersByObject

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

procedure UnregisterEventHandlersByObject(const anEventHandlers: array of TObject)

Parameters:

  • anEventHandlers: 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)