RemoteViz::Rendering::ServiceListener Class Reference

More...

#include <RemoteViz/Rendering/ServiceListener.h>

Public Member Functions
virtual	~ServiceListener ()
	Destructor.
virtual bool	onPendingCreateRenderArea (const std::string &renderAreaId, unsigned int &width, unsigned int &height, std::shared_ptr< RenderAreaHardware > renderAreaHardware, std::shared_ptr< Client > client, std::shared_ptr< const ConnectionParameters > parameters)
	Triggered when a connection is pending and the requested renderArea does not exist.
virtual bool	onPendingShareRenderArea (std::shared_ptr< RenderArea > renderArea, std::shared_ptr< Client > client, std::shared_ptr< const ConnectionParameters > parameters)
	Triggered when a connection is pending and the requested renderArea exists.
virtual void	onInstantiatedRenderArea (std::shared_ptr< RenderArea > renderArea)
	Triggered when a renderArea has been instantiated.
virtual void	onDisposingRenderArea (std::shared_ptr< RenderArea > renderArea)
	Triggered before a renderArea is disposed.
virtual void	onDisposedRenderArea (const std::string &renderAreaId)
	Triggered when a renderArea has been disposed.
virtual void	onConnectedClient (const std::string &clientId, std::shared_ptr< NetworkPerformance > networkPerformance)
	Triggered when a client is connected to the service.
virtual void	onInitializedClient (std::shared_ptr< Client > client, std::shared_ptr< const NetworkPerformance > networkPerformance)
	Triggered when a client is initialized.
virtual void	onDisconnectedClient (const std::string &clientId)
	Triggered when a client is disconnected from the service.
virtual std::string	onRequestedPrivateKeyPassphrase ()
	Triggered when the secure connection is enabled.
virtual HTTPResponse	onHTTPRequest (std::shared_ptr< const HTTPRequest > httpRequest)
	Triggered when an HTTP connection is made that does not attempt to upgrade the connection to the WebSocket protocol.
Deprecated
virtual SoDEPRECATED void	onMissingLicense (const std::string &renderAreaId, std::shared_ptr< const ConnectionParameters > parameters)
	This listener is deprecated from Open Inventor 10.9 and is not triggered by RemoteViz anymore.

Detailed Description

This class can be overridden by an application to receive notifications from the rendering Service.

A typical sequence of calls to this listener is:

• onConnectedClient
  Client object has been created (isConnected will return true)
• onPendingCreateRenderArea
  RenderArea object is about to be created
• onInstantiatedRenderArea
  RenderArea object has been created (isDisposed will return false)
• onInitializedClient
  Client is running and bandwidth calibration has finished
  
  Application is running...
  
  
• onDisposingRenderArea
  RenderArea object will be disposed
• onDisposedRenderArea
  RenderArea object has been disposed (isDisposed will return true)
• onDisconnectedClient
  Client object has been disposed (isConnected will return false)

Since RemoteViz 10.6, this class also allows the Service to respond to standard HTTP requests using standard HTTP response codes (and messages). This can be useful, for example, to respond to "health check" requests. This method is not suitable to serve high volume requests or HTTP resources, in these cases, prefer a dedicated HTTP server like Apache or Nginx. See onHTTPRequest().

Typically the application will attach a listener to the Service instance before calling the Service's open() method.

For notifications about connections, rendering, input events and client messages see the RenderAreaListener class.

Definition at line 89 of file ServiceListener.h.

Constructor & Destructor Documentation

~ServiceListener()

virtual RemoteViz::Rendering::ServiceListener::~ServiceListener ( )

virtual

Destructor.

Member Function Documentation

onConnectedClient()

virtual void RemoteViz::Rendering::ServiceListener::onConnectedClient ( const std::string &  clientId, std::shared_ptr< NetworkPerformance >  networkPerformance  )

virtual

Triggered when a client is connected to the service.

Default behavior : do nothing

