Description

This class manages connection to winIDEA.

#include <ConnectionMgr.h>

Inherits std::enable_shared_from_this< ConnectionMgr >.

Public Types
enum	EVersionControl { EVersionIgnore , EVersionWarning , EVersionError }
	Defines constants for winIDEA version verification. More...

Public Member Functions
	ConnectionMgr (void)
	Constructs the object, and creates IConnect client. More...

	ConnectionMgr (const std::string &rstrPath)

	~ConnectionMgr (void)
	If this instance is owner of IConnectClient, it disconnects from winIDEA and deletes IConnectClient. More...

void	initLogger (const std::string &id, const std::string &fileName, isys::CLogger::LogFileLanguage language)
	Initializes logger, which is owned by instance of this class. More...

const std::string &	getId ()
	Returns the ID set by setLogger(). More...

isys::CLogger *	getLogger ()
	Returns pointer to logger set by setLogger(). More...

void	connect (SPConnectionConfig spConnectionConfig)
	Connects to local winIDEA instance with the same configuration (workspace, id) as set in input parameter. More...

void	connect ()
	Connects to most-recently started winIDEA instance If it is not running, a new instance is started. More...

bool	isConnected ()
	Returns true, if connection was established. More...

void	enumerateWinIDEAInstances (const std::string &address, const SPConnectionConfig spConnectionConfig, VectorWinIDEAInstanceInfo &instances)
	This method enumerates instances of winIDEA running at the specified host. More...

void	disconnect_keep ()
	Disconnects from winIDEA and leaves it running. More...

void	disconnect_close (bool bSaveAll)
	Disconnects from winIDEA and closes it. More...

isys::CWinIDEAVersion	getWinIDEAVersion ()
	Returns winIDEA version. More...

bool	isCoreLaunched (int coreIndex)
	Returns true, if core is already launched, false otherwise. More...

ConnectionMgrSPtr	launchCore1 (uint32_t coreIndex)
	Opens another winIDEA instance, which is connected to core specified by parameter 'coreIndex'. More...

bool	isWarning ()
	Returns true, if the last operation issued a warning.

std::string	getLastErrorMsg ()
	Returns the warning or error message of the last operation. More...

bool	isAttached ()
	Returns true, if connection to winIDEA is alive. More...

	ConnectionMgr (ConnectionMgr::EVersionControl versionControl)

void	connectMRU (const std::string &workspacePath="", const std::string &winIDEAId="", const std::string &hostIpAddress="", bool isUseServerEnvVars=true)

void	connectMRUEx (const std::string &workspacePath, bool isAnyWinIDEAId, const std::string &winIDEAId, const std::string &hostIpAddress, bool isUseServerEnvVars)

int	findExistingInstance (const std::string &address, SPConnectionConfig spConnectionConfig)

int	startNewInstance (SPConnectionConfig spConnectionConfig)

int	findOrStartInstance (SPConnectionConfig spConnectionConfig)

void	connect (const std::string &address, int iconnectPort)

void	connect (uint32_t pid)

void	disconnect (IConnect::EDetachFlags flags=IConnect::dfCloseAutoSaveDefault)

void	disconnect (IConnect::EDetachFlags closeServerFlags, IConnect::EDetachFlags autoSaveFlags)

std::string	launchCore (int coreIndex, bool isPrimaryCoreIndexed=false)

Static Public Member Functions
static bool	isStartedFromWinIDEA ()
	Returns true, if application calling this function was started from winIDEA, false otherwise.

Member Enumeration Documentation

◆ EVersionControl

enum isys::ConnectionMgr::EVersionControl

Defines constants for winIDEA version verification.

Enumerator
EVersionIgnore	version is not verified
EVersionWarning	version is verified and warning written if winIDEA is different version than SDK
EVersionError	version is verified and exception thrown if winIDEA is different version than SDK

Constructor & Destructor Documentation

◆ ConnectionMgr() [1/3]

isys::ConnectionMgr::ConnectionMgr ( void )

Constructs the object, and creates IConnect client.

The most recently used isystem.connect DLL is used. Use one of connection methods to establish connection to winIDEA. If this ctor is used, version of winIDEA is verified on connect, and warning written to stdout if it does not match isystem.connect SDK version.

