SMS handlers

List of handlers

Every event may be handled automatically by Headwind GSM modem driver by using handlers. The events raised by the software are:

• Receive - the short message is received;
• Send - the short message is sent;
• Delivery - the short message is delivered.

There are three types of SMS handlers.

• Command-line handler is the program started from a command line. It gets the contents and the sender address of an incoming SMS (or parameters of other events) from the command-line parameters. The command-line handler may be used, for example, for the remote management of the computer.
• URL handler is the remote URL downloaded when the event is raised. The parameters are usually sent as the CGI variables of the GET request. Headwind GSM Modem Driver encodes it using the URL-encoding.
• COM handler can be registered by any Windows application using the COM interface of Headwind GSM modem driver.

To open the list of handlers, double-click the Headwind GSM modem driver icon and select the "Handlers" tab in the control panel. This tab contains a list of currently used handlers. You can add, edit or remove them by using the buttons to the left of the list. Please note that you can add or modify only command-line and URL handlers, because COM handlers are registered and unregistered by Windows applications.

Add handler

To add a handler, open the list of handlers (see above) and click "Add". The "Add handler" dialog will be opened. Every handler has its name, filter for the contents and filter to the sender. Every filter is a substring which is searched for in the contents or the sender of an incoming SMS.

The command line is set in the appropriate field. You can browse for a command by clicking a button to the right from the edit box. You can use the following templates for the events:

• Receive: _FROM_ and _BODY_ are replaced by sender address and message contents;
• Send: _TO_ - recipient phone number, _BODY_ - message contents, _ID_ - reference ID returned by the SMSC (usually 0-255), _STATUS_ - sending status (sent, failed);
• Delivery: _TO_ - recipient phone number, _ID_ - reference ID of the delivered message (usually 0-255), _STATUS_ - delivery status (delivered, undelivered).

The directory in which the command is executed can be also set. If the directory edit box is empty, the command is executed in the default directory.

To debug handlers, set the checkbox "Output result in log".

Example 1: a simple handler

The first example is a handler writing incoming SMS in a text file. To setup this handler, do the following steps:

• Open the control panel of Headwind GSM Modem Driver by double-clicking the application icon and select the "Handlers" tab;
• Click "Add"; a "Handler" dialog will be opened;
• Type echo _FROM_,_BODY_ >> C:\sms.txt in the "Command" field and click "OK". You will see that the new handler appears in a list.

The handler setup is complete. Send a short message to the mobile phone number of a GSM device connected to the PC. You will see a balloon tip notifying you that the message has been handled. Check that the file "sms.txt" appears in the root directory of the disk C; the file must contain the sender number and the message.

Example 2: MySQL handler

You can use Headwind GSM Modem Driver to place incoming short messages in a database. This example is related to the MySQL database. However, you can use MS SQL database as well (there is a command-line utility sqlcmd.exe, which places data in the database).

To place SMS in a database, you need to install the database first. Use the Windows package of MySQL from http://www.mysql.com.

After the MySQL database is installed, do the following steps to setup a handler:

• Create the database by running MySQL client and typing the following commands:

  CREATE DATABASE smsbase;
  USE smsbase;
  CREATE TABLE smstable (smstime DATETIME, sender VARCHAR(255), body VARCHAR(255));

   

• Open the control panel of Headwind GSM Modem Driver by double-clicking the application icon and select the "Handlers" tab;
• Click "Add"; a "Handler" dialog will be opened;
• Type the following command in the "Command" field (check the path to the MySQL client!):

  echo insert into smstable values(curtime(), '_FROM_','_BODY_'); | "c:\Program Files\mysql5.0.51b\mysql" smsbase

   

• Click "OK". You will see that the new handler appears in a list.

The handler setup is complete. Send a short message to the mobile phone number of a GSM device connected to the PC. You will see a balloon tip notifying you that the message has been handled. To check that the SMS has been written in the database, run the MySQL client and type the following commands:

USE smsbase;
SELECT * FROM smstable;

The result of selection must contain the time, the sender address and the SMS body.

Example 3: VBScript handler

• Create a VBScript file and name it "handler.vbs"

sMsisdn = WScript.Arguments(0)
sBody = WScript.Arguments(1)

sFile = "C:\sms.txt"

Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objFile = objFSO.OpenTextFile(sFile, 8, True)

' Timestamp in UTC
Timestamp = CLng(DateDiff("s", "01/01/1970 00:00:00", Now))
' Time difference with UTC 
Timestamp = Timestamp - 3600 * 3

objFile.WriteLine(Timestamp & vbTab & sMsisdn & vbTab & sBody)
objFile.Close
	

• Open the control panel of Headwind GSM Modem Driver by double-clicking the application icon and select the "Handlers" tab;
• Click "Add"; a "Handler" dialog will be opened;
• Type the following command in the "Command" field:

  cscript.exe handler.vbs _FROM_ "_BODY_"

• Setup the directory where the handler is located;
• Setup the handler event 'Receive'.

This demo handler writes incoming short messages in a text file.