SMS Driver 1.1

Introduction

SMS Driver 1.1 represents the SMSDriver package and includes only one component, the TSMSDriver, which provide an interface between an application and a GSM Terminal for sending and receiving short messages. It is fully GSM 07.05 compliant and works with any GSM Terminal. It was tested with Nokia Cellular Data Suite 2.0 and with Falcom A1.

Description

Use TSMSDriver to communicate with a GSM Terminal connected to a COM port. TSMSDriver introduces properties, methods and events for connecting and disconnection from a GSM Terminal attached to the computer, to setup the terminal, to send and receive short messages (SMS).

Features

• it is fully customizable to meet any requirements for any type of GSM Terminal.
• can send and receive SMSs according to the GSM 07.05 specifications.
• now includes a PDU codec for older GSM terminals.
• handle incoming SMS with or without storing them on the SIM memory.
• can connect to a GSM Terminal attached to any COM port at any baud rate.
• use 8 bits data, 1 stop bit, no parity and hardware flow control communication settings.

TSMSDriver is a visual component which encapsulates all the low level code required to control a GSM Terminal. Thanks to TSMSDriver component, you are needed to know nothing about low level 'AT' programming to be able to use Short Messaging Service on a GSM Terminal. Just place a TSMSDriver onto your form, rename it, modify its properties as needed and save the changes. Next you have to write down some lines of code to start a connection, to send SMSs, to handle incoming SMSs and, of course, to end (to close) the connection.

Copyright

License Agreement

You should carefully read the following terms and conditions before using this software. Unless you have a different license agreement signed by Valentin Nagacevschi, your use of this software indicates your acceptance of this license agreement and warranty.

Copyright © 1996-99, Valentin Nagacevschi.
All rights reserved worldwide.

SMSDriver package and its accompanying documentation are copyrighted material. Use and distribution of SMSDriver and the accompanying documentation are subject to the following terms and conditions.

SMSDriver package is the intellectual property of Valentin Nagacevschi and as such protected by international copyright laws. Reverse engineering, patching or any other modification is specifically prohibited without permission of the author.

SMSDriver package is used entirely on own risk. The author will take no responsibility for any loss of data or any other direct and indirect damage which may occur during the usage of SMSDriver package.

SMSDriver package is supplied as shareware so it can be used and tested 30 days for evaluation purposes free. After 30 days SMSDriver package has either to be registered for a fee of 120.00 $ (on purchasing the source code) or the usage of SMSDriver package has to stop and all files and versions of SMSDriver package must be deleted. Distribution of SMSDriver package must follow the shareware principle so that a small fee only for copying and providing the program ought to be charged by commercial shareware distributors. The charging of additional fees like such for unlocking archives is hereby strictly forbidden.

A unregistered usage of SMSDriver package into other programs / components and the distribution (commercial or noncommercial) of it is hereby strictly forbidden.

Properties

Baud

property Baud: String default '2400'

The BaudRate property determines the speed (bauds) of the COM port. You must set its value before a connection is established.

TSMSDriver provides support for 15 standard baud rate settings. Any entered value between any 2 consecutive standard values will be adjusted to the lower value.(for example if you enter '10000' the actual value will be '9600'). Any value above 256000 will be set to 256000. Any value below 110 will be set to 110.

DeleteOnRead

property DeleteOnRead: Boolean default TRUE

The DeleteOnRead property determines if a SMS message stored in SIM will be deleted after the execution of ReadSMS or DownloadSMS methods. It is recommended to be set to TRUE, because the SIM can only store 15 messages. You can set this property any time, even after the connection was established.

DirectForward

property DirectForward: Boolean default FALSE

The DirectForward property determines if a received message will be stored in SIM (FALSE value) or will be forward directly to the driver (TRUE value). If it is set to FALSE, an OnNotifySMS will be launched, with the SIM memory index of the received message as parameter. This parameter could then be used in a ReadSMS or DeleteSMS method. If it is set to TRUE, an OnReceiveSMS will be launched, with the message header and the message body as parameters. You can set this property any time, even after the connection was established, and take effect immediately.

Note: Storing received messages in SIM is not recommended, because accessing time is high and the SIM card is guaranteed for limited write/delete cycles (normally 10 000 - 100 000 cycles).

InitString1

property InitString1: String default 'ATZ'

