Session Class Reference

Top-level session object that owns the connection to a running INCA instance. More...

#include <Session.hpp>

Public Member Functions
	Session (const Session &)=delete
	Copying is deleted; the COM connection must not be duplicated.
	Session (Session &&)=delete
	Move construction is deleted; the session has a unique identity.
Session &	operator= (const Session &)=delete
	Copying assignment is deleted; the COM connection must not be duplicated.
Session &	operator= (Session &&)=delete
	Move assignment is deleted; the session has a unique identity.
	~Session ()
	Destructor; triggers disconnection from INCA via IncaProxy.
auto	add_param (const std::string &name) -> void
	Registers a calibration parameter for use during the experiment.
auto	set_param (const std::string &name, double value) -> void
	Sets a registered calibration parameter to the given value.
auto	reset () -> void
	Resets all registered parameters to their reference-page values and clears the internal parameter table.
auto	start_recording () -> void
	Starts a new measurement recording in INCA.
auto	stop_recording (const std::filesystem::path &filename) -> void
	Stops the recording, saves the measurement data, and resets all registered parameters.

Static Public Member Functions
static auto	connect (const std::function< IDispatch *(void)> &factory) -> Session
	Factory function that connects to a running INCA instance and returns an initialised Session.
static auto	connect () -> Session
	Factory function that connects to a running INCA instance and returns an initialised Session.

Detailed Description

Top-level session object that owns the connection to a running INCA instance.

Session is the single entry point for the pacemaker library. It establishes a COM connection to a locally running INCA process, validates that an experiment is open and at least one device is online and exposes the complete measurement workflow, parameter management, recording lifecycle, and teardown, through a single, opaque object.

Typical usage

CoInitialize(NULL);
auto session = pacemaker::inca::Session::connect();
 
session.add_param("Engine_TorqueRequest");
session.start_recording();
session.set_param("Engine_TorqueRequest", 120.0);
session.stop_recording("run_001.mf4");
 
// Session destructor calls DisconnectFromTool() automatically
CoUninitialize();

Lifetime and thread safety

The session is non-copyable and non-movable. Exactly one Session should exist per INCA automation connection. COM must be initialised on the calling thread before connect() is invoked.

On destruction, Session's destructors calls DisconnectFromTool() on the INCA COMM object, ensuring INCA is cleanly notified of the disconnection.

Note

Platform: Windows only. INCA must be installed and running.

Definition at line 45 of file Session.hpp.

Constructor & Destructor Documentation

Session() [1/2]

Session ( const Session & )

delete

Copying is deleted; the COM connection must not be duplicated.

Session() [2/2]

Session ( Session && )

delete

Move construction is deleted; the session has a unique identity.

~Session()

~Session

(

)

Destructor; triggers disconnection from INCA via IncaProxy.

DisconnectFromTool() is called on the Incaproxy object, so INCA is notified of the disconnection. Then the Proxies are destroyed in reverse order.

Member Function Documentation

connect() [1/2]

static auto connect ( const std::function< IDispatch *(void)> & factory ) -> Session

staticnodiscard

Factory function that connects to a running INCA instance and returns an initialised Session.

The function allows to specify a custom way to initialize Session and its underlying structures.

Parameters

factory

Function returning the argument to initialize the underlying IncaProxy member variable

Returns

A fully constructed Session ready for use.

Exceptions

std::runtime_error	if CoCreateInstance fails (INCA not installed or not running).
std::runtime_error	if the open experiment has no devices configured or online.

Precondition

COM must be initialised on the calling thread (e.g. CoInitialize oir CoInitializeEx)

connect() [2/2]

static auto connect ( ) -> Session

staticnodiscard

Factory function that connects to a running INCA instance and returns an initialised Session.

The function performs the following steps:

1. Calls CoCreateInstance(CLSID_Inca, CLSCTX_LOCAL_SERVER) to obtain the root INCA COM object.
2. Retrieves the open experiment and experiment-view objects via IncaProxy.
3. Enumerates connected devices; selects the first available device.
4. Constructs and returns a Session owning an IncaProxy and the fully initialised Experiment.

Returns

A fully constructed Session ready for use.

Exceptions

std::runtime_error	if CoCreateInstance fails (INCA not installed or not running).
std::runtime_error	if the open experiment has no devices configured or online.

Precondition

COM must be initialised on the calling thread (e.g. CoInitialize oir CoInitializeEx)

operator=() [1/2]

Session & operator= ( const Session & )

delete

Copying assignment is deleted; the COM connection must not be duplicated.

operator=() [2/2]

Session & operator= ( Session && )

delete

Move assignment is deleted; the session has a unique identity.

add_param()

auto add_param

(

const std::string &

name

)

-> void

Registers a calibration parameter for use during the experiment.

Looks up the named calibration scalar on the primary device via IncaOnlineExperiment_DispatchWrapper::GetCalibrationValueInDevice() and stores the resulting CalibrationScalarDataProxy in the internal parameter table. The parameter can then be updated during the run via set_param().

Calling add_param() a second time with the same naem is a no-op; the parameter is not re-fetched from INCA.

Parameters

name	Name of the calibration parameter as it appears in INCA.

Exceptions

std::runtime_error

if the parameter cannot be found in the primary device.

set_param()

auto set_param	(	const std::string &	name,
		double	value ) -> void

Sets a registered calibration parameter to the given value.

Looks up name in the internal parameter table and calls SetImplValue(value) vis operator-> on the stored CalibrationScalarDataProxy. The change takes effect immediately in the running INCA measurement session.

Parameters

name	Name of the calibration parameter previously registered via add_param().
value	New value to write to the parameter's implementation page.

Note

returns silently if name was not registered via add_param().

reset()

auto reset

(

)

-> void

Resets all registered parameters to their reference-page values and clears the internal parameter table.

Iterates over all stored CalibrationScalarDataProxy objects and calls ResetValueToRP() via operator-> on each. After this call the session is in the same state as immediately after connect(...), no parameters are registered and INCA's calibration values are restored to their reference-page baseline.

This method is called automatically by stop_recording() at the end of each run, but may also be called explicitly if an early reset is needed.

start_recording()

auto start_recording

(

)

-> void

Starts a new measurement recording in INCA.

Delegates to StartRecording() on the internal IncaOnlineExperimentProxy via operator->. The recording captures all online measurement signals configured in the open INCA experiment from this point forward.

Register all calibration parameters via add_param() before calling start_recording().

stop_recording()

auto stop_recording

(

const std::filesystem::path &

filename

)

-> void

Stops the recording, saves the measurement data, and resets all registered parameters.

The method performs the following steps in order:

1. Sleeps for k_flush_delay (40 ms) to allow INCA to flush any buffered measurement samples.
2. Stops the INCA recording and saves the recording
3. Stop measurement
4. Resets all registered calibration parameters to their reference-page values

Parameters

filename

Output recording filename or filepath passed to INCA.

---

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

• include/pacemaker/inca/Session.hpp