>>> conn_mgr = ConnectionMgr()
>>> print(f"Is connected: {conn_mgr.isConnected()}")
Is connected: False

Python example: test_connection_mgr.py

◆ ConnectionMgr() [2/3]

isys::ConnectionMgr::ConnectionMgr ( const std::string & rstrPath )

Deprecated:: Use default constructor and then call connect(SPConnectionConfig) with CConnectionConfig::exe_dir() set to define directory where winIDEA.exe is located.

Constructs the object, and creates IConnect client. The specified path is used to start new winIDEA instance on connect() call, if necessary. Use one of connection methods to establish connection to winIDEA.

Parameters

rstrPath Path to winIDEA.exe or directory (must be terminated with \ or /) containing the winIDEA.exe. You can use this parameter if multiple versions of winIDEA are installed on a system and you want to control which one to use. Example value: 'C:/winIDEA/2024/'

Python example: test_connection_mgr.py

◆ ~ConnectionMgr()

isys::ConnectionMgr::~ConnectionMgr ( void )

If this instance is owner of IConnectClient, it disconnects from winIDEA and deletes IConnectClient.

Otherwise IConnectClient is left unchanged.

◆ ConnectionMgr() [3/3]

isys::ConnectionMgr::ConnectionMgr ( ConnectionMgr::EVersionControl versionControl )

Deprecated:: version control is always strict since 9.17.187. Use the parameterless constructor instead of this one.

Constructs the object, and creates IConnect client. The most recently used isystem.connect DLL is used. Use one of connection methods to establish connection to winIDEA.

Parameters

versionControl ignored

Member Function Documentation

◆ connect() [1/4]

void isys::ConnectionMgr::connect ( )

Connects to most-recently started winIDEA instance If it is not running, a new instance is started.

Python example: test_cconnection_config.py

◆ connect() [2/4]

void isys::ConnectionMgr::connect	(	const std::string &	address,
		int	iconnectPort
	)

Deprecated:: use connect(spConnectionConfig) instead

Connects to winIDEA via TCP/IP at address specified in address at the specified port. TCP/IP server must be enabled in winIDEA for this method to work (Tools | Options | tab isystem.connect).

Parameters

address	The IP address of the machine where winIDEA is running. This can be either dotted decimal or an URL. If it is an empty string, the local host is considered.
iconnectPort	The TCP port to use. This should be the same value as configured in winIDEA to which the connection is attempted. Default port value is 5315, and can be set in winIDEA' menu Tools \| Options \| isystem.connect \| TCP Connection Port Range.

Python example: test_cconnection_config.py

◆ connect() [3/4]

void isys::ConnectionMgr::connect ( SPConnectionConfig spConnectionConfig )

Connects to local winIDEA instance with the same configuration (workspace, id) as set in input parameter.

If it is not running, a new instance with the given configuration is started.

Parameters

spConnectionConfig expected winIDEA configuration and startup parameters

Python example: test_cconnection_config.py

◆ connect() [4/4]

void isys::ConnectionMgr::connect ( uint32_t pid )

Deprecated:: use connect(spConnectionConfig) instead

Connects to winIDEA with the given process ID.

Parameters

pid	Windows process ID

Python example: test_cconnection_config.py

Note: This call does not work on Linux, because it requires communication over shared memory, which is currently implemented only on Windows.

◆ connectMRU()

void isys::ConnectionMgr::connectMRU	(	const std::string &	workspacePath = `""`,
		const std::string &	winIDEAId = `""`,
		const std::string &	hostIpAddress = `""`,
		bool	isUseServerEnvVars = `true`
	)

Deprecated:: use connect(SPConnectionConfig) instead. connectMRU() without arguments can be replaced with connect().

Connects to the most recently used winIDEA and opens the given workspace. This is a utility method, which suits most needs. For complex configurations with more than one winIDEA instance or remote instances use other methods as described in documentation of this class.

If environment variables ICONNECT_PATH and ICONNECT_TCP_PORT are defined, then they define the winIDEA to connect to. Otherwise winIDEA's internal data is used to connect to the most recently started winIDEA. These two environment variables are defined when executing Python script interactively from winIDEA.

Note 1: On Linux this method always starts executable called winidea, which is on system path. It does not check which winIDEA was started latest.

