Script Class Reference

This class defines the API of the ScriptObject (so).

#include <script.h>

Public Slots
Message related functions.
void	sendCommand (QString strCommand)
	Sends a special, receiver specific command.
void	sendCommand (QString strTarget, QString strCommand)
	Sends a special, receiver specific command.
void	sendCommand (QString strTarget, QString strCommand, QString strMetadata)
	Sends a special, receiver specific command.
void	sendMessage (QString strPayload)
	Sends a message.
void	sendMessage (QString strTarget, QString strPayload)
	Sends a message.
void	sendMessage (QString strTarget, QString strPayload, QString strMetadata)
	Sends a message.
void	sendMessage (QString strTargetProject, QString strTarget, QString strPayload, QString strMetadata)
	Sends a message.
void	sendResponse (QString strPayload)
	Sends a response message.
void	sendResponse (QString strTarget, QString strPayload)
	Sends a response message.
void	sendResponse (QString strTarget, QString strPayload, QString strMetadata)
	Sends a response message.
Environment related functions.
void	useMSecsSinceEpochTimeStamp (bool bMsSinceEpoch)
	Causes kbLogger to call the processMessage method in the script with an integer representing the ms since epoch as a time stamp.
Timer related functions.
int	timerCreate (QString strCallback, QString strParam)
	Creates a timer.
void	timerRemove (int iTimer)
	Removes a timer.
void	timerRestart (int iTimer, int iMs)
	Restarts a timer.
void	timerStartCyclic (int iTimer, int iMs)
	Starts a cyclic timer.
void	timerStartSingle (int iTimer, int iMs)
	Starts a single shot timer.
void	timerStop (int iTimer)
	Stops a timer.
void	triggerWatchdog ()
	Prevent the internal Watchdog from from throwing the timeout error.
ConfigItems related functions.
unsigned int	configItemCountReceiver (QString strTarget)
	Counts ConfigItems which are receivers from this one.
unsigned int	configItemCountSender (QString strSource)
	Counts ConfigItems which are senders to this one.
ConfigItem *	configItem (QString strConfigItem)
	Returns a config item which is a receiver or sender connected to this one.
Callback related functions.
int	callbackCreate (QString strPayload, QString strCallback)
	Creates a callback function.
int	callbackCreate (QString strPayload, QString strMetadata, QString strCallback)
	Creates a callback function.
void	callbackRemove (int iCallback)
	Removes a callback function.
Script execution related functions.
ScriptValue	extractVariable (QString strText, QString strDelimiter, QString strVariableName)
	Extracts a variable from the given text.
ScriptValue	getTimestamp ()
	Returns the actual time stamp.
void	sleep (quint64 ms)
	Halts the execution of the script for a given time.
void	log (QString strText)
	Sends the given text to the log window.
void	trace (QString strText)
	Sends the given text to the trace window.
Project related functions.
QString	projectDir ()
	Returns the full qualified name of the project path.
ProjectExplorer *	projectExplorer ()
	Returns the ProjectExplorer object as void pointer (for usage in scripts).
kbLogger related functions related functions.
void	closeLogger (int exitCode)
	Closes the complete logger application.
Process related functions.
qint32	processOpen (QString strEcecutable, QString strWorkingDir="")
	Opens an external processes.
void	processSetParameter (qint32 hProcess, QString strParameter)
	Appends a command line parameter to a process.
bool	processStart (qint32 hProcess, bool bStartDetached=true)
	Starts a process.
void	processClose (qint32 hProcess)
	Closes an external process.
void	processCloseAll ()
	Close all external processes.
File related functions.
bool	fileExists (QString strFile)
	Checks if a file exists.
void *	fileOpen (QString strFile, QString strMode="rw")
	Opens a file.
quint64	fileWrite (void *pFile, QString strText)
	Writes to a file.
QString	fileRead (void *pFile, quint64 length)
	Reads from a file.
QString	fileReadLine (void *pFile)
	Reads from a file a single line.
bool	fileSeek (void *pFile, quint64 pos)
	Sets the current position in a file.
bool	fileAtEnd (void *pFile)
	Retrieves true if the actual file position is at the end.
quint64	fileSize (void *pFile)
	Retrieves the size of the file.
