DiCE API nvidia_logo_transpbg.gif Up
mi::bridge::IClient_session Class Referenceabstract

Represents the client side of a Bridge session. More...

#include <ibridge_client.h>

Inheritance diagram for mi::bridge::IClient_session:

Public Member Functions

virtual Client_session_state get_state ()=0
 Returns the state of the session. More...
 
virtual void add_session_state_callback (IClient_session_state_callback *callback)=0
 Adds a session state callback. More...
 
virtual void remove_session_state_callback (IClient_session_state_callback *callback)=0
 Removes a previously added session state callback. More...
 
virtual Sint32 execute (IClient_job *job, neuraylib::ITransaction *transaction)=0
 Schedules the provided job for execution on the server and returns immediately. More...
 
virtual Sint32 cancel (IClient_job *job)=0
 Marks the provided job to be canceled and returns immediately. More...
 
virtual IClient_video_contextcreate_video_context ()=0
 Creates a new video context. More...
 
virtual Sint32 measure_bandwidth (IClient_measure_bandwidth_callback *progress_callback, bool upload, Uint32 package_size, Uint32 package_count=1)=0
 Measures the bandwidth to the Bridge server. More...
 
virtual void set_receiving_logger (base::ILogger *logger)=0
 Sets the receiving logger for log messages forwarded from the Bridge server. More...
 
virtual base::ILoggerget_receiving_logger () const =0
 Returns the receiving logger for log messages forwarded from the Bridge server. More...
 
virtual Sint32 set_forwarding_log_level (base::Message_severity level)=0
 Sets the log level of messages that are forwarded from the Bridge server. More...
 
virtual base::Message_severity get_forwarding_log_level () const =0
 Returns the currently set log level for messages forwarded from the server. More...
 
virtual Size get_bytes_written () const =0
 Returns the number of bytes written to the server so far. More...
 
virtual Size get_bytes_read () const =0
 Returns the number of bytes read from the server so far. More...
 
virtual Sint32 set_hash_overrides (const IMap *overrides, const char *top_level_element, neuraylib::ITransaction *transaction)=0
 Allows the data for specific elements to be overridden by specifying the hash of the data to use regardless of the actual data stored in the db. More...
 
- Public Member Functions inherited from mi::base::IInterface
virtual Uint32 retain () const =0
 Increments the reference count. More...
 
virtual Uint32 release () const =0
 Decrements the reference count. More...
 
virtual const IInterfaceget_interface (const Uuid &interface_id) const =0
 Acquires a const interface from another. More...
 
template<class T>
const T * get_interface () const
 Acquires a const interface from another. More...
 
virtual IInterfaceget_interface (const Uuid &interface_id)=0
 Acquires a mutable interface from another. More...
 
template<class T>
T * get_interface ()
 Acquires a mutable interface from another. More...
 
virtual Uuid get_iid () const =0
 Returns the interface ID of the most derived interface. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x70bb8712, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x70bb8712, ... >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
- Static Public Member Functions inherited from mi::base::IInterface
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface. More...
 

Detailed Description

Represents the client side of a Bridge session.

A session can be opened by mi::bridge::IBridge_client::get_session(). Note that repeated calls of that method with the same arguments return the same session, i.e., sessions are shared between different callers. Sharing the same session is vital for features such as incremental changes, and to share other resources that would otherwise be duplicated. The session will be destroyed and client- and server-side resources will be released when all references to the session has been released.

The session will automatically connect to the server. Use add_session_state_callback() for callbacks about session state changes. A closed session can not be used anymore. Use mi::bridge::IBridge_client::get_session() to attempt to reconnect.

See also
mi::bridge::IBridge_client::get_session()

Member Function Documentation

 add_session_state_callback()

virtual void mi::bridge::IClient_session::add_session_state_callback ( IClient_session_state_callback callback)
pure virtual

Adds a session state callback.

When adding a callback it will be called immediately once with the current state, and then every time the session state changes.

See also
remove_session_state_callback()
Parameters
callbackThe callback to be added.

 cancel()

virtual Sint32 mi::bridge::IClient_session::cancel ( IClient_job job)
pure virtual

Marks the provided job to be canceled and returns immediately.

A job progress callback will be made to inform when the job is canceled or completed. Note that it is not always possible to cancel a job depending on the timing so a job can still be completed even after successfully calling this method.

Known limitation: Canceling jobs doing uploads doesn't cancel the upload itself and even if the job is canceled successfully some or all uploaded elements might be stored in the database. To make sure that elements from a job is not persisted in the server side database the transaction must be aborted. This will automatically cancel all Bridge jobs running in that transaction.

Parameters
jobThe job to cancel.
Returns
  • 0: Job canceled.
  • 1: Job not executing or already canceled.
  • -1: Invalid arguments (job is NULL).
  • -3: Network error.
  • <= -4: Unspecified error.

 create_video_context()

virtual IClient_video_context * mi::bridge::IClient_session::create_video_context ( )
pure virtual

Creates a new video context.

The video context will be assigned an id which needs to be transferred to the server, along with any other data required to set up the video source properly. The server use this id to get the corresponding server-side video context which can be used to stream video frames to the client. The recommended way of transferring the id to the server is by executing a Bridge job.

Returns
The created video context, or NULL in case of failure.

 execute()

virtual Sint32 mi::bridge::IClient_session::execute ( IClient_job job,
neuraylib::ITransaction *  transaction 
)
pure virtual