Note 2: If this method does not find running winIDEA instance on Linux, check if you have enabled firewall (discovery is made with broadcasting).

Parameters

workspacePath	specifies a path to the workspace file. If the string is empty (size == 0), and winIDEA option `Tools \| Options \| Reload last workspace on startup` is enabled, the last opened workspace is used. Linux specific: Is is assumed that Wine maps drive Z: to root folder.
winIDEAId	if specified, connection is made to winIDEA, which was started with command line option /id:<winIDEAId>. If empty string, this parameter is ignored.
hostIpAddress	if specified, this host is used for lookup. If empty, local host is used.
isUseServerEnvVars	if true, environment vars as set by launching application are used to connect to winIDEA. Namely, process ID and TCP port are used. For example, if Python script was started from winIDEA, and this flag is `true`, then the script will be able to connect only to this instance of winIDEA. Set this flag to `false` to connect to other instances of winIDEA if required.

Exceptions

IllegalStateException	if already connected
IOException	if connecting to winIDEA failed

◆ connectMRUEx()

void isys::ConnectionMgr::connectMRUEx	(	const std::string &	workspacePath,
		bool	isAnyWinIDEAId,
		const std::string &	winIDEAId,
		const std::string &	hostIpAddress,
		bool	isUseServerEnvVars
	)

Deprecated:: use connect(spConnectionConfig) instead

Connects to the most recently used winIDEA and opens the given workspace. Use this method only if you want to connect to winIDEA with no ID specified. For complex configurations with more than one winIDEA instance or remote instances use other methods as described in documentation of this class.

If environment variables ICONNECT_PATH and ICONNECT_TCP_PORT are defined, then they define the winIDEA to connect to. Otherwise winIDEA's internal data is used to connect to the most recently started winIDEA. These two environment variables are defined when executing Python script interactively from winIDEA.

Parameters

workspacePath	specifies a path to the workspace file. If the string is empty (size == 0), and winIDEA option `Tools \| Options \| Reload last workspace on startup` is enabled, the last opened workspace is used. Linux specific: Is is assumed that Wine maps drive Z: to root folder.
isAnyWinIDEAId	if true, value of winIDEAId parameter is ignored - connection is made to winIDEA with any ID.
winIDEAId	if isAnyWinIDEAId is false, connection is made to winIDEA, which was started with command line option /id:<winIDEAId>). If empty string, connection is made to winIDEA, which was started without command line option /id:<winIDEAId>.
hostIpAddress	if specified, this host is used for lookup. If empty, local host is used.
isUseServerEnvVars	if true, environment vars as set by launching application are used to connect to winIDEA. Namely, process ID and TCP port are used. For example, if Python script was started from winIDEA, and this flag is `true`, then the script will be able to connect only to this instance of winIDEA. Set this flag to `false` to connect to other instances of winIDEA if required.

Exceptions

IllegalStateException	if already connected
IOException	if connecting to winIDEA failed
IllegalStateException	if already connected
IOException	if connecting to winIDEA failed

◆ disconnect() [1/2]

void isys::ConnectionMgr::disconnect	(	IConnect::EDetachFlags	closeServerFlags,
		IConnect::EDetachFlags	autoSaveFlags
	)

Deprecated:: use disconnect_keep / disconnect_close instead

Disconnects from winIDEA.

Parameters

closeServerFlags	one of `IConnect::EDetachFlags::dfCloseServer`... flags or 0 if we do not want to close winIDEA.
autoSaveFlags	one of `IConnect::EDetachFlags::dfCloseAutoSave`... flags

◆ disconnect() [2/2]

void isys::ConnectionMgr::disconnect ( IConnect::EDetachFlags flags = IConnect::dfCloseAutoSaveDefault )

Deprecated:: use disconnect_keep / disconnect_close instead

Disconnects from winIDEA. This method is automatically called by destructor, if connection to winIDEA is still active.

Python example: test_start_new_instance.py

◆ disconnect_close()

void isys::ConnectionMgr::disconnect_close ( bool bSaveAll )

Disconnects from winIDEA and closes it.

Parameters

bSaveAll if true, winIDA saves files and workspace, otherwise discards changes

◆ disconnect_keep()

void isys::ConnectionMgr::disconnect_keep ( )

Disconnects from winIDEA and leaves it running.

