TRORemoteDataModule

Overview

The TRORemoteDataModule base class for all RO SDK and Data Abstract services is one of the most important classes in the RO SDK library. When a new project or service is created, the IDE wizard prompts for the new service object ancestor. If the Remoting SDK Remote Datamodule is selected, the wizard creates this class descendant for the new service. All custom service methods are implemented as protected methods of this new class.
This class is intended to be subclassed and never used as is. As a rule, instances of the TRORemoteDataModule sublasses are created during the remote method execution process.
There are many important protected methods that should be overridden or called from the service code during remote method execution, so it is advised to read this class description thoroughly.

Location


 

constructor Create  override

Standard component constructor

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

AllowRemoteEventsRegistration  protected

Obsolete, replaced by the LegacyEvents property.

function AllowRemoteEventsRegistration: Boolean

Assign  override

Copies data from a given source.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

ClientID

The unique identifier for the client connected to the service. It is equal to the session ID if the session already exists. When the service method is called, this property is already initialized with a proper value. Do not change it unless you know what you are doing!

property ClientID: TGUID read write

CreateSession

Creates a new session object and makes it available via the Session property. As a rule, there is no need to call this method because the session is created automatically when required.

procedure CreateSession

CustomRequireSession  protected virtual

Internal use only, don't override.

function CustomRequireSession(const aMessage: IROMessage): Boolean

Parameters:

  • aMessage: Message

DestroySession

Destroys the current session object. This method is primarily used to destroy the session in case of unsuccessful client authentication.

procedure DestroySession

EventRepository

Points to the event repository (TROEventRepository instance) for the service. The value must be set to use the events feature.

property EventRepository: TROEventRepository read write

GetDispatchInfo  protected virtual

Allows to grab the input parameters to get all information about the upcoming call including the remote method parameters and the calling client transport object.

procedure GetDispatchInfo(const aTransport: IROTransport; const aMessage: IROMessage)

Parameters:

  • aTransport: Points to the transport object containing connection-specific information
  • aMessage: Message that needs to be processed

GetEventsData  protected

Collects events data to the memory stream. For internal use only, don't call or override.

function GetEventsData(const ClientID: string; out EventsData: Binary): Integer

Parameters:

  • ClientID: Client ID
  • EventsData: Binary stream that holds the event data

IsRetained  protected

Returns true if anObject is retained by Self.

function IsRetained(const anObject: TObject): Boolean

Parameters:

  • anObject: Object to check

IsSessionPresent

Checks if session is present

function IsSessionPresent: Boolean

LegacyEvents

Enables or disables the legacy events mode for the service. The default value is true. The legacy mode is less secure and it is recommended to set this property to false for new projects. Note that refusing to use the legacy mode will break compatibility with legacy Delphi clients.

property LegacyEvents: Boolean read write

NewSession

Indicates that the client's session was just created, i.e. this indicates the first connection of a so far unknown client.

property NewSession: Boolean read

OnActivate

Called just after the service is created and before any service method is called. Handle this event for everything you need to do when the service instance is created.

property OnActivate: TActivateEvent read write
delegate: procedure OnActivate(const aClientID: TGUID; aSession: TROSession; const aMessage: IROMessage)

OnBeforeRegisterEventClient

Called when the new client is being registered to receive events. Deprecated now, since remote event (un-)registration is forbidden (LegacyEvents = false).

property OnBeforeRegisterEventClient: TRegisterEventClientEvent read write
delegate: procedure OnBeforeRegisterEventClient(const aClientID: TGUID; const EventTypes: string)

OnBeforeUnregisterEventClient

Called when the client is being unsubscribed from events. Deprecated now, since remote event (un-)registration is forbidden (LegacyEvents = false).

property OnBeforeUnregisterEventClient: TRegisterEventClientEvent read write
delegate: procedure OnBeforeUnregisterEventClient(const aClientID: TGUID; const EventTypes: string)

OnDeactivate

Called after the service method completes and before the service instance is freed. Handle this event to perform actions on service destruction, such as disposing of resources.

property OnDeactivate: TDeactivateEvent read write
delegate: procedure OnDeactivate(const aClientID: TGUID; aSession: TROSession)

OnGetDispatchInfo

This event is fired before the invoker executes the service method. Handle this event to preview remote methods about to be executed; the input parameters allow to get all information about the upcoming call including the remote method parameters and the calling client transport object.

property OnGetDispatchInfo: TGetDispatchInfoEvent read write
delegate: procedure OnGetDispatchInfo(const aTransport: IROTransport; const aMessage: IROMessage)

OnValidateRoles

Validates roles.