If network performance calibration is enabled, the network bandwidth is measured after this call and before calling onInitializedClient. Therefore the NetworkPerformance queries getBandwidth and getLatency will return zero at this point. Use the queries in onInitializedClient to get the measured values.

Calibration is enabled by default. Calibration can be disabled using the networkPerformance parameter (see NetworkPerformance::enableCalibration). The duration of the calibration measurement (default 5 seconds) can also be modified (see NetworkPerformance::setMaxCalibrationDuration).

Parameters

clientId	: ID identifying the client
networkPerformance	: network performance for the client.

onDisconnectedClient()

virtual void RemoteViz::Rendering::ServiceListener::onDisconnectedClient ( const std::string &  clientId )

virtual

Triggered when a client is disconnected from the service.

Default behavior : do nothing

Parameters

clientId

: ID identifying the client

onDisposedRenderArea()

virtual void RemoteViz::Rendering::ServiceListener::onDisposedRenderArea ( const std::string &  renderAreaId )

virtual

Triggered when a renderArea has been disposed.

See RenderArea::closeConnectionsAndDispose. At this point, the resources of the renderArea have been released. This listener is called after onDisposingRenderArea.

Default behavior : do nothing

Parameters

renderAreaId

: ID identifying the disposed renderArea

onDisposingRenderArea()

virtual void RemoteViz::Rendering::ServiceListener::onDisposingRenderArea ( std::shared_ptr< RenderArea >  renderArea )

virtual

Triggered before a renderArea is disposed.

See RenderArea::closeConnectionsAndDispose. After disposing the renderArea, the object will be considered as "disposed" (see RenderArea::isDisposed) and will never be reused by RemoteViz internally. This listener is called before onDisposedRenderArea.

Default behavior : do nothing

Parameters

renderArea

: the renderArea that will be disposed

onHTTPRequest()

virtual HTTPResponse RemoteViz::Rendering::ServiceListener::onHTTPRequest ( std::shared_ptr< const HTTPRequest >  httpRequest )

virtual

Triggered when an HTTP connection is made that does not attempt to upgrade the connection to the WebSocket protocol.

This allows a service to respond to these requests with regular HTTP responses. It can be useful, for example, to manage health checks:

Health checks are usually used with an external monitoring service or container orchestrator to check the status of the service. They periodically invoke the endpoint to check the health of the service instance.

In a Kubernetes environment, a pair of health checks are used that distinguish between two states:

• The service is functioning but not yet ready to receive requests. This state is the service's readiness.
• The service is functioning and responding to requests. This state is the service's liveness.

This method is not suitable to serve high volume requests or HTTP resources, in these cases, prefer a dedicated HTTP server like Apache or Nginx. Only HTTP 1.0 features are supported (status code, method, content type and headers). Connections are terminated immediately after the response.

Default behavior : returns an HTTPResponse with "404 NOT FOUND" status.

IMPORTANT: This listener is executed in a separate thread. It gives your program the chance to perform longer calculations without blocking other network operations.

Parameters

httpRequest

HTTP request message

Returns

HTTP response message

onInitializedClient()

virtual void RemoteViz::Rendering::ServiceListener::onInitializedClient ( std::shared_ptr< Client >  client, std::shared_ptr< const NetworkPerformance >  networkPerformance  )

virtual

Triggered when a client is initialized.

Default behavior : If network performance calibration is enabled NetworkPerformance::enableCalibration), the client bandwidth value (ClientSettings::setBandwidth) is set to the measured network bandwidth value (NetworkPerformance::getBandwidth).

If calibration is enabled, the network performance measures can be retrieved using the networkPerformance parameter (see NetworkPerformance::getBandwidth and NetworkPerformance::getLatency).

The client bandwidth value (ClientSettings::setBandwidth) influences the quality and the number of interactive frames sent to the client (see ConnectionSettings::setFrameEncodingPolicy). The higher the value, the better the quality and the number of interactive frames.

Parameters

client	: client that is being connected to the service.
networkPerformance	: network performance for the client.

onInstantiatedRenderArea()