>>> conn_mgr = ConnectionMgr()
>>> conn_mgr.connect()
>>> conn_mgr.isConnected()
True
>>> conn_mgr.disconnect_keep()
>>> conn_mgr.isConnected()
False

◆ enumerateWinIDEAInstances()

void isys::ConnectionMgr::enumerateWinIDEAInstances	(	const std::string &	address,
		const SPConnectionConfig	spConnectionConfig,
		VectorWinIDEAInstanceInfo &	instances
	)

This method enumerates instances of winIDEA running at the specified host.

Parameters

address	The IP address of the machine where to search for running instance of winIDEA. This can be either dotted decimal or an URL. If it is empty string, the local host is considered.
spConnectionConfig	configuration parameters for search domain (shared memory or UDP). See CConnectionConfig for more info.
instances	vector to receive enumeration information. One element contains information for one instance found.

Python example: test_enumerate_winidea_instances.py

◆ findExistingInstance()

int isys::ConnectionMgr::findExistingInstance	(	const std::string &	address,
		SPConnectionConfig	spConnectionConfig
	)

Deprecated:: use connect(spConnectionConfig) instead

Finds existing instance of winIDEA if it is running on host specified with parameter address. Search criteria is specified with parameters workspace, and instanceId of parameter spConnectionConfig, if they are not empty strings.

Parameters

address	The IP address of the machine where to search for running instance of winIDEA. This can be either dotted decimal or an URL. If it is an empty string, the local host is considered, and shared memory discovery is used on Windows. On Linux UDP discovery is always used.
spConnectionConfig	configuration parameters for search algorithm. Process ID of found winIDEA instance is returned in this object. See CConnectionConfig for more info.

Returns: port number of the running instance which matches the search criteria. If no such winIDEA instance was found, exception is thrown.

See also: findOrStartInstance; startNewInstance

Exceptions

IOException if winIDEA instance could not be found.

Python example: advanced_winidea_launching.py
Python example: test_find_existing_instance.py

◆ findOrStartInstance()

int isys::ConnectionMgr::findOrStartInstance ( SPConnectionConfig spConnectionConfig )

Deprecated:: use connect(spConnectionConfig) instead

First tries to find a winIDEA instance, with workspace, and instanceId as specified in spConnectionConfig. If any of these two items is empty string, it is ignored when searching. If matching instance of winIDEA is found, its isystem.connect port number is returned. If not, a new instance is started and its isystem.connect port number is returned.

Parameters

spConnectionConfig configuration parameters for search algorithm and creating of new winIDEA instance. Process ID of found/started winIDEA instance is set in this object if shared memory communication is used. If TCP/IP is used, then process ID of winIDEA is set only if winIDEA has been started. See CConnectionConfig for more info.

Returns: port number of winIDEA instance matching the workspace and instanceId in spConnectionConfig.

See also: startNewInstance; findExistingInstance

Python example: test_find_or_start_instance.py

◆ getId()

const std::string & isys::ConnectionMgr::getId ( )

Returns the ID set by setLogger().

Python example: test_logger.py

◆ getLastErrorMsg()

std::string isys::ConnectionMgr::getLastErrorMsg ( )

Returns the warning or error message of the last operation.

Returns empty string, when there was no error or warning.

Python example: test_get_last_error_msg.py

◆ getLogger()

isys::CLogger * isys::ConnectionMgr::getLogger ( )

Returns pointer to logger set by setLogger().

Python example: test_logger.py

◆ getWinIDEAVersion()

isys::CWinIDEAVersion isys::ConnectionMgr::getWinIDEAVersion ( )

Returns winIDEA version.

Supported only on winIDEA versions 9.9 and higher.

◆ initLogger()

void isys::ConnectionMgr::initLogger	(	const std::string &	id,
		const std::string &	fileName,
		isys::CLogger::LogFileLanguage	language
	)

Initializes logger, which is owned by instance of this class.

Logger writes isystem.connect calls to log file, so that it produces valid python program in most cases. Only some complex calls, which require creation of local variables are not logged in a way to be directly executable.

Parameters

id

used as prefix in log statements. The default value is empty string, which is OK if there is only one winIDEA instance. If we are controlling multiple targets or multi-core CPUs, then the ID must be set to distinguish connections in scripts produced by isystem.connect logger. If the id is empty, logged statements will look something like:

        execCtrl.setBP("func1");