property OnValidateRoles: TValidateRolesEvent read write
delegate: procedure OnValidateRoles(aRoles: array of string; var aAllow: Boolean)

RefCount

Reference counter - this class is the interfaced object.

property RefCount: Integer read

RegisterEventClient (TROSession, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const aSession: TROSession; const EventTypes: string)

Parameters:

  • aSession: Client session
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

RegisterEventClient (string, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const ClientID: string; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to subscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

RegisterEventClient (TGUID, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const ClientID: TGUID; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to subscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

ReleaseObject  protected

Takes away the hold of anObject set by RetainObject.

procedure ReleaseObject(const anObject: TObject)

Parameters:

  • anObject: Object to release

RequiresSession

This property should be set to true (perhaps with the designer) to make the service protected and to disallow unauthenticated clients to call its methods. Read more.

property RequiresSession: Boolean read write

RetainObject  protected

Sets the hold of anObject.

procedure RetainObject(const anObject: TObject)

Parameters:

  • anObject: Object to hold

ServiceValidateRoles  protected

Validates roles.

procedure ServiceValidateRoles(aRequiredRoles: array of string)

Parameters:

  • aRequiredRoles: Roles

Session

Provides access to the session object of the current connection. If the session does not exist, it is created at the moment of property access.

property Session: TROSession read

SessionManager

Points to the session manager to use. It is necessary to assign the session manager if the protected service is being developed and/or it is necessary to use the events feature.

property SessionManager: TROCustomSessionManager read write

Synchronize  protected

procedure Synchronize(aMethod: TThreadMethod)

Parameters:

  • aMethod:

Transport

Provides access to the transport object that processes the current network (or other) connection to the server. Various information, such as client IP address, can be available via the transport objects.

property Transport: IROTransport read

UnregisterEventClient (TROSession, string)  protected overload

procedure UnregisterEventClient(const aSession: TROSession; const EventTypes: string)

Parameters:

  • aSession:
  • EventTypes:

UnregisterEventClient (string, string)  protected overload

The action is opposite to RegisterEventClient, it cancels the subscription. Unregistration is not absolutely necessary as the client session dies after some time of inactivity but allows to conserve some system resources.

procedure UnregisterEventClient(const ClientID: string; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to unsubscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to unsubscribe the client from.

UnregisterEventClient (TGUID, string)  protected overload

procedure UnregisterEventClient(const ClientID: TGUID; const EventTypes: string)

Parameters:

  • ClientID:
  • EventTypes:

 

ClientID

The unique identifier for the client connected to the service. It is equal to the session ID if the session already exists. When the service method is called, this property is already initialized with a proper value. Do not change it unless you know what you are doing!

property ClientID: TGUID read write

EventRepository

Points to the event repository (TROEventRepository instance) for the service. The value must be set to use the events feature.

property EventRepository: TROEventRepository read write

LegacyEvents

Enables or disables the legacy events mode for the service. The default value is true. The legacy mode is less secure and it is recommended to set this property to false for new projects. Note that refusing to use the legacy mode will break compatibility with legacy Delphi clients.

property LegacyEvents: Boolean read write

NewSession

Indicates that the client's session was just created, i.e. this indicates the first connection of a so far unknown client.

property NewSession: Boolean read

RefCount

Reference counter - this class is the interfaced object.

property RefCount: Integer read

RequiresSession

This property should be set to true (perhaps with the designer) to make the service protected and to disallow unauthenticated clients to call its methods. Read more.

property RequiresSession: Boolean read write

Session

Provides access to the session object of the current connection. If the session does not exist, it is created at the moment of property access.

property Session: TROSession read

SessionManager

Points to the session manager to use. It is necessary to assign the session manager if the protected service is being developed and/or it is necessary to use the events feature.

property SessionManager: TROCustomSessionManager read write

Transport

Provides access to the transport object that processes the current network (or other) connection to the server. Various information, such as client IP address, can be available via the transport objects.

property Transport: IROTransport read

 

constructor Create  override

Standard component constructor

constructor Create(aOwner: TComponent)

Parameters:

  • aOwner: Owner.

AllowRemoteEventsRegistration  protected

Obsolete, replaced by the LegacyEvents property.

function AllowRemoteEventsRegistration: Boolean

Assign  override

Copies data from a given source.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CreateSession

Creates a new session object and makes it available via the Session property. As a rule, there is no need to call this method because the session is created automatically when required.

procedure CreateSession

CustomRequireSession  protected virtual

Internal use only, don't override.

function CustomRequireSession(const aMessage: IROMessage): Boolean

Parameters:

  • aMessage: Message

DestroySession

Destroys the current session object. This method is primarily used to destroy the session in case of unsuccessful client authentication.

procedure DestroySession

GetDispatchInfo  protected virtual

Allows to grab the input parameters to get all information about the upcoming call including the remote method parameters and the calling client transport object.

procedure GetDispatchInfo(const aTransport: IROTransport; const aMessage: IROMessage)

Parameters:

  • aTransport: Points to the transport object containing connection-specific information
  • aMessage: Message that needs to be processed

GetEventsData  protected

Collects events data to the memory stream. For internal use only, don't call or override.

function GetEventsData(const ClientID: string; out EventsData: Binary): Integer

Parameters:

  • ClientID: Client ID
  • EventsData: Binary stream that holds the event data

IsRetained  protected

Returns true if anObject is retained by Self.

function IsRetained(const anObject: TObject): Boolean

Parameters:

  • anObject: Object to check

IsSessionPresent

Checks if session is present

function IsSessionPresent: Boolean

RegisterEventClient (TROSession, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const aSession: TROSession; const EventTypes: string)

Parameters:

  • aSession: Client session
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

RegisterEventClient (string, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const ClientID: string; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to subscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

RegisterEventClient (TGUID, string)  protected overload

Registers the client to receive server callback events of the specified type.

procedure RegisterEventClient(const ClientID: TGUID; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to subscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to subscribe the client to.

ReleaseObject  protected

Takes away the hold of anObject set by RetainObject.

procedure ReleaseObject(const anObject: TObject)

Parameters:

  • anObject: Object to release

RetainObject  protected

Sets the hold of anObject.

procedure RetainObject(const anObject: TObject)

Parameters:

  • anObject: Object to hold

ServiceValidateRoles  protected

Validates roles.

procedure ServiceValidateRoles(aRequiredRoles: array of string)

Parameters:

  • aRequiredRoles: Roles

Synchronize  protected

procedure Synchronize(aMethod: TThreadMethod)

Parameters:

  • aMethod:

UnregisterEventClient (TROSession, string)  protected overload

procedure UnregisterEventClient(const aSession: TROSession; const EventTypes: string)

Parameters:

  • aSession:
  • EventTypes:

UnregisterEventClient (string, string)  protected overload

The action is opposite to RegisterEventClient, it cancels the subscription. Unregistration is not absolutely necessary as the client session dies after some time of inactivity but allows to conserve some system resources.

procedure UnregisterEventClient(const ClientID: string; const EventTypes: string)

Parameters:

  • ClientID: Client identifier to unsubscribe
  • EventTypes: Identifier (GUID) of the event sink containing the events to unsubscribe the client from.

UnregisterEventClient (TGUID, string)  protected overload

procedure UnregisterEventClient(const ClientID: TGUID; const EventTypes: string)

Parameters:

  • ClientID:
  • EventTypes:

 

OnActivate

Called just after the service is created and before any service method is called. Handle this event for everything you need to do when the service instance is created.

property OnActivate: TActivateEvent read write
delegate: procedure OnActivate(const aClientID: TGUID; aSession: TROSession; const aMessage: IROMessage)

OnBeforeRegisterEventClient

Called when the new client is being registered to receive events. Deprecated now, since remote event (un-)registration is forbidden (LegacyEvents = false).

property OnBeforeRegisterEventClient: TRegisterEventClientEvent read write
delegate: procedure OnBeforeRegisterEventClient(const aClientID: TGUID; const EventTypes: string)

OnBeforeUnregisterEventClient

Called when the client is being unsubscribed from events. Deprecated now, since remote event (un-)registration is forbidden (LegacyEvents = false).

property OnBeforeUnregisterEventClient: TRegisterEventClientEvent read write
delegate: procedure OnBeforeUnregisterEventClient(const aClientID: TGUID; const EventTypes: string)

OnDeactivate

Called after the service method completes and before the service instance is freed. Handle this event to perform actions on service destruction, such as disposing of resources.

property OnDeactivate: TDeactivateEvent read write
delegate: procedure OnDeactivate(const aClientID: TGUID; aSession: TROSession)

OnGetDispatchInfo

This event is fired before the invoker executes the service method. Handle this event to preview remote methods about to be executed; the input parameters allow to get all information about the upcoming call including the remote method parameters and the calling client transport object.

property OnGetDispatchInfo: TGetDispatchInfoEvent read write
delegate: procedure OnGetDispatchInfo(const aTransport: IROTransport; const aMessage: IROMessage)

OnValidateRoles

Validates roles.

property OnValidateRoles: TValidateRolesEvent read write
delegate: procedure OnValidateRoles(aRoles: array of string; var aAllow: Boolean)