Docs Image

[EUC Score Toolset Documentation Start Page]

Simload Software Development Kit (SDK)

The Install-SDK package includes libraries, tools and sample code needed to build your own Simloads.

Prerequisites

Components required for using the Simload SDK.

Design Guidelines

Simload code design principles and conventions.

Code Samples

Simload examples with references to all required source files.

Prerequisites

The Simload Install-SDK package includes sample code, libraries, icons and some extra tools. It requires the Install-EUCScore package to be installed on the target machine. The preferred development environment for EUC Score Simloads is Visual Studio Code plus extensions.

Visual Studio Code

Visual Studio Code is a lightweight source code editor which is available for Windows. It has a rich ecosystem of extensions for other languages and runtimes, such as PowerShell, AutoIt and Inno Setup.

AutoIt Scripting Language

An installed AutoIt v3 is a prerequisite for the Simload SDK. AutoIt is a freeware BASIC-like scripting language designed for automating the Windows GUI and general scripting. It uses a combination of simulated keystrokes, mouse movement and window control manipulation. AutoIt is very small and only consumes minimal system resources. Scripts can be compiled into self-contained executables that include all runtime components and run on all versions of Windows out-of-the-box. In addition to the runtime components, the AutoIt install package includes the SciTE editor that provides syntax highlighting.

The AutoIt extension for Visual Studio Code replaces the SciTE editor, but still requires the installed AutoIt development environment, including the compiler. In Visual Studio Code, search for the AutoIt extension by Damien and install it. By default, the extension is set up for the default installation of AutoIt on a 64-bit system. For alternate setups, you can change the configuration by navigating to File-> Preferences-> Settings.

 

AutoIt

 

Inno Setup Installer

Another Simload SDK prerequisite is an installed Inno Setup. It is a free installer for Windows programs by Jordan Russell and Martijn Laan, allowing the creation of a single EXE for easy online distribution. An important feature is the installation of 64-bit applications on the 64-bit editions of Windows. Both administrative and non administrative installations are supported as well as the creation of registry and INI entries. For details, see Inno Setup Help

The Inno Setup extension for Visual Studio Code provided by idleberg is a language syntax, snippets and build system for Inno Setup. Before you can build an Inno Setup package, make sure the compiler ISCC is in your PATH environmental variable. Alternatively, you can specify the path to ISCC in your user settings. To trigger a build, select "Inno Setup: Save & Compile Script" from the command-palette or use the default keyboard shortcut SHIFT+ALT+B.

 

Inno Setup

 

IMPORTANT NOTE: The development of custom Simloads does not rely on Visual Studio Code, AutoIt and Inno Setup! For the Simload code, any programming language is suitable that can be compiled into a Windows executable and that allows to manipulate Windows programs, text files and registry entries. Creating an installation package with Inno Setup is also optional as a copy and paste deployment of Simloads is supported.

Design Guidelines

The code behind each EUC Simload is separated into multiple modules. A type 1 Simload located in Simloads\<GroupName> has a main code file named SL1-<SimloadName>.au3. An include or library file located in the same folder — named Lib-<SimloadName>.au3 — contains Simload-specific functions. The purpose of these functions is to provide a mechanism to reuse code for Simload-specific user actions in type 2 Simloads (= Personas).

Another mandatory module located in the same folder is the SL1-<SimloadName>.ini file. This side-by-side .ini file can be used to overwrite the hard-coded Simload default settings as defined in the main code file. It also acts as a fallback in case general Simload settings and folder locations are not stored in the registry.

The general include or library file LibSimloads.au3 located in the Libs folder contains a spectrum of common functions: Main Functions, Temp Object Functions, Process Functions and App Functions. Many of the functions write to or read from a Temporary Simload Object. The code in LibSimloads.au3 follows the design guidelines of AutoIt User Defined Functions (UDFs).

 

