This group of functions is used for setting up the connection with the SpaceControl Daemon and handle special things where the daemon is involved, but not the devices. More...

Functions
ScStatus	scConnect2 (bool isAlwaysReceivingData, char *applName)
	Establishes the connection to the SpaceControl daemon. More...

ScStatus	scConnect ()

ScStatus	scDisconnect ()
	Closes the connection to the SpaceControl daemon. More...

ScStatus	scStop ()
	Sends the SpaceControl Daemon a stop message, the process finishes itself after sending an OK message. More...

ScStatus	scGetDmnVrsn (char versionP, char pathP)
	Retrieves the SpaceControl daemon's software version and its binary name and path. More...

ScStatus	scGetFgAppl (char fgApplNameP, char fgApplStateP)
	Retrieves the name and potentially the state of the foreground application. More...

ScStatus	scSetState2 (char *state)
	Informs the daemon about the internal state (mode) of a supported application. More...

ScStatus	scSetState (char str1, char str2)

ScStatus	scGetDaemonPar (int par, int *val)
	Retrieves one of the integer or boolean parameters available in the Daemon's configuration file "daemon.ini". More...

ScStatus	scSetDaemonPar (int par, int *val)
	Sets one of the integer or boolean parameters available in the Daemon's configuration file "daemon.ini". More...

Detailed Description

This group of functions is used for setting up the connection with the SpaceControl Daemon and handle special things where the daemon is involved, but not the devices.

Function Documentation

◆ scConnect()

ScStatus scConnect ( )

Deprecated:: This function is replaced by scConnect2() and should not be used any longer.

Establishes the connection to the SpaceControl daemon. If this function is not executed successfully no other DLL functions can be used.
Example:

ScStatus status = scConnect();
if (status == SC_OK)
   printf("connected\n");
else
   printf("error\n");

Returns: SC_OK, SC_COMMUNICATION_ERROR

References SC_COMMUNICATION_ERROR, and SC_OK.

Referenced by scConnect2().

◆ scConnect2()

ScStatus scConnect2	(	bool	isAlwaysReceivingData,
		char *	applName
	)

Establishes the connection to the SpaceControl daemon.

If this function is not executed successfully no other DLL functions can be used.
Two parameters can be handed over:

isAlwaysReceivingData controls the driver's behaviour concerning your application's foreground status. If set to true your application will receive the standard data set even if it is not in the foreground. If set to false your application will not receive these data any longer as soon it is not the topmost application.
applName is your application's binary name (without the ".exe" extension) and is only important if your application is a so called "supported application". [See chapter 3.4.2 of the user manual. You can change your application to be a supported one by adding an appropriate line into the file "daemon.ini". This file is located in the folder "SpaceController" in the user's home directory. See function scSetState2() for further details.]
If you do not want to use this feature set applName to NULL.

Due to security riscs it is not possible to connect to a daemon started by another user as the one who started the application which has loaded the DLL; error SC_WRONG_USER is returned in this case.

Example:

ScStatus status = scConnect2(false, NULL);
if (status == SC_OK)
   printf("connected\n");
else
   printf("error\n");

Parameters

isAlwaysReceivingData	if false the application will receive the standard data set only if it is in the foreground
applName	your application's name; only needed if your application is a "supported application"; set it to NULL otherwise

Returns: SC_OK, SC_PARAMETER_OUT_OF_RANGE, SC_COMMUNICATION_ERROR, SC_WRONG_USER

References MAX_STR_LEN, SC_OK, SC_PARAMETER_OUT_OF_RANGE, scConnect(), scSetState(), and UNNAMED_TRNS.

◆ scDisconnect()

ScStatus scDisconnect ( )

Closes the connection to the SpaceControl daemon.

The daemon will destroy its proxy objects when receiving this message.
Example:

ScStatus status = scDisconnect();
if (status == SC_OK)
   printf("disconnected\n");
else
   printf("error\n");

Returns: SC_OK, SC_COMMUNICATION_ERROR

References SC_OK.

◆ scGetDaemonPar()

ScStatus scGetDaemonPar	(	int	par,
		int *	val
	)

Retrieves one of the integer or boolean parameters available in the Daemon's configuration file "daemon.ini".

Which one is requested is controlled by the first parameter par. It can have one of the values given in the enumeration DaemonPar. Boolean parameters are returned as 0 for false and 1 for true.
String parameters are not accessible for the time being.
Example:

bool     val;
ScStatus status = scGetDaemonPar(ENABLE_LEGACY_COM1, &val);
if (status == SC_OK)
   printf("success\n");