void	fileClose (void *pFile)
	Closes a file.
void	fileCloseAll ()
	Closes all files.
bool	fileRemove (QString strFile)
	Removes the file.

Public Member Functions
void	startWatchdog ()
void	stopWatchdog ()

Member Function Documentation

callbackCreate [1/2]

int callbackCreate ( QString strPayload, QString strCallback )

slot

Creates a callback function and registers it in the java script interpreter. This function is called every time, a message arrives at the SciptObject and its payload causes a match in the regular expression in strPayload.

Example:

var myCallback = so.callbackCreate("^Error", "myErrorFunction");
 
function myErrorFunction(strTimesatmp, strSource, strPayload, strMetadata)
{
}

Parameters

strPayload	A string containing a regular expression to test again the payload of every arrived message.
strCallback	The name of the user defined callback function to call.

Returns

A handle to the callback.

callbackCreate [2/2]

int callbackCreate ( QString strPayload, QString strMetadata, QString strCallback )

slot

Creates a callback function and registers it in the java script interpreter. This function is called every time, a message arrives at the SciptObject and its payload and its meta data causes a match in the regular expression in strPayload and in strMetadata.

Example:

var myCallback = so.callbackCreate("^Error", "DLC=8", "myErrorFunction");
 
function myErrorFunction(strTimesatmp, strSource, strPayload, strMetadata)
{
}

Parameters

strPayload	A string containing a regular expression to test the payload of every arrived message.
strMetadata	A string containing a regular expression to test the meta data of every arrived message.
strCallback	The name of the user defined callback function to call.

Returns

A handle to the callback.

callbackRemove

void callbackRemove ( int iCallback )

slot

Removes a callback function from the internal list. That means the callback function is not called anymore, even if the source code is contained in the java script file.

Example:

var myCallback = so.callbackCreate("^Error", "myErrorFunction");
 
so.callbackRemove(myCallback);

Parameters

iCallback

The handle of the callback function to be removed.

closeLogger

void closeLogger ( int exitCode )

slot

Parameters

exitCode

Closes the complete logger application.

configItem

ConfigItem * configItem ( QString strConfigItem )

slot

Returns a config item which is a receiver or sender connected to this one. At first the receivers are searched, then the senders.

Example

var configItem = so.configItem("myNeighbour");

Parameters

strConfigItem

A string with a regular expression to match the AliasNames of the connected ConfigItems.

Returns

A handle to the first found ConfigItem.

configItemCountReceiver

unsigned int configItemCountReceiver ( QString strTarget )

slot

Counts ConfigItems which are receivers from this one.

Example

var receivers = so.configItemCountReceiver("myReceiver");

Parameters

strTarget

A string with a regular expression to match the AliasNames of the connected ConfigItems.

Returns

The number of found ConfigItems.

configItemCountSender

unsigned int configItemCountSender ( QString strSource )

slot

Counts ConfigItems which are senders to this one.

Example

var sender = so.configItemCountSender("mySender");

Parameters

strSource

A string with a regular expression to match the AliasNames of the connected ConfigItems.

Returns

The number of found ConfigItems.

extractVariable

ScriptValue extractVariable ( QString strText, QString strDelimiter, QString strVariableName )

slot

Extracts a variable from the given text.

Example

var length=so.extractVariable("This text contains variables length=100,width=50", ",", "length");
so.trace("length=" + length);

Parameters

strText	The text which contains the variables.
strDelimiter	The regular expression which separates the variables.
strVariableName	The name of the variable to search.

Returns

The content of the variable in case of success, otherwise an undefined value.

fileAtEnd

bool fileAtEnd ( void * pFile )

slot

Retrieves true if the actual file position is at the end.

Example

var fFileTestParameter = so.fileOpen("/path/to/my/file");
 
if(so.fileAtEnd(fFileTestParameter))
{
     trace("file is at its end");
}

Parameters

pFile

A handle to the file.

Returns

true if the actual position is at the file end.

fileClose

void fileClose ( void * pFile )

slot

Closes one file.

Example

var fFileTestResults = so.fileOpen("/path/to/my/file");
so.fileWrite(fFileTestResults, "passed");
so.fileClose(fFileTestResults);

Parameters

pFile