The InitString1 property contains the first 'AT' command to be executed after the connection was established. Normally, this command is 'ATZ', actually, a reset command. It can be any valid 'AT' command. If it is an empty string, the string will not be sent to the SMS Terminal. You must set its value before a connection is established. If an illegal command is executed then an OnSMSError event will be launched.

InitString2

property InitString1: String default 'ATE0&S0'

The InitString2 property contains the second 'AT' command to be executed after the connection was established. Normally, this command is 'ATE0&S0', actually, a command to cut off the echo. It can be any valid 'AT' command. If it is an empty string, the string will not be sent to the SMS Terminal. You must set its value before a connection is established. If an illegal command is executed then an OnSMSError event will be launched.

InitString3

property InitString1: String default ''

The InitString2 property contains the second 'AT' command to be executed after the connection was established. Normally, this is an empty string and will not be sent to the GSM Terminal. It can be any valid 'AT' command. You must set its value before a connection is established. If an illegal command is executed then an OnSMSError event will be launched.

PIN

property PIN: String

The PIN property contains the PIN code to be entered normally after the GSM Terminal is switched on. The Connect method will check if the PIN code is required, and if so, will pass this string to the GSM Terminal. You must set its value before a connection is established. If a wrong PIN code was entered then an OnSMSError event will be triggered.

Note: You must be aware that entering a wrong PIN code several times, would last in the blocking of the SIM card.

PoolingDelay

property PoolingDelay: Integer default 1;

The PollingDelay property determines the delay (in seconds) to wait before checking for incoming messages from the GSM Terminal. Never set the delay too high, especially if using high baud rates. Usually, 1 second is enough for most cases. You must set its value before a connection is established.

Port

property Port: String default 'COM2'

The Port property contains the name of the serial port, which must be used. You must set its value before the connection is established. TSMSDriver provides support for up to 16 serial ports (COM1..COM16). Set this property to the COM port to which your GSM Terminal is connected.

Note: Nokia Cellular Data Suite, installs a special driver which provide an additional COM port to connect to. If your computer has 2 COM ports (most common), and your handset is attached to COM2, after you install NCDS, you must set the Port property to COM3.

ReadTimeout

property ReadTimeout: Integer default 10

The ReadTimeout property defines how long to wait for a sent command to be completed (seconds). The reply of a sent command will be ended either with 'OK' or 'ERROR' string. You must set its value before the connection is established.

SMSCenter

property SMSCenter: String

The SMSCenter property contains the address (phone number in international format) of the SMS Message Center. This is network dependent could be obtained from your local provider. You must set its value before the connection is established.

StorageString

property StorageString: String default '"SM","SM","SM"'

The StorageString property contains the type of storage for the three memories. The first is the memory from which messages are read and deleted, the second is the memory to which writing and sending operations are made, and the third is the memory to which the received SMSs are preferred to be stored. Check the GSM Terminal manual before setting this string. You must set its value before the connection is established.

Note: For NCDS, the String is '"SM","SM"' and for Falcom A1, the property is '"SM"'.

newTextMode

property TextMode: Boolean default true;

The TexMode property allows you to switch between the TEXT Mode (true) and the PDU Mode (false). Setting the TextMode to false enables older GSM terminals to function properly by using the PDU codec. All functionality is preserved.

Methods

procedure Connect

The Connect method opens the communication port and initializes the attached GSM Terminal according to the properties previously set. On completion, the OnConnected event will be triggered. At the end of the Connect method, a timer will be setup, which will poll the GSM Terminal for incoming messages (see PoolindDelay property). If an unexpected error occurs, the OnSMSError event will be triggered.

function Connected: Boolean

The Connected method returns a flag indicating if the component is or isn't controlling a GSM terminal. It returns TRUE if the component is controlling a (is connected to a) GSM Terminal, or FALSE if it is not controlling a GSM Terminal.

procedure Disconnect

The Disconnect method closes the communication port and stops polling. If the communication port has never been opened, then it does nothing. On completion the OnDisconect event will be triggered. After the communication port has been closed it will be available to other applications.

function DeleteSMS(index: String): Boolean

The DeleteSMS method deletes the stored message at the index location in the SIM memory. On completion it returns TRUE and triggers the OnDeleteSMS event. If an unexpected error occurs the OnSMSError event will be triggered and it returns FALSE.

Note: You may use this method after a OnNotifySMS event was received, in order to take the message index.

procedure DownloadSMS

