SMS Reception Center: User's Guide

Overview

SMS Reception Center is a program that reads incoming short messages from a cellular phone and, for each message, executes the actions that you specified. Unlike other popular desktop SMS utilities, its main purpose is to handle incoming messages and send outgoing ones without any human intervention. Usually it's set up at the computer with a dedicated cellular phone or a GSM modem plugged in.

When you start SMS Reception Center, the first thing that you see is the editor. Now you can begin to write rules defining what will be done with incoming messages. When it's done you can save the rules to a file. When the rules are ready, you have to run the service that will actually connect to your phone (modem) and process messages. You can do it from the editor's menu.

The service is able to run in one of two modes:

• Desktop mode. It's running on the current user's desktop, and the service's icon is shown in the system tray. Some testing and debugging features are available in this mode only, so you'll certainly use it while tesing your ruleset.

• NT service mode. The service is running at the background and doesn't interact with the user's desktop; it remains running when you log off and can be set up to autostart before somebody logs in.

The main editor's window contains a list of rules that you have defined. You may create a new rule either with Edit->Insert in the main menu or with a context menu that will appear when you click on the list with the right mouse button. You may start editing an existing rule by double-clicking on the list element.

When a message arrives, the rules are applied in sequence. Each rule can use some predefined variables as parameters, and some rule types can define new variables. There may be a condition for each rule, determining when this rule is applied and when it's skipped.

The following actions are supported so far:

• Store message adds a new line to the text file; you should specify a template for this line, using variable references where appropriate.
• Send message sends out a new SMS or Winpopup message.
• Execute SQL query runs SQL statement using an ODBC connection. The result of the query may be stored to variables.
• Run program runs an executable file. You may use variable references in the executable file name as well as in other command-line parameters. You can define a variable that will contain the console program's output.
• Tweak variable modifies the variable's value using an operation of your choice: replaces prefix, substring, or regular expression in the value.

When you begin to edit a rule, a dialog box appears where you can type in a rule's parameters. Some elements of this dialog box have context menu: when you click on such an element with the right mouse button, you can see the menu containing all the variables defined so far. The reference to the chosen variable (in the form of [%variable-name%]) is inserted into the field that you're editing. When this rule is used to process incoming message, all these references are replaced with current values of referenced variables. For each particular parameter, you can always know if variable references are allowed in it: if the appropriate dialog box element has a context menu, they are.

Common Elements of the Rule-Editing Dialogs

The layout of the rule editing dialog is specific for each rule type. However, some dialog elements are common for all types.

Description (entry)

Here you can specify the purpose of the rule in a few words. When you look at the main editor's window, you see the Description of each rule in the Information column (if the description is empty, this column is filled with action parameters).

This field doesn't affect message processing in any way, it's for your convenience only.

Condition (frame)

When a message arrives, the rule is applied to it only if the condition is true. There are two parts of a condition: a simple test (checking if the variable's value matches the pattern you give), and a complex test (checking if the logical expression, given in the C-like syntax, is true). The simple test's parameters are given in the upper part of the frame, and the compex test's expression is given in the lower one.

A few things to remember about Conditions:

• Any blank condition (test) is considered true. If you fill the simple test parameters and leave the complex test expression blank, then the whole condition's result will depend on the simple test. If you don't touch any field in the Condition frame at all, the rule is applied unconditionally.
• Simple test is considered blank (always true) if a variable's name is empty.

The simple test compares the variable with the pattern you give, using one of the following methods:

• If you select is exactly as an operation, the variable's value must be exactly the same as the pattern that you give.

• If you select is like, same as above, except that you can use some metacharacters in the pattern.
  • (star) matches any sequence of zero or more characters;
  • ? matches exactly one character;
  • [chars] matches any single character in chars.
• If you select contains, the variable's value must contain a substring that you give as pattern.

• If you select matches regexp, the pattern must be a regular expression, against which the variable's value will be matched.

The complex test evaluates the logical expression you give. The expression may contain the following elements:

• Variable references in the form of [%variable-name%] (you can insert a reference using the context menu);
• String literals surrounded by double quotes: “string”. Any occurrence of $, ", \, [, ] in string literals must be quoted with backslash;
• !=, == comparisons between variables and string literals;
• ( ) parentheses to denote subexpressions;
• ||, && logical operators;
• [regexp regexp string] is true if the string matches the regular expression. Both string and regexp may contain variable references.
• [string match pattern string] is true if the string matches the pattern, using the same pattern style as in “is like” simple test.

Take no further actions after this one is taken (checkbox)

If you enable this option for a rule, then if the rule's condition is true and all variables that it uses are defined, all rules following this one are ignored.

Running the Service

When all the rules are ready, you'll want to start the service that will handle incoming messages. Selecting Run -> Install... in the menu will bring up an appropriate dialog window.

You can set the following parameters in this window:

• Service mode. The following options are available:
  • NT Service: the service will be started as a Windows NT system service. It will survive the user's logout, and it can be started before somebody logs in.

  • Desktop: the service will be started on the current user's desktop. It will create an icon in the system tray, and the context menu of this icon can be used to stop the service. This mode is useful for debugging and testing purposes.

• COM port. The name of the serial port to which the cellular phone is plugged. The following things may be important for you:
  • If Bluetooth or Infrared connection is used, there is usually some emulated COM-port. You should use this port to make SMS Reception Center work with such a connection.
  • Sometimes the phone requires a vendor-specific driver to work as a GSM modem (notably, some lower-class NOKIA phones require NOKIA data suite). The driver may provide emulated COM-port different from the real port, and you should select this emulated port when starting the service.
• Port parameters. The speed, parity, data bits, stop bits parameters for the COM-port in a standard form. “19200,n,8,1” is the default that will work for most phones and modems. If your phone's or data cable's manual recommends another settings, you can alter this parameter (ex. Falcom A2D1 GSM modem requires speed=9600 to work).

• Start the service (uncheck to stop). If you mark this checkbox, the service will be started when you click on the OK button; if you unmark this checkbox, the service will be stopped. You should take care that the NT service doesn't use the same COM port as the Desktop service tries to use: only one of those services will be able to open the port. So it's recommended to keep the NT service stopped while you're using the Desktop service to test your ruleset file.

• Start on boot or login. Mark this checkbox to autostart the service when the system is powered on (NT service) or the current user logs in (Desktop).

Testing the Rules

When you defined some rules for message processing in the editor, you may want to test if the rules work properly. The good thing is that it can be done without sending any real SMS (and even without a cellular phone).

First you should start the message-processing service in the Desktop mode (see how to start the service). The program's icon appears in the system tray when the Desktop-mode service is started, and the icon's context menu may be used to control the service.

While the Desktop-mode service is running, you can use Run->Test message... menu entry to imitate message reception and see what is done. The service will handle this message exactly the way it would handle a real incoming message with the same sender and text that you entered in the dialog window.

There is also an option in the tray icon's context menu that can be useful if the program doesn't work properly with your cellular phone. When you select “Save debug log” in the menu, the text file is created. If you send the debug log file to mailto:support@sw4me.com in your error report, it may speed up the error-correction process significantly.

If you worry about the privacy issues, note that:

• The debug log file contains all information that was received from the phone and sent to it. It may include the message texts and sender/recipient numbers, if the messages were sent or received in this session. If there were no messages sent or received, this file doesn't contain any information on the message-processing rules that you set up.
• If the connection was established with a phone, the file contains the full name of your phone's model and manufacturer.
• The file doesn't contain any other information on your system or the rules that you have defined.