A handle to the file to close.

fileCloseAll

void fileCloseAll ( )

slot

Closes all files.

Example

so.fileCloseAll();

fileExists

bool fileExists ( QString strFile )

slot

Checks if a file exists.

Example

if(so.fileExists("/path/to/my/file")
    so.trace("File exists");

Parameters

strFile

The file to check.

Returns

true if the file exists, otherwise false.

fileOpen

void * fileOpen ( QString strFile, QString strMode = "rw" )

slot

Opens a file in read and/ or write mode. If the file does not exits and the file mode contains write access, the file will be created.

Example

var fFileTestResults = so.fileOpen("/path/to/my/file");
so.fileWrite(fFileTestResults, "passed");
so.fileClose(fFileTestResults);

Parameters

strFile	The file to read and write.
strMode	The access mode. Valid is "r", "w", "rw".

Returns

The file handle.

fileRead

QString fileRead ( void * pFile, quint64 length )

slot

Reads from the given file. The position to read can be set by fileSeek.

Example

var fFileTestParameter = so.fileOpen("/path/to/my/file");
var strTestParameter = so.fileRead(fFileTestParameter, 30);
so.fileClose(fFileTestParameter);
 
switch(strTestParameter)
{
   case "case1":
     trace("starting test case1");
     break;
}

Parameters

pFile	The file handle.
length	Amount of text to read in bytes.

Returns

fileReadLine

QString fileReadLine ( void * pFile )

slot

Reads from a file a single line.

Example

var fFileTestParameter = so.fileOpen("/path/to/my/file");
var strTestParameter = so.fileReadLine(fFileTestParameter;
so.fileClose(fFileTestParameter);
 
switch(strTestParameter)
{
   case "case1":
     trace("starting test case1");
     break;
}

Parameters

pFile

The file handle.

Returns

fileRemove

bool fileRemove ( QString strFile )

slot

Removes the file from the hard disk.

Example

var fFileTestResults = so.fileOpen("/path/to/my/file");
so.fileWrite(fFileTestResults, "passed");
so.fileClose(fFileTestResults);
so.fileRemove("/path/to/my/file");

Parameters

strFile

The file to delete.

Returns

True if successful.

fileSeek

bool fileSeek ( void * pFile, quint64 pos )

slot

Sets the current position to pos.

Example

var fFileTestParameter = so.fileOpen("/path/to/my/file");
 
if(so.fileSeek(fFileTestParameter, 4))
{
     var strTestParameter = so.fileRead(fFileTestParameter, 1);
     so.fileClose(fFileTestParameter);
 
     switch(strTestParameter)
     {
         case "1":
             trace("starting test case1");
             break;
     }
}

Parameters

pFile	A handle to the file.
pos	The new read/write position.

Returns

fileSize

quint64 fileSize ( void * pFile )

slot

Retrieves the size of the file.

Parameters

pFile

The file handle.

Returns

The current size of the file.

fileWrite

quint64 fileWrite ( void * pFile, QString strText )

slot

Writes the given text to the given file. The position to write can be set by fileSeek.

Example

var fFileTestResults = so.fileOpen("/path/to/my/file");
so.fileWrite(fFileTestResults, "passed");
so.fileClose(fFileTestResults);

Parameters

pFile	The file handle.
strText	The text to write to the file.

Returns

getTimestamp

ScriptValue getTimestamp ( )

slot

Returns the actual time stamp.

Example

var timestamp=so.getTimestamp();

Returns

The actual time stamp.

log

void log ( QString strLog )

slot

Sends the given text to the log window.

Example

so.log("This text will appear in the log window");

Parameters

strLog

The text to log.

processClose

void processClose ( qint32 hProcess )

slot

Closes the given process. The external process is killed.

Example

var procResultViewer = so.processOpen("C:/Program Files (x86)/Microsoft Office/Office14/EXCEL.EXE");
 
so.processSetParameter(procResultViewer, "/e");
so.processSetParameter(procResultViewer, "/p");
so.processSetParameter(procResultViewer, so.projectDir());
so.processSetParameter(procResultViewer, strSheetTestResults);
 
so.processStart(procResultViewer);
 
so.processClose(procResultViewer);

Parameters

hProcess

The process handle.

processCloseAll

void processCloseAll ( )

slot

Closes all processes. All external processes are killed.

Example

var procResultViewer = so.processOpen("C:/Program Files (x86)/Microsoft Office/Office14/EXCEL.EXE");
 
so.processSetParameter(procResultViewer, "/e");
so.processSetParameter(procResultViewer, "/p");
so.processSetParameter(procResultViewer, so.projectDir());
so.processSetParameter(procResultViewer, strSheetTestResults);
 
so.processStart(procResultViewer);
 
so.processCloseAll();

processOpen

qint32 processOpen ( QString strExecutable, QString strWorkingDir = "" )

slot

Opens an external process object, but does not start it.

Example:

var proc = so.processOpen("excel", "c:/path/to/working/dir");
so.processSetParameter(proc, "Param1");
so.processSetParameter(proc, "Param2");
so.processStart(proc);
so.processClose(proc);

Parameters

strExecutable	The executable to start.
strWorkingDir	Sets the working directory. If the is parameter is empty or not given, the project directory is used instead.

Returns

A handle to the process object.

processSetParameter

void processSetParameter ( qint32 hProcess, QString strParameter )

slot

Appends a start parameter to the parameter list of the given process.

Example

var procResultViewer = so.processOpen("C:/Program Files (x86)/Microsoft Office/Office14/EXCEL.EXE");
 
so.processSetParameter(procResultViewer, "/e");
so.processSetParameter(procResultViewer, "/p");
so.processSetParameter(procResultViewer, so.projectDir());
so.processSetParameter(procResultViewer, strSheetTestResults);
 
so.processStart(procResultViewer);
 
so.processClose(procResultViewer);

Parameters

hProcess	The process handle.
strParameter	The parameter.

processStart

bool processStart ( qint32 hProcess, bool bStartDetached = true )

slot

Starts the external process attached or detached. An attached process will be closed together with kbLogger. If the bStartDetached parameter is missing, the default value [true] is used.

Example

var procResultViewer = so.processOpen("C:/Program Files (x86)/Microsoft Office/Office14/EXCEL.EXE");
 
so.processSetParameter(procResultViewer, "/e");
so.processSetParameter(procResultViewer, "/p");
so.processSetParameter(procResultViewer, so.projectDir());
so.processSetParameter(procResultViewer, strSheetTestResults);
 
so.processStart(procResultViewer);
 
so.processClose(procResultViewer);

Parameters

hProcess	The process handle.
bStartDetached	True [default] if the process shall be started.

Returns

True in case of attached process. In case of a detached process, the return code is true in case of success or false in case if failure.

projectDir

QString projectDir ( )

slot

Returns the full qualified project path.

Example This Example opens a excel sheet in the project directory.

var procResultViewer = so.processOpen("C:/Program Files (x86)/Microsoft Office/Office14/EXCEL.EXE");
 
so.processSetParameter(procResultViewer, "/e");
so.processSetParameter(procResultViewer, "/p");
so.processSetParameter(procResultViewer, so.projectDir());
so.processSetParameter(procResultViewer, strSheetTestResults);
 
so.processStart(procResultViewer);

Returns

The project path.

projectExplorer

ProjectExplorer * projectExplorer ( )

slot

Returns handle to the ProjectExplorer.

Example This Example shows how to open a new project from within a master project.

var projectExplorer = so.projectExplorer();
 
projectExplorer.openProject("/my/very/new/test/project.klp");

Returns

The handle to the project explorer object.

sendCommand [1/3]

void sendCommand ( QString strCommand )

slot

Sends a special, receiver specific command. This command is send as a broadcast to every receivers of this Script.

Example

so.sendCommand("play");

Parameters

strCommand

A string which contains the command which is interpreted by every receiver.

sendCommand [2/3]

void sendCommand ( QString strTarget, QString strCommand )

slot

Sends a special, receiver specific command. This command is not send as a broadcast to every receivers of this Script. Instead the receiver is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching receiver is called.

Example

so.sendCommand("myConfigItem", "play");

Parameters

strTarget	The receiver of this command message.
strCommand	A string which contains the command which is interpreted by the receiver.

sendCommand [3/3]

void sendCommand ( QString strTarget, QString strPayload, QString strCommand )

slot

Sends a special, receiver specific command. This command is not send as a broadcast to every receivers of this Script. Instead the receiver is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching receiver is called.

Example

so.sendCommand("myConfigItem", "track=1", "play");

Parameters

strTarget	The receiver of this command message.
strPayload	The user data for this command.
strCommand	A string which contains the command which is interpreted by the receiver.

sendMessage [1/4]

void sendMessage ( QString strPayload )

slot

Sends a message.

Example

so.sendMessage("my personal message");

This message is send as a broadcast to every receivers of this Script.

Parameters

strPayload

The user data for this message.

sendMessage [2/4]

void sendMessage ( QString strTarget, QString strPayload )

slot

Sends a message. This message is not send as a broadcast to every receivers of this Script. Instead the receiver is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching receiver is called.

Example

so.sendMessage("myConfigItem", "my personal message");

Parameters

strTarget	The receiver of this message.
strPayload	The user data for this message.

sendMessage [3/4]

void sendMessage ( QString strTarget, QString strPayload, QString strMetadata )

slot

Sends a message. This message is not send as a broadcast to every receivers of this Script. Instead the receiver is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching receiver is called.

Example

so.sendMessage("myConfigItem", "my personal message", "additional data");

Parameters

strTarget	The receiver of this message.
strPayload	The user data for this message.
strMetadata	Additional data for this message. This can be the message type, communication channel or others.

sendMessage [4/4]

void sendMessage ( QString strTargetProject, QString strTarget, QString strPayload, QString strMetadata )

slot

Sends a message. This message is not send as a broadcast to every receivers of this Script. Instead the receiver is searched by name in the target project and, if found, called directly. The names of the target project and the target item has to equal to the given parameters. If the target project is set to BROADCAST, all currently loaded projects will receive that message. Example

so.sendMessage("anotherProject", "myConfigItem", "my personal message", "additional data");

Parameters

strTargetProject	The receiver project of this message.
strTarget	The receiver ConfigItem of this message.
strPayload	The user data for this message.
strMetadata	Additional data for this message. This can be the message type, communication channel or others.

sendResponse [1/3]

void sendResponse ( QString strPayload )

slot

Sends a response. A response is send in reverse arrow direction. This message is send as a broadcast to every sender of this Script.

Example

so.sendResponse("my personal response");

Parameters

strPayload

The user data for this message.

sendResponse [2/3]

void sendResponse ( QString strTarget, QString strPayload )

slot

Sends a response. A response is send in reverse arrow direction. This message is not send as a broadcast to every sender of this Script. Instead the sender is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching sender is called.

Example

so.sendResponse("myConfigItem", "my personal response");

Parameters

strTarget	The receiver of this message.
strPayload	The user data for this message.

sendResponse [3/3]

void sendResponse ( QString strTarget, QString strPayload, QString strMetadata )

slot

Sends a response. A response is send in reverse arrow direction. This message is not send as a broadcast to every sender of this Script. Instead the sender is searched in the list of connected ConfigItems and if found, called directly. Only the fist matching sender is called.

Example

so.sendResponse("myConfigItem", "my personal response", "additional data");

Parameters

strTarget	The receiver of this message.
strPayload	The user data for this message.
strMetadata	Additional data for this message. This can be the message type, communication channel or others.

sleep

void sleep ( quint64 ms )

slot

Halts the execution of the script for a given time.

Example

so.sleep(100);

Parameters

ms	The time in milliseconds to halt the execution.

startWatchdog()

void startWatchdog

(

)

Starts the Watchdog for this ScriptObject.

Example

so.startWatchdog();

stopWatchdog()

void stopWatchdog

(

)

Stops the Watchdog for this ScriptObject.

Example

so.stopWatchdog();

timerCreate

int timerCreate ( QString strCallback, QString strParam )

slot

Creates a timer. By using the parameter strParam it's possible to use a single callback function for different timers.

Example

var timer1 = so.timerCreate("onTimerElapsed", "timer1");
var timer2 = so.timerCreate("onTimerElapsed", "timer2");
 
so.timerStartSingle(timer1, 1000);
so.timerStartSingle(timer2, 2000);
 
function onTimerElapsed(strParam)
{
     trace("onTimerElapsed: " + strParam + " elapsed");
}

Parameters

strCallback	The name of the function to call when the timer elapsed.
strParam	A (constant) parameter to handing over to the callback function.

Returns

A handle to the timer object.

timerRemove

void timerRemove ( int iTimer )

slot

Removes a timer.

Example

var timer1 = so.timerCreate("onTimerElapsed", "timer1");
var timer2 = so.timerCreate("onTimerElapsed", "timer2");
 
so.timerStartSingle(timer1, 1000);
so.timerStartSingle(timer2, 2000);
 
function onTimerElapsed(strParam)
{
     trace("onTimerElapsed: " + strParam + " elapsed");
 
     if(strParam == "timer2)
         so.timerRemove(timer1);
}

Parameters

iTimer

The handle of the timer to be removed.

timerRestart

void timerRestart ( int iTimer, int iMs )

slot

Restarts a timer but does not change its type (single or cyclic timer).

Example

var timer1Value = 100;
var timerIncreaseValue = 100;
var timer1 = so.timerCreate("onTimerElapsed", "timer1");
 
so.timerStartSingle(timer1, 1000);
 
function onTimerElapsed(strParam)
{
     trace("onTimerElapsed: " + strParam + " elapsed");
     timer1Value += timerIncreaseValue;
     so.timerRestart(timer1, timer1Value);
}

Parameters

iTimer	The handle to the timer.
iMs	The timeout value in milliseconds.

timerStartCyclic

void timerStartCyclic ( int iTimer, int iMs )

slot

Starts a timer as cyclic timer.

Example

var timer1 = so.timerCreate("onTimerElapsed", "timer1");
 
so.timerStartCyclic(timer1, 1000);

Parameters

iTimer	The handle to the timer.
iMs	The timeout value in milliseconds.

timerStartSingle

void timerStartSingle ( int iTimer, int iMs )

slot

Starts a timer as single shot timer.

Example

var timer1 = so.timerCreate("onTimerElapsed", "timer1");
 
so.timerStartSingle(timer1, 1000);

Parameters

iTimer	The handle to the timer.
iMs	The timeout value in milliseconds.

timerStop

void timerStop ( int iTimer )

slot

Stops a timer.

Example

var timer1Value = 100;
var timerIncreaseValue = 100;
var timer1EndValue = 1000;
var timer1 = so.timerCreate("onTimerElapsed", "timer1");
 
so.timerStartSingle(timer1, 1000);
 
function onTimerElapsed(strParam)
{
     trace("onTimerElapsed: " + strParam + " elapsed");
     timer1Value += timerIncreaseValue;
     so.timerRestart(timer1, timer1Value);
 
     if(timer1EndValue < timer1Value)
         so.timerStop(timer1);
}

Parameters

iTimer

The handle to the timer.

trace

void trace ( QString strText )

slot

Sends the given text to the trace window.

Example

so.trace("This text will appear in the trace window");

Parameters

strText

The text to trace.

triggerWatchdog

void triggerWatchdog ( )

slot

Triggers the Watchdog for this ScriptObject.

Each ScriptObject, TestObject, TranslatorObject and UserInterface has their own Watchdog. If the user script does not return after 1s, an JavaScript exception is thrown and the script is canceled. To avoid that and let the kbLogger internal events gets handled, the user needs to call this function periodically.

Example

so.triggerWatchdog();

useMSecsSinceEpochTimeStamp

void useMSecsSinceEpochTimeStamp ( bool bMsSinceEpoch )

slot

Causes kbLogger to call the processMessage method in the script with an integer representing the ms since epoch as a time stamp. Without this call, the ScriptObject is using a string in this format: "YYYY.MM.DD HH:mm:ss:ms" .

Example

so.timerCreate("onTimerElapsed", "timer1");
var timer2 = so.timerCreate("onTimerElapsed", "timer2");
 
so.useMSecsSinceEpochTimeStamp(true);
so.timerStartSingle(timer2, 2000);
 
function onTimerElapsed(strParam)
{
     trace("onTimerElapsed: " + strParam + " elapsed");
}

Parameters

bMsSinceEpoch

Set this to true, if you want to use time stamps to be ms since epoch.