Simload-Specific Functions in Simloads\<GroupName>\Lib-<SimloadName>.au3

  • _SimLoad_<SimloadName>Init
    Initialize a Simload. Examples are adding user-specific settings in the registry or in configuration files.
  • _SimLoad_<SimloadName>RunAction
    Run a sequence of individual user actions after a Simload was started in run mode or without any command-line parameter until the predefined countdown time iTime in seconds was reached.
  • _SimLoad_<SimloadName>Terminate
    Terminate the Simload, which may include to set back user-specific settings to standard values.
  • _SimLoad_<SimloadName>StartAction
    Optionally run user actions after a Simload is launched in start mode.
  • _SimLoad_<SimloadName>StopAction
    Optionally clean up user-specific settings when a Simload is stopped.

Main Functions in Libs\LibSimLoads.au3

  • _SimLoad_InitEnvironment()
    Initialize a Simload and set global variables. No parameter and no return value.
  • _SimLoad_CountdownScreen(sLabel)
    Show countdown screen before launching the Simload. The parameter sLabel is a string displayed on the countdown screen. No return value.
  • _SimLoad_CheckTimePeriod(sTempName)
    Check if an application is open for a shorter or a longer time than the iTime value in the temporary Simload object. The parameter sTempName is the unique name of a temporary Simload object. The return value is 1 if the current time in seconds since midnight minus sStartTime in seconds since midnight is smaller than iTime. The return value is 0 if the current time minus sStartTime is greater than iTime.
  • _SimLoad_CheckRuntimeInSeconds(iStartTimeInSecs)
    Calculate application runtime in seconds from the start time. The parameter iStartTimeInSecs is the application start time, calculated in seconds since midnight. The return value is the time difference in seconds between the current time in seconds since midnight and the application start time.
  • _SimLoad_WriteLog(sType, sDescription)
    Add an entry to the log file. The parameter sType can have the values ERROR, WARNING, INFO, DEBUG or SYSNOTE. The parameter sDescription is a description text string. No return value.
  • _SimLoad_WriteEvent(sTempName, sType, sDescription)
    Add a line with time stamp, type and descriptions to an existing event file. The parameter sTempName is the unique name of a temporary Simload object. The parameter sType can have the values ERROR, WARNING or INFO. The parameter sDescription is a description text string. The return value is 0 if bEventFile = 0 in the temporary Simload object. The return value is 1 if a new line was added to the event file.
  • _SimLoad_HelpText1(SimloadName), _SimLoad_HelpText2(SimloadName), _SimLoad_HelpText3(SimloadName)
    Show dialog box with help information (simload types 1, 2 or 3). The parameter SimloadName is the name of the Simload. No return value.
  • _SimLoad_SetWatermark()
    Set a watermark in the top right corner of the screen, based on multiple values in Tools\Registration.ini. No parameter and no return value
  • _SimLoad_DeleteWatermark()
    Remove the watermark on the screen. No parameter and no return value.

Temporary Object Functions in Libs\LibSimLoads.au3

  • _SimLoad_NewTempObject(sTempName, ByRef aTempObject)
    Create a new temporary Simload object. The parameter sTempName is the unique name of the new Temporary Simload Object. The paramter ByRef aTempObject is a pointer to the array including the initial values of the temporary Simload object that was created previously. No return value.
  • _SimLoad_SetTempObjectValue(sTempName, valuename, type, value)
    Set value in a temporary object, uses _SimLoad_WriteRegValue. The parameter sTempName is the unique name of the new temporary Simload object. The parameter valuename is the item name of a temporary Simload object. The parameter type is the value type, either REG_SZ or REG_DWORD. The parameter value is the value of the temporary Simload object item. No return value.
  • _SimLoad_SetTempObjectAppWinPos(sTempName, iX, iY, iWidth = 0, iHeight = 0)
    Write application window position and size into temporary Simload object. The parameter sTempName is the unique name of the new temporary Simload object. The parameters iX and iY are the application window's top left position on the screen. The optional parameters iWidth and iHeight are the new application window position on the screen. No return value.
  • _SimLoad_GetTempObject(sTempName)
    Read out all values of a temporary Simload object and write them into an array. The parameter sTempName is the unique name of a temporary Simload object. Returns an array including the entire temporary Simload object.
  • _SimLoad_GetTempObjectValue(sTempName, valuename)
    Read out one value of a temporary object. The parameter sTempName is the unique name of a temporary Simload object. The parameter valuename is the item name of a temporary Simload object. Returns the value of the selected Simload object item.
  • _SimLoad_GetTempObjectFullAppPath(sTempName)
    Read a string with full application path from AppName, AppPath and AppPathType. The parameter sTempName is the unique name of a temporary Simload object. Returns the full application path.
  • _SimLoad_GetTempObjectFullDataPath(sTempName)
    Read a string with full data path from DataFile, DataPath and DataPathType. The parameter sTempName is the unique name of a temporary Simload object. Returns the full data file path.
  • _SimLoad_ShowTempObject(sTempName, timeout = 5)
    Show all values of a temporary Simload object in a dialog box. The parameter sTempName is the unique name of a temporary Simload object. The optional parameter timeout is the time the dialog box stays open. No return value.
  • _SimLoad_DeleteTempObject(sTempName)
    Delete temporary Simload object. The parameter sTempName is the unique name of a temporary Simload object. No return value.