else
   printf("error\n");

Parameters

par	the parameter you want to retrieve as defined in enumeration DaemonPar

Return values

val	the parameter's current value

Returns: SC_OK, SC_COMMUNICATION_ERROR

References SC_COMMUNICATION_ERROR, and SC_OK.

◆ scGetDmnVrsn()

ScStatus scGetDmnVrsn	(	char *	versionP,
		char *	pathP
	)

Retrieves the SpaceControl daemon's software version and its binary name and path.

Example:

char     version[MAX_VERSION_LEN];
char     path[MAX_FILENAME_LEN];
ScStatus status = scGetDmnVrsn(version, path);
if (status == SC_OK)
   printf("the daemon's version is %s\n", version);
else
   printf("error\n");

Return values

versionP	pointer to the memory the version string is to be copied
pathP	pointer to the memory the version string is to be copied

Returns: SC_OK, SC_COMMUNICATION_ERROR

References MAX_FILENAME_LEN, MAX_VERSION_LEN, SC_COMMUNICATION_ERROR, and SC_OK.

◆ scGetFgAppl()

ScStatus scGetFgAppl	(	char *	fgApplNameP,
		char *	fgApplStateP
	)

Retrieves the name and potentially the state of the foreground application.

The daemon checks regularly which application is in the foreground. With this information the daemon loads automatically the appropriate configuration.
Some applications are better integrated into the daemon than others. These "supported applications" can tell its inner state, Pro/ENGINEER tells e. g. the mode ("drawing", "part" etc.) it is in. This state is returned in the second argument.
The foreground application's name (what is this?) is not easy to determine: You see the application's window, and you can get its so called window identifier. The task is to get an unambiguous application name out of this number, and that should work for all operating systems. The daemon uses the following strategy: Try to get the application's binary file name out of the window identifier and deliver this as the application's name. If this fails (this may happen under Linux because there is no direct connection between the window identifier and the application since the X server creates the window and not the application itself, and because the binary name may not be unambiguous [e.g. all Java applications are under control of the same runtime executable]) the window title is used as application name. Be aware that this is ambiguous too; many applications name their windows according to some content of the window and not to the application's name. Example:

char      fgApplicationName [MAX_APPL_NAME_LEN];
char      fgApplicationState[MAX_APPL_STATE_LEN];
ScStatus  status = scGetFgAppl(fgApplicationName, fgApplicationState);
if (status == SC_OK)
   printf("foreground application: %s\n", fgApplicationName);
else
   printf("error\n");

Return values

fgApplNameP	pointer to the actual foreground application's name
fgApplStateP	pointer to the actual foreground application's state

Returns: SC_OK, SC_COMMUNICATION_ERROR

References MAX_APPL_NAME_LEN, MAX_APPL_STATE_LEN, SC_COMMUNICATION_ERROR, and SC_OK.

◆ scSetDaemonPar()

ScStatus scSetDaemonPar	(	int	par,
		int *	val
	)

Sets one of the integer or boolean parameters available in the Daemon's configuration file "daemon.ini".

Which one is to be set is controlled by the first parameter par. It can have one of the values given in the enumeration DaemonPar. Boolean parameters are handed over as 0 for false ("off") and 1 for true ("on").
String parameters are not accessible for the time being.
Example:

bool     val    = true;
ScStatus status = scSetDaemonPar(ENABLE_LEGACY_COM1, &val);
if (status == SC_OK)
   printf("success\n");
else
   printf("error\n");

Parameters

par	the parameter you want to set as defined in enumeration DaemonPar

Return values

val	the parameter's new value

Returns: SC_OK, SC_COMMUNICATION_ERROR

References SC_COMMUNICATION_ERROR, and SC_OK.

◆ scSetState()

ScStatus scSetState	(	char *	str1,
		char *	str2
	)

Deprecated:: This function is replaced by scSetState2() and should not be used any longer.

Informs the daemon about the internal state (mode) of a supported application. The daemon will load the appropriate configuration file. See also scGetFgAppl().
Example:

char*    str1   = "ProEngineer"; // the application's name as known to the daemon
char*    str2   = "Assembly";    // the mode the application is in
ScStatus status = scSetState(str1, str2);
if (status == SC_OK)
   printf("success\n");
else
   printf("this can not happen\n");