The DownloadSMS method get all the stored messages from SIM memory and for each one it triggers the OnReceiveSMS event. If the DeleteOnRead property is set to TRUE, all the stored messages will be deleted.

Note: This method is very useful when toggling between direct forwarding or storing the received SMS (see DirectForward property), or after a new connection is established.

function GetState: Integer

The GetState method returns a flag indicating the state of the terminal. If the return value is 0, then the GSM Terminal is not connected to the communication port.

function GetField: Integer

The GetField method returns a negative integer value, which represents the field expressed in dBM. For full field, a -53 dBm value is returned. A value less or equal with -111 dBm means no field available.

function ReadSMS(index: String): String

The ReadSMS method returns the stored message at the index location of the SIM memory. On completion it returns the stored message, header first and then the body. If an unexpected error occurs, the OnSMSError event will be triggered, and it returns an empty string.

Note: You may use this method after an OnNotifySMS event was received, in order to take the message index.

procedure Reset

The Reset method resets the communication port and the GSM Terminal. Actually, it performs a Disconnect and then a Connect command.

function SendSMS(PhoneNumber, Message: String):String

The SendSMS method is used to send SMSs. The PhoneNumber represents the destination phone-number, and the Message represents the message to be sent. The length of the message must be less than 160 bytes. On completion, an OnSentSMS event will be triggered, and will return the data from the GSM Terminal. If an unexpected error occurs, the OnSMSError event will be triggered.

function SendSMSCommand(Command: String): String

The SendSMSCommand method could be used in order to send AT-like commands to the GSM Terminal. It returns the data replied by the terminal. If an unexpected error occurs the OnSMSError event will be triggered.

Note: Use this method with care because some commands could affect the correct functionality of the entire driver, especially the setting commands.

Events

property OnConnected: TConnected
TConnected = procedure(Sender: TObject) of object

The OnConnect event occurs after the successful completion of the Connect method.

property OnDeleteSMS: TDelSMSEvent
TDelSMSEvent = procedure(Sender: TObject; Reference: String) of object

The OnDeleteSMS event occurs after the successful deletion of the message from the SIM memory (see DeleteSMS). The Reference value points to the memory index where the message was stored. Don't use it, it's only for informational use.

property OnDisconnect: TDisconnect
TDisconnect = procedure(Sender: TObject) of object

The OnDisconnect event occurs after the completion of the Disconnect method.

property OnNotifySMS: TNotifySMSEvent
TNotifySMSEvent = procedure(Sender: TObject; Mem: String; Reference: String) of object

The OnNotifySMS event occurs every time a new SMS is received and stored in the SIM memory. The DirectForward property must be set to FALSE in order for this event to be triggered. The parameters of this event represent the type of the storage (Men) and the index at which the message is stored (Reference) respectively. Most common, the Mem contains the "SM" string, meaning that the message was stored in the SIM memory. Then, one can read or delete the message using the Reference value as parameter for the corresponding method.

property OnReceiveSMS: TReceiveSMSEvent
TReceiveSMSEvent = procedure(Sender: TObject; Header, MessageBody: String) of object

The OnReceiveSMS event occurs every time a new SMS is received and forward directly to the communication port. The DirectForward property must be set to TRUE. Also, this event is also triggered after the execution of the DownloadSMS method, for every SMS four in the SIM memory.

Note: A good practice would be that after the completion of the connection, and the setting of DirectForward property to TRUE, to execute the DownloadSMS method, in order to free the SIM memory, and then use the OnReceiveSMS event to take care of all received messages. Before the disconnection, the DirectForward property must be set to FALSE, in order for future received messages not to be lost. Thus, the intensive access to the SIM memory is prevented, without loosing messages after disconnection. Of course the DeleteOnRead property must be set to TRUE.

property OnSentSMS: TSentSMSEvent
TSentSMSEvent = procedure(Sender: TObject; Reference: String) of object

The OnSentSMS event occurs after the successful sending of a message using the SendSMS method. The Reference parameter is actually a counter of the sent messages, but if it exceeds the 255 value it will be reset to 0.

property OnSMSError: TSMSErrorEvent
TSMSErrorEvent = procedure(Sender: TObject; ErrorId: Integer; ErrorMessage: String) of object

The OnSMSError event is triggered every time an unexpected error occurs. The ErrorId parameter represents the error code, and the ErrorMessage represents the associated error message of ErrorId.

Note: If you don't handle this event, an exception will be raised if an unexpected error occurs.