Info for Software Developers - Smooth Program Scheduler

Info for Software Developers

Information on this page should be used as a general programmer's guide for software developers interested into enabling their own programs with an interface towards Smooth Program Scheduler. If you need some help regarding this matter you can contact our technical support at info@xemico.com

Basic principles

Scheduler communicates with the target program in two ways:
- through Windows Messages when it can pass message type (e.g. WM_CLOSE) and two integer parameters (Wparam and LParam)
- through a program call with command-line parameters if it should pass some string to the program

There must be a .SCH file in XML format for each target program that keeps the information about the target program and list of actions available for automation through Scheduler. Precise format of the .SCH file is described further below on this page. When a Scheduler's task is due it will launch the target program if it is not already running and start passing messages and/or command-line parameters according to the task actions schedule.

Preparing the target program

To enable your program to work with Scheduler you will have to add necessary message-handlers, monitor command-line parameters and call program functions accordingly so the program automation becomes possible. It is completely up to you to decide which functions of your program should be available for automation through Scheduler.

After you finish with writing code that will provide all that functionality you will move on to create .SCH file for your program. In that file you will describe all actions that your program offers to Scheduler for automation. If some action will expect some parameters you will also define Windows controls that will be used for setting those parameters in the Scheduler itself.

Message-handlers

In order to allow Scheduler to control your program you have to define messages that the Scheduler will send to your program and provide the code to handle those messages and perform certain actions in your program. Those messages might be some pre-defined Windows messages (e.g. WM_CLOSE) or you can define new messages and assign one to each action that will be automated in your program.

Writing a message-handler depends on the programming concept and language you use. We are including one general example written in C++ Builder:

#define CM_SCH_PAUSE (WM_USER + 104)
void __fastcall TEditForm::AWndProc( Messages::TMessage &Message )
{
  switch( Message.Msg ) {
    case WM_CLOSE :
      if( !isExiting ) Hide();
      break;

    case CM_SCH_PAUSE :
      PauseClick();
      break;

    default :
      WndProc( Message );
  }
}

For details on this subject take a look at Using Messages and Message Queues in MSDN library.

Command-line parameters

You will use command-line parameters if Scheduler has to pass some information of string type to your program (e.g. some file name that you want to be opened in your program). So, to provide that functionality you have to include command-line parameters monitoring at startup in your program. This kind of action Scheduler treats as Execute Program action. You will also have to define appropriate Windows controls in .SCH file that will allow users to enter string information that Scheduler will pass to your program as command-line parameter.

Preparing .SCH file

This file has to be in the same folder as your program's executable (<install_folder>) and it has to have the same name as your program's executable just with the extension .sch (<exe_file_name>.sch). Otherwise Scheduler will not be aware of the file's existence and it will not be able to show actions available for your program.

You can distribute .sch file for your program in its installation package, or if the file's contents depends on a user's computer configuration you can create it during the installation process or at the first start of your program.

.SCH file is an XML file consisting of tags that describe available actions in your program. To define an action you have to follow a simple tag syntax that is described here. One exception is the Program Execute action that is always available and does not have to be defined in .SCH file.

Actions that do not have additional parameters (WParam, LParam, command-line parameters) are defined very easy. Here is an example:

<?xml version="1.0" ?>

<Commands ApplicationTitle="Audio Notes Recorder" AppWndClass="TDictaphoneForm">

<Command Name="Stop Playback/Recording">
<Message>WM_USER + 103</Message>
<WParam>0</WParam>
<LParam>0</LParam>
</Command>

</Commands>

The situation is more complicated with actions that require parameters because you also have to define Windows controls that will allow users to set those parameters in Scheduler. Therefore nested tags are required and that action definition becomes more complicated. Here is an example:

<Command Name="Start Playback">
<Comment>Optional parameters:</Comment>
<Message>WM_USER + 102</Message>
<WParam>-1</WParam>
<LParam>-1</LParam>

You can see the complete .SCH file for Audio Notes Recorder by clicking here.

Obligatory tags and their attributes in .SCH file

Please note that tags and attributes are given in logical order, they are not sorted alphabetically. Tags are shown in bold and attributes in normal letters.

Commands

The whole .SCH file contents should be enclosed with this tag.
<Commands>...</Commands>

ApplicationTitle

Required attribute. This one is necessary so Scheduler can get HWND handle of the main program window for sending messages. It has to be the real program title here, the one you see in Windows Task Manager for your program.

AppWndClass

Optional attibute. However, if there is a chance that several programs have the same ApplicationTitle this is the only way for Scheduler to determine the correct HWND.

Command

This tag defines an action. Each action should have its own description enclosed with this tag.

Name

Reqiured attribute. Defines a name for the action that will show up in Scheduler's list of available actions for your program.

Comment

Optional tag. If present the comment will show up in Scheduler when that action is selected. You can use it to give some more information about the action.

Message

Windows message integer number. It should be set as WM_USER + <number>. If the action you are defining is Execute with command-line parameters then set this tag to Execute.

CmLnParam

This attribute is used only if Message tag is set to Execute. Its meaning is to set default value for command-line parameters.
Example: <Message CmLnParam="">Execute</Message>

WParam

Default value for WParam.

LParam

Default value for LParam.

Controls

All controls for a given action have to be enclosed with this tag. It is also possible to place another Controls tag in Control tag (see next tag description).

Control

Describes the control.

Class

Defines the type of control. Available values are:
"CheckBox", "Panel", "ComboBox", "SpinEdit", "Label", "Button", "Edit", "RadioButton", "ListBox", "RadioGroup", "GroupBox", "TrackBar".

Name

Control name that can be used to reference it further in the XML file.

...Type

Describes the type of Property or Event for the given control. The only available type for Events is TNotifyEvent and for Properties possible types are : int, string, bool and TStrings.

Default

Use it to set default Property value.

ArgType

Defines the type of arguments in an expression if their type is different than Type or ResType. Useful when we should get bool type by comparing two int or string types.

Res

Used for Event description to set which value is changed as a result of that Event.

ResType

Type of value defined through attribute Res.

Val0, Val1...

Arguments in an expression.

Op1, Op2...

Arithmetical and logical operations. Could be any symbol of operation on int, bool or string type. However, pay attention that some symbols are reserved in XML so they have to be substituted:
">" with " >"
"<" with "<"
"&" with "&"

Item0, Item1...

If you have Property tag <Items Type="TStrings"> like with ComboBox and ListBox controls then you can set values of items in the control's list through these attributes. You have to start with Item0 and continue with Item1, Item2, etc without skipping.

if

Used for Events if the return value should depend on some condition.

Condition

Set the condition for if here. You can set it directly or calculate through an expression when you should set it to "?".

Example: <if Condition="?" ArgType="int" Val0="WParam"/>

then

Used when Condition attribute is True.

else

Used when Condition attribute is False.