This function is also used to tell the daemon the name of the application when the parameter str2 is set to "initializing". In this case the parameter str1 is put into the list of communication partners, and the daemon can identify this application. If the daemon knows an application by name it will stop sending data to it when it is not in the foreground any longer. An application not known to the daemon will always receive data whether it is in the foreground or not.
So, if you don't want getting data into your application when in background: Figure out how the daemon will identify your application by starting the control panel and getting your application into the foreground. The control panel prints the identifier in the status bar besides the label "Active Application:"; say, it states "MyApplication". Insert a statement
status = scState("MyApplication", "initializing");
into your code after your scConnect(), and the daemon knows to send data to your application only when it is in the foreground.
New extension since version 2.0.0:
To avoid sending data to a second instance of the same application (which has the same application name) you will have to provide the daemon with the process id of each instance. Append it to the application name, separated by a semicolon. Example with process id 1234:
status = scState("MyApplication;1234", "initializing");
You have to retrieve your processe's id at runtime, of course. See the Win32 API function GetCurrentProcessId().
Sorry for this unhandy interface; as you can see it is cobbled together a little.

Parameters

str1	name of the supported application
str2	state (mode) the supported application is in

Returns: SC_OK, SC_PARAMETER_OUT_OF_RANGE, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_APPL_NOT_FOUND, SC_WRONG_USER

References MAX_STR_LEN, SC_APPL_NOT_FOUND, SC_COMMUNICATION_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, SC_WRONG_DEVICE_INDEX, and SC_WRONG_USER.

Referenced by scConnect2().

◆ scSetState2()

ScStatus scSetState2 ( char * state )

Informs the daemon about the internal state (mode) of a supported application.

The driver will load the appropriate configuration file. The following conditions must be fulfilled that the driver can do this:

There must be an entry in the section [SUPP_APPLS] in the driver's initialization file "SpaceController/daemon.ini" in the user's home directory. Place an entry in this section, and your application will be recognized as a supported one. Example:

ProEngineerWF4 = proe_wf4_plugin.exe xtopWF4 # comment
As you can see a line in this section consists of four parts:
- The part before the equal sign is the application's name as it will appear in the SpaceController's display. The same string is displayed in the SpaceControl Panel's status bar to identify the application.
  Example: "ProEngineerWF4".
- The second part is the first word after the equal sign. It can be the name of a binary (plug-in) which the driver starts as soon as your application comes into the foreground.
  Example: "proe_wf4_plugin.exe".
  If the plug-in is a DLL place a dummy name there.
- The third part is the binary name of your application (without the ".exe" extension). The driver checks for this binary to be the foreground application.
  Example: "xtopWF4" - xtopWF4.exe is the binary of Pro/ENGINEER Wildfire 4.
- The fourth part is a comment starting with a hash character and can be omitted.
You must have provided the driver with your application's binary name (without the ".exe" extension) in function scConnect2().
Example: scConnect2(false, "ProEngineerWF4").
There must be a directory with the same name as your application in the folder "<userName>\SpaceController\Devices\<DeviceSerialNo>\".
Example: "C:\Users\billy\SpaceController\Devices\DC1UWX09190021T\ProEngineerWF4\".
In this folder must be a configuration file with the same name as the state but with the extension "*.cfg".
Example: "Assembly.cfg".

Example:

char*    state  = "Assembly";    // the mode the application is in
ScStatus status = scSetState2(state);
if (status == SC_OK)
   printf("success\n");
else
   printf("error\n");

Parameters

state state (mode) the supported application is in

Returns: SC_OK, SC_PARAMETER_OUT_OF_RANGE, SC_COMMUNICATION_ERROR, SC_WRONG_DEVICE_INDEX, SC_APPL_NOT_FOUND

References MAX_STR_LEN, SC_APPL_NOT_FOUND, SC_COMMUNICATION_ERROR, SC_OK, SC_PARAMETER_OUT_OF_RANGE, and SC_WRONG_DEVICE_INDEX.

◆ scStop()

ScStatus scStop ( )

Sends the SpaceControl Daemon a stop message, the process finishes itself after sending an OK message.

Example:

ScStatus status = scStop();
if (status == SC_OK)
   printf("stopped\n");
else
   printf("error\n");

Returns: SC_OK, SC_COMMUNICATION_ERROR

References SC_COMMUNICATION_ERROR, and SC_OK.

Functions

Detailed Description

Function Documentation

◆ scConnect()

◆ scConnect2()

◆ scDisconnect()

◆ scGetDaemonPar()

◆ scGetDmnVrsn()

◆ scGetFgAppl()

◆ scSetDaemonPar()

◆ scSetState()

◆ scSetState2()

◆ scStop()