virtual void RemoteViz::Rendering::ServiceListener::onInstantiatedRenderArea ( std::shared_ptr< RenderArea >  renderArea )

virtual

Triggered when a renderArea has been instantiated.

Default behavior : do nothing

Parameters

renderArea

: the instantiated renderArea

onMissingLicense()

virtual SoDEPRECATED void RemoteViz::Rendering::ServiceListener::onMissingLicense ( const std::string &  renderAreaId, std::shared_ptr< const ConnectionParameters >  parameters  )

virtual

This listener is deprecated from Open Inventor 10.9 and is not triggered by RemoteViz anymore.

Triggered when a new connection is requested and a RemoteViz license is not found. In this callback, if you release one RemoteViz license (for instance, closing another connection), the new connection will then be opened. Otherwise, a LICENSE disconnect message will be sent to the client (which can choose to notify the user).

IMPORTANT: This callback is executed in a separate thread.

RemoteViz is protected by a license key mechanism limiting its use to specified computers or network environments based on commercial agreements. RemoteViz uses floating licenses managed by a license server or an encrypted "master password" string (see SoLockManager).

Default behavior : Post an error message.

onPendingCreateRenderArea()

virtual bool RemoteViz::Rendering::ServiceListener::onPendingCreateRenderArea ( const std::string &  renderAreaId, unsigned int &  width, unsigned int &  height, std::shared_ptr< RenderAreaHardware >  renderAreaHardware, std::shared_ptr< Client >  client, std::shared_ptr< const ConnectionParameters >  parameters  )

virtual

Triggered when a connection is pending and the requested renderArea does not exist.

Default behavior : Accept the connection by returning true.

Use this callback to implement connection management, e.g. authentication. See the Authentication page and the ConnectionManagement example example. Accepting the connection means that RemoteViz will create a RenderArea and give it the id requested by the Client (renderAreaId).

Parameters

renderAreaId	: ID identifying the renderArea requested by the client
width	: client requested width if the connection parameters contain this information, otherwise it's the renderArea default width. This value can be modified, it determines the created RenderArea width.
height	: client requested height if the connection parameters contain this information, otherwise it's the renderArea default height. This value can be modified, it determines the created RenderArea height.
renderAreaHardware	: hardware settings used to compute the render.
client	: client that is being connected to the service. If the client does not exist yet, this parameter will be null.
parameters	: field-value pairs included in the url during the client connection. See connectTo function in RemoteVizRenderArea.

Returns

true if the connection is accepted. The renderArea will be created.
Otherwise returns false. In this case, the client will be notified by an REFUSED disconnect message.
If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
If there are no listeners to call, the connection will be accepted.

onPendingShareRenderArea()

virtual bool RemoteViz::Rendering::ServiceListener::onPendingShareRenderArea ( std::shared_ptr< RenderArea >  renderArea, std::shared_ptr< Client >  client, std::shared_ptr< const ConnectionParameters >  parameters  )

virtual

Triggered when a connection is pending and the requested renderArea exists.

Default behavior : accept the connection by returning true.

Parameters

renderArea	: the requested renderArea
client	: client that is being connected to the service. If the client does not exist yet, this parameter will be null.
parameters	: field-value pairs included in the url during the client connection. See connectTo function in RemoteVizRenderArea.

Returns

true if the connection is accepted, otherwise returns false. In this case, the client will be notified by an REFUSED disconnect message.
If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
If there are no listeners to call, the connection will be accepted.

onRequestedPrivateKeyPassphrase()

virtual std::string RemoteViz::Rendering::ServiceListener::onRequestedPrivateKeyPassphrase ( )

virtual

Triggered when the secure connection is enabled.

This callback has to return the private key passphrase.

If the private key does not contain a passphrase, do not implement this callback. The default implementation will return an empty string.

Security warning !! DO NOT hard-code the passphrase into this callback !!
Read it from a SECURE location on your system.

See also

ServiceSettings::enableSecureConnection

Default behavior : returns an empty string.

---

The documentation for this class was generated from the following file:

• RemoteViz/Rendering/ServiceListener.h