If we set the id to main_ , we get:

        main_execCtrl.setBP("func1");

fileName name of the log file

language language used for log files statements. Only PYTHON is currently fully supported, while JAVA has limited support.

Python example: test_logger.py

◆ isAttached()

bool isys::ConnectionMgr::isAttached ( )

Returns true, if connection to winIDEA is alive.

When winIDEA is closed, this method returns false.

See also: isConnected()

Python example: test_is_attached.py

◆ isConnected()

bool isys::ConnectionMgr::isConnected ( )

Returns true, if connection was established.

It returns true, until the method disconnect() (which releases connection resources) is called, even if winIDEA is closed after the connection is established.

See also: isAttached()

Python example: test_connect.py

◆ isCoreLaunched()

bool isys::ConnectionMgr::isCoreLaunched ( int coreIndex )

Returns true, if core is already launched, false otherwise.

i

Parameters

coreIndex 0 for primary core, 1 for next core, ...

Python example: test_launch_core1.py

◆ launchCore()

std::string isys::ConnectionMgr::launchCore	(	int	coreIndex,
		bool	isPrimaryCoreIndexed = `false`
	)

Deprecated:: This method does not work reliably when you have multiple instances of winIDEA with the same workspace opened. Use launchCore1() instead.

Opens another winIDEA instance, which is connected to core specified by parameter 'coreIndex'.

Parameters

coreIndex	index of the core, starting with 0. If parameter `isPrimaryCoreIndexed` is false, then the primary core is not indexed, so index `0` means core 1. This is deprecated usage, which exists for backward compatibility. It is recommended to always set flag `isPrimaryCoreIndexed` to `true`, so all cores can be indexed. Indices may be in range 0..(N - 1), where N is the number of cores.
isPrimaryCoreIndexed	see description of parameter `coreIndex` above.

Returns: name of the workspace file used by the newly opened instance. To use isystem.connect with this core, instantiate another ConnectionMgr and use the returned workspace name as parameter to ConnectionMgr::connectMRU().

◆ launchCore1()

ConnectionMgrSPtr isys::ConnectionMgr::launchCore1 ( uint32_t coreIndex )

Opens another winIDEA instance, which is connected to core specified by parameter 'coreIndex'.

Connection to primary core must be made before this method is called.

Parameters

coreIndex index of the core, starting with 0. Indices may be in range 0..(N - 1), where N is the number of cores. Since instance of connection manager on which this method is called is usually connected to core 0, this parameter is usually >= 1.

Returns: connection manager already connected to the winIDEA instance.

Python example: test_launch_core1.py

◆ startNewInstance()

int isys::ConnectionMgr::startNewInstance ( SPConnectionConfig spConnectionConfig )

Deprecated:: use connect(spConnectionConfig) instead

Starts new instance of winIDEA with parameters specified in spConnectionConfig. To connect to the new winIDEA instance call method connect() with port number returned by this method.

Parameters

spConnectionConfig configuration of the new instance of winIDEA to be started. Process ID of started winIDEA instance is returned in this object.

Returns: isystem.connect port of the new winIEDA instance

See also: findOrStartInstance; findExistingInstance

Python example: test_start_new_instance.py

Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

◆ EVersionControl

Constructor & Destructor Documentation

◆ ConnectionMgr() [1/3]

◆ ConnectionMgr() [2/3]

◆ ~ConnectionMgr()

◆ ConnectionMgr() [3/3]

Member Function Documentation

◆ connect() [1/4]

◆ connect() [2/4]

◆ connect() [3/4]

◆ connect() [4/4]

◆ connectMRU()

◆ connectMRUEx()

◆ disconnect() [1/2]

◆ disconnect() [2/2]

◆ disconnect_close()

◆ disconnect_keep()

◆ enumerateWinIDEAInstances()

◆ findExistingInstance()

◆ findOrStartInstance()

◆ getId()

◆ getLastErrorMsg()

◆ getLogger()

◆ getWinIDEAVersion()

◆ initLogger()

◆ isAttached()

◆ isConnected()

◆ isCoreLaunched()

◆ launchCore()

◆ launchCore1()

◆ startNewInstance()