Schedules the provided job for execution on the server and returns immediately.

Jobs are executed asynchronously, but sequentially (per transaction) on the server in the same order as execution is requested by this method. A job is only executed after its referenced database elements have been updated from the Bridge client to the Bridge server.

Note that the same IClient_job instance must not be executed several times in parallel. This is true both within a single transaction and in multiple transactions.

Parameters
jobThe job to execute.
transactionThe transaction in which context the job will be executed.
Returns
  • 0: Success.
  • -1: Invalid arguments (job or transaction is NULL).
  • -2: Invalid transaction state (already committed or aborted).
  • -3: Network error.
  • -4: The job reference elements that can't be accessed.
  • <= -5: Unspecified error.

 get_bytes_read()

virtual Size mi::bridge::IClient_session::get_bytes_read ( ) const
pure virtual

Returns the number of bytes read from the server so far.

See also
get_bytes_written()

 get_bytes_written()

virtual Size mi::bridge::IClient_session::get_bytes_written ( ) const
pure virtual

Returns the number of bytes written to the server so far.

See also
get_bytes_read()

 get_forwarding_log_level()

virtual base::Message_severity mi::bridge::IClient_session::get_forwarding_log_level ( ) const
pure virtual

Returns the currently set log level for messages forwarded from the server.

See also
set_forwarding_log_level

 get_receiving_logger()

virtual base::ILogger * mi::bridge::IClient_session::get_receiving_logger ( ) const
pure virtual

Returns the receiving logger for log messages forwarded from the Bridge server.

Note that if no receiving logger has been set, this method returns NULL and logging is done using the currently general configured logger.

See also
set_receiving_logger()

 get_state()

virtual Client_session_state mi::bridge::IClient_session::get_state ( )
pure virtual

Returns the state of the session.

See also
mi::bridge::Client_session_state

 measure_bandwidth()

virtual Sint32 mi::bridge::IClient_session::measure_bandwidth ( IClient_measure_bandwidth_callback progress_callback,
bool  upload,
Uint32  package_size,
Uint32  package_count = 1 
)
pure virtual

Measures the bandwidth to the Bridge server.

The bandwidth is measured by sending a specified number of packages with a specified size in bytes. This method is asynchronous, the provided callback interface will be called when there is progress and when the measurement is done.

Note
For meaningful results the method should only be called when the session is not used to upload or download other real data at the same time.
Parameters
progress_callbackA callback interface that will be called with progress information.
uploadtrue for measuring upload bandwidth, false for measuring download bandwidth.
package_sizeThe size in bytes of a single package.
package_countThe number of packages to upload or download.
Returns
0 if the measurement was successfully started, -1 otherwise.

 remove_session_state_callback()

virtual void mi::bridge::IClient_session::remove_session_state_callback ( IClient_session_state_callback callback)
pure virtual

Removes a previously added session state callback.

See also
add_session_state_callback()
Parameters
callbackThe callback to be removed.

 set_forwarding_log_level()

virtual Sint32 mi::bridge::IClient_session::set_forwarding_log_level ( base::Message_severity  level)
pure virtual

Sets the log level of messages that are forwarded from the Bridge server.

Note that this does not affect the log level of the server, nor the log level of the client. It only filters the messages forwarded by the server to the client. Also note that the server will never send out log messages more verbose than the configured limit for the bridge application the session is connected to.

See also
get_forwarding_log_level()

 set_hash_overrides()

virtual Sint32 mi::bridge::IClient_session::set_hash_overrides ( const IMap overrides,
const char *  top_level_element,
neuraylib::ITransaction *  transaction 
)
pure virtual

Allows the data for specific elements to be overridden by specifying the hash of the data to use regardless of the actual data stored in the db.

The replacements will only be done when executing a bridge job that returns the provided top_level_element in its get_references() method and only when executed in the same scope as the scope of the provided transaction. When an edited element is detected for the job the overrides map will be consulted to see if an override for the element with that name exists. If it does the element won't be serialized and the override hash from the map will be used instead. The server then use the hash when loading the data from the cache, meaning that it can be different than the actual data on the client. For this to work, the data for the hash must be guaranteed to already be in the server side cache. This can be achieved by storing snapshots in the server side cache with all required data before rendering the scene containing hash overrides.

Parameters
overridesAn IMap with the name of the element to override as key and the hash as string value. The map must be of type Map<String>. Call this method with a NULL override map to release it or replace it with a new one. The map instance is retained by bridge to avoid expensive copying and must not be modified after this call.
transactionThe hash overrides will be applied only for jobs executing in the same scope as this transaction. The top level element must be visible in this transaction.
top_level_elementThe top level element. The overrides applies to this element and all elements it reference when executing a job that returns the specified top level element in its get_references() method.
Returns
  • 0: Success.
  • -1: Invalid arguments (job or transaction is NULL).
  • -2: Invalid transaction state (already committed or aborted).
  • <= -2: Unspecified error.

 set_receiving_logger()

virtual void mi::bridge::IClient_session::set_receiving_logger ( base::ILogger logger)
pure virtual

Sets the receiving logger for log messages forwarded from the Bridge server.

If the provided logger is NULL then forwarded log entries will be written to the general configured logger as if they were generated locally, but with a prefix identifying the server that they originated from (default behavior).

See also
set_receiving_logger()
Parameters
loggerThe receiving logger. It is valid to pass NULL in which case logging is reset to be done to the general configured logger.