Process Functions in Libs\LibSimLoads.au3

  • _SimLoad_GetHandleFromPid(iPID, sTitle = "", timeout = 30)
    Read all window titles [x][0] and handles [x][1] associated to a process ID. The parameter iPID is the process ID. The optional parameter sTitle is the window title (default is an empty string). The optional parameter timeout is the maximum function run time in seconds (avoiding endless loops, default is 30 seconds). Returns an array which includes all window handles that belong to a process ID.
  • _SimLoad_GetWinInfoByPid(iPID, sTitle = "")
    Read all relevant window parameters. The parameter iPID is the process ID. Optional parameter sTitle is the window title. Returns the array [PID, HWND, ProcessName, FileName, Title, X, Y, Width, Height, WinState].
  • _SimLoad_GetWinInfoByHandle(hWnd)
    Read all relevant window parameters. The parameter hWnd is the window handle. Returns the array [PID, HWND, ProcessName, FileName, Title, X, Y, Width, Height, WinState]. The default timeout is set to 30 seconds.
  • _SimLoad_GetWinInfoByTitle(sTitle)
    Read all relevant window parameters. The parameter sTitle is the window title. Returns the array [PID, HWND, ProcessName, FileName, Title, X, Y, Width, Height, WinState].
  • _SimLoad_SetWinControlsByTitle($sTempName, $timeout = 30)
    Get process ID and window handle by window title and store the values in the temporary simload object. The parameter sTempName is the unique name of a temporary object. The default timeout is set to 30 seconds. No return value.

Windows App Functions in Libs\LibSimLoads.au3

  • _SimLoad_StartWinApp(sTempName, bDataFile)
    Start a windows application. Resize, move or make fullscreen if needed. The parameter sTempName is the unique name of a temporary Simload object. If parameter bDataFile is 0 then don't open data file, if it is 1 then open FullDataPath. No return value.
  • _SimLoad_StopWinApp(sTempName)
    Read a Windows application name and the control type from the temporary Simload object and stop the application. The parameter sTempName is the unique name of a temporary Simload object. No return value.
  • _SimLoad_MoveWinApp(sTempName, fRandom, iSpeed = 5, iX = 0, iY = 0)
    Move application window to a new position, with speed and randomize options. The parameter sTempName is the unique name of a temporary Simload object. If the parameter fRandom is 1, move app window to a random place on the screen. The optional parameter iSpeed is the delay in ms between micro moves (default = 5). The optional parameters iX and iY are the new application window position on the screen. No return value.
  • _SimLoad_SetWinAppPosAndSize(sTempName)
    Read application window's position and/or size from temporary Simload object and set on the screen accordingly. The parameter sTempName is the unique name of a temporary Simload object. No return value.

Code Samples

The SDK install package adds the following folders and files:

Folder File Name Description
Libs
LibSimLoads.au3 Main Simload user-defined function library.
Simloads\ZL1-Samples
Compile-ZL1-Samples.au3 Running this AutoIt file with F5 compiles the Simloads in this folder.
ZL1-Empty.au3 AutoIt sample source code with an empty Simload object that can be used as a template. Many lines with comments were added with the purpose of making the source code easier to understand.
ZL1-Empty.ini Side-by-side .ini file for the ZL1-Empty Simload with empty Simload object. The section name [ZL1-Empty] must reflect the code file name without extension. The same is true for the keyname in the [Simloads] section and the path to the Simload executable in the value.
Lib-Empty.au3 Simload-specific functions: _SimLoad_EmptyInit, _SimLoad_EmptyRunAction, _SimLoad_EmptyTerminate, _SimLoad_EmptyStartAction and _SimLoad_EmptyStopAction.
ZL1-Empty.exe The executable of the ZL1-Empty Simload after it was compiled using Compile-ZL1-Samples.au3.
ZL1-App.au3 AutoIt sample source code with an empty Simload object that relies on application configuration details in the side-by-side .ini file. While the ZL1-App Simload is running, a dialog box with temporary object values is show in the bottom right corner of the screen.
ZL1-App.ini Side-by-side .ini file for the ZL1-App Simload with all required Simload object values. The section name [ZL1-App], the keyname in the [Simloads] section and the path to the Simload executable in the value must be set properly.
Lib-App.au3 Simload-specific functions: _SimLoad_AppInit, _SimLoad_AppRunAction, _SimLoad_AppTerminate, _SimLoad_AppStartAction and _SimLoad_AppStopAction. The additional function _SimLoad_ShowForm displays a dialog box with temporary object values in the bottom right corner of the screen.
ZL1-App.exe The executable of the ZL1-App Simload after it was compiled using Compile-ZL1-Samples.au3.
ZL1-NotepadTest.au3 AutoIt sample source code with a Simload object that is preconfigured to open Notepad. The side-by-side ini file can be used to overwrite object values.
ZL1-NotepadTest.ini Side-by-side .ini file for the ZL1-NotepadTest Simload with optional Simload object values. The section name [ZL1-NotepadTest], the keyname in the [Simloads] section and the path to the Simload executable in the value must be set properly.
Lib-NotepadTest.au3 Simload-specific functions: _SimLoad_AppInit, _SimLoad_AppRunAction, _SimLoad_AppTerminate, _SimLoad_AppStartAction and _SimLoad_AppStopAction.
ZL1-NotepadTest.exe The executable of the ZL1-NotepadTest Simload after it was compiled using Compile-ZL1-Samples.au3.
ZL1-MSEdgeTest.au3 AutoIt sample source code with a Simload object that is preconfigured to open a web page in Microsoft Edge. The run action scrolls up and down every second. The side-by-side ini file can be used to overwrite object values.
ZL1-MSEdgeTest.ini Side-by-side .ini file for the ZL1-MSEdgeTest Simload with optional Simload object values. The section name [ZL1-NotepadTest], the keyname in the [Simloads] section and the path to the Simload executable in the value must be set properly.
Lib-MSEdgeTest.au3 Simload-specific functions: _SimLoad_AppInit, _SimLoad_AppRunAction, _SimLoad_AppTerminate, _SimLoad_AppStartAction and _SimLoad_AppStopAction.
ZL1-MSEdgeTest.exe The executable of the ZL1-MSEdgeTest Simload after it was compiled using Compile-ZL1-Samples.au3.
Tools
WinInfo.exe Table showing process ID, window handle, file name, window title, position, size and state of all enabled and visible windows.
WinInfoPlus.exe Table showing process ID, window handle, file name, window title, position, size, state, username and domain of all enabled and visible windows. A file with the results is stored in c:\Users\Public\Documents\.
ProcInfo.exe Table showing process name, process ID and file name of all processes running on the system. A file with the results is stored in c:\Users\Public\Documents\.
WtsProcInfo.ex Table showing process name, process ID, file name, session ID and user info of all processes running on the system, using the Terminal Server API. A file with the results is stored in c:\Users\Public\Documents\.
TempObjectInfo.exe Dialog box allowing to select a temporary object and show all values.
_Icons
EUCScore_AppTimeLarge.ico Icon used for type 1 Simloads.
EUCScore_AppSet.ico Icon used for type 2 Simloads (Personas).

 

The Inno Setup file Install-ZL1-Samples.iss in the EUC Score root folder contains the source code required to build the SDK install package. The target folder is \_Installers.