MOBITEK SMS API version 9 — Manual for Software Developer

INTRODUCTION

MOBITEK® SMS API is application programming interface for short messaging service. It allows software developer or system integrator to build a SMS application, a SMS Gateway, or to add SMS functionality to an existing system (e.g. ERP, CRM).

MOBITEK® SMS API is COM/ActiveX that can be called by:-

  1. Microsoft’s IDE (e.g. VB6, C++, C#, VB.net)
  2. PHP (version 5 and above)
  3. Delphi
  4. Cold Fusion
  5. Java (with JACOB)

General Features:-

  1. to initialise modem; to connect and disconnect GSM modem with PC/Server
  2. to reboot the GSM modem
  3. to unlock SIM with PIN
  4. to check whether GSM modem is connected with GSM network
  5. to check the signal strength of GSM network
  6. to get the name of GSM network operator
  7. to send SMS (maximum 160 characters, and in text format only)
  8. to send long message i.e. SMS longer than 160 characters (concatenating messages)
  9. to read incoming SMS (in text format only)
  10. to turn on / off the delivery status report, and to obtain delivery status report of outgoing SMS
  11. to interact with GSM network via USSD (for checking account balance, expiry date, top-up prepaid account, etc.)
  12. to add, delete, edit phone book in SIM card
  13. check whether a mobile number is on-line

 

REVISION HISTORY

EDITION REVISED DATE REMARK
8th 2021-12-23 added "Version 9.3"; revised "COMPATIBILITY LIST of SMS API version 9"
7th 25th of January, 2017 revised "INTRODUCTION"
6th 29th of January, 2015 Version 9.2 is released
5th 14th of August, 2013 Version 9 (beta) is released
4th 23rd of August, 2010 Version 7.3 is released with support of unicode SMS
3rd 13th of July, 2010 Version 7.2 released — "Programme Design" updated
2nd 21st of April, 2010 Introduction revised, "Supported Operating System" appended into "Specifications"
1st 4th of December, 2009 Draft release

 

COPYRIGHT

© 2015 MOBITEK System Sdn. Bhd. All rights reserved.

No part of this document may be reproduced, distributed, stored in a retrieval system or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical, photocopying, manual or otherwise, without the prior written permission of MOBITEK System Sdn. Bhd.

 

TRADEMARK

MOBITEK®  is a registered trademark owns by MOBITEK System Sdn. Bhd.
Product names, logos, brands and other trademarks referred in this document are the property of their respective trademark holders and are used only to directly describe the products being provided.

 

DISCLAIMER

MOBITEK makes no representations or warranties with respect to the contents here of and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose.
Furthermore, MOBITEK reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to notify any person of such revision or changes.

 

SPECIFICATION

Version: 9.3.6 for MOBITEK Q25 ; 9.3.7 for MOBITEK S80

API Type: COM/ActiveX or ActiveX Dll

Supported Operating System:

  1. Windows XP Home / Pro 32 bit and 64 bit
  2. Windows Vista 32 bit and 64 bit
  3. Windows Server 2008 32 bit and 64 bit
  4. Windows 7 32 bit and 64 bit
  5. Windows 8 32 bit and 64 bit
  6. Windows Server 2012
  7. Windows 10 32 bit and 64 bit

COM: MobitekSMSAPI9.dll

Requirements

  1. You must be a software developer or a system integrator, and you must posses programming skill and knowledge on using  ActiveX component.
  2. You must use a programming language that can reference to COM, call its methods and get its properties. Here is a list of supported programming languages:-
  • Visual Basic
  • Visual Basic .Net
  • C++
  • C#
  • Java
  • PHP
  • Delphi
  • Cold Fusion
  • Any programming language that can call “MobitekSMSAPI9.dll”

 

BENEFITS

  1. rapid development of a SMS Gateway
  2. full control of the message flow, business logic and the design of SMS Gateway
  3. can decide how to handle incoming- trigger an event, or launch an external application
  4. can decide where to store the incoming message – in database, in text, or in XML
  5. can decide who should receive outgoing message, when to send, what to send
  6. integrate SMS feature with external software application
  7. able to check credit balance of prepaid account
  8. able to reload, top-up the prepaid account
  9. send concatenating SMS, i.e. SMS longer than 160 characters
  10. send Chinese SMS

 

LIMITATIONS

  1. Cannot send SMS in 8 bit format, e.g. ring tone, picture message, 2D barcode nor flash SMS.
  2. Does not support WAP push.
  3. Does not support encryption nor compression of SMS.

 

COMPATIBILITY LIST of SMS API version 9

Certain model / brand of modem does not support all the functions of MOBITEK® SMS API version 9. Please refer to the table below.

CLASS
METHOD
MOBITEK Q24
MOBITEK S80
MOBITEK Q25
MODEM
FindCOMPort
YES
NO
NO
MODEM
InitModem
YES
YES
YES
MODEM
Reboot
YES
MODEM
IsConnectToGSM
YES
YES
YES
MODEM
OperatorName
YES
YES
YES
MODEM
SignalStrength
YES
YES
YES
MODEM
ShutDown
YES
MODEM
GetMSISDN
YES
YES
NO
MODEM
GetIMSI
YES
YES
NO
PHONEBOOK
TotalSpace
YES
PHONEBOOK
TotalUsed
YES
PHONEBOOK
PhonebookRead
YES
PHONEBOOK
PhonebookWrite
YES
PHONEBOOK
PhonebookDelete
YES
SMS
SendSMSText
YES
YES
YES
SMS
SendLMSText
YES
SMS
SendSMSUnicode
YES
YES
YES
SMS
SendSMS
YES
YES
YES
SMS
ReadSMS
YES
YES
YES
SMS
IsOnline
YES
YES
YES
SMS
DeliveryReportOn
YES
YES
YES
SMS
GetDeliveryReport
YES
YES
YES
SMS
DeliveryReportOff
YES
YES
YES
USSD
USSD
YES
YES
YES
USSDListen
USSD
YES
VOICE
CheckCall
YES YES
VOICE
MakeCall
 YES YES
VOICE
 EndCall YES YES

 

RELEASE NOTE

Version 9.3.6 (final) for MOBITEK®  Q25 & Version 9.3.7 (final) for S80

  • Release Date: 09-Dec-2021
  • Two “Read” methods added:
    • SMS.ReadSMS() – read text format SMS
    • SMS.ReadSMSText() – read PDU format SMS

Version 9.2 (final) for MOBITEK®  S80

  • Release Date: 4-Feb-2015
  • New class — “Voice” with new methods and property:-
  • Voice.AnswerCall( )
  • Voice.CheckCall( )
  • Voice.End( )
  • Voice.MakeCall( )
  • Voice.CallerID

Version 9.0 (beta)

  • Release Date: 14-Aug-2013
  • New function in Modem class:-
    • Modem.GETMSISDN()
    • Modem.GETIMSI()
  • New function in USSD class:-
    • USSD.USSDListen()

Version 7.3 (final)

  • Release Date: 14-Apr-2011
  • Support of unicode SMS
    • SMS.SendSMSUnicode()

Version 7.1 (beta)

  • Release Date: 8-Mar-2010
  • Able to receive multiple parts of SMS (got bugs); Concatenating needs to be done by software developer.

Difference between version 5.3 (final) and 7.0 (beta)

  • Version 7 has a new class, “Modem”:-

Modem.Init ( )

Modem.FindCOMPort ( )

Modem.Reboot ( )

Modem.IsConnectToGSM ( )

Modem.OperatorName ( )

Modem.GetSignalStrength ( )

Modem.ShutDown ( )

  • Version 7’s class “SMS” has new methods:-

SMS.SendLMSText ( )

SMS.IsOnLine ( )

  • List of methods in version 7:-

SMS.ModemInit ( )

SMS.ModemClose ( )

SMS.ModemReset ( )

The rest methods and properties of the SMS API version 9 are from version 7.

 

TERMS AND CONDITIONS

  1. MOBITEK® SMS API version 9.0 (here refer as “API” is a beta stage. It is a beta version. It may not work the way a final version will. MOBITEK System Sdn. Bhd. (hereafter refer as “MOBITEK “) may change any functions and/or properties in the final version.
  2. MOBITEK may not release a final version of this API.
  3. It is recommended to use this API for the purpose of research and development.
  4. You grant MOBITEK, without charge, the right to use, share and commercialize your feedback in any way and for any purpose.
  5. The API is supplied “as-is.” You bear the risk of using it.
  6. MOBITEK MAKES NO WARRANTY, EXPRESS OR IMPLIED.
  7. You have the ability to give feedbak about the API to MOBITEK.
  8. MOBITEK may or may not provide any fix nor patch for the API.
  9. This functionality of SMS API depends on the model of the wireless/SMS/GSM modem. Certain model does not support all the functions.

 

SET-UP

Before using the MOBITEK®  SMS API, please go through the following check list:

  • MOBITEK Q24 SMS Modem is properly set-up (refer to the installation guide);
  • identify the COM port where the modem is connected;
  • install the SMS API from CD (note: there is no download link on our web site, please keep a back-up the CD); and
  • the IDE (VB.net, VC++, etc.) is properly configured to use the COM/ActiveX (refer to your programming guide).

 

VB6

Below is a Visual Basic example on how to configure to use the “MobitekSMSAPI9.dll

  1. Go to “Project > References”
  2. Click “MobitekSMSAPI9”
  3. Create object for Modem
    Dim Modem as New MobitekSMSAPI9.Modem
  4. Create object for SMS
    Dim Modem as New MobitekSMSAPI9.SMS
  5. Create object for USSD
    Dim USSD as New MobitekSMSAPI9.USSD

VB.Net

Refer to the manual, “Manual_VB2008.pdf”, that is in the CD on how to use MOBITEK® SMS API in VB.net or .Net platform.

 

Using COM Components from Visual Studo .Net Directly

The following article is from http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dndotnet/html/callcomcomp.asp
It describes how you can call COM/ActiveX from .Net:

As a .NET developer, you also have the option of using COM components directly. At least, that’s what it looks like, although you’re programmatically still using a RCW to get to objects in unmanaged code. If you’re working within a Visual Basic .NET project, you can follow these steps to add a reference to a COM component:

  1. Click Project, and then click Add Reference.
  2. In the Add Reference dialog box, click the COM tab.
  3. Select the type library you wish to use from the list and click Select, or use the Browse button to locate a component that’s not listed. The selected components will be added to the lower listview in the dialog box.
  4. Click OK to create RCWs for the selected type libraries in your Visual Basic .NET project.

When you do this, you’ll find that Visual Basic .NET actually creates a DLL in your project’s /Bin folder, with a name derived from the original COM component name. For example, if you reference BackEnd.dll version 2.0 in this manner, Visual Basic .NET will create the RCW in the file Interop.BackEnd_2_0.dll.

 

MODEM CLASS

There are 9 methods or functions:

  1. Modem.FindCOMPort()
  2. Modem.Init()
  3. Modem.Reboot()
  4. Modem.IsConnectToGSM()
  5. Modem.OperatorName()
  6. Modem.GetMSISDN()
  7. Modem.GetIMSI()
  8. Modem.SignalStrength
  9. Modem.ShutDown

 

FindCOMPort

Modem.FindCOMPort (iStart As Integer, iEnd As Integer) As Integer

To find out which COM Port is the GSM modem connected with. Only applies to Wavecom and Q24.

 

Arguments

  • iStart: the method will begin searching at this COM port; number must be smalle than iEnd
  • iEnd: the method will end the search at this COM port; number must be greater than iStart

 

Return Value
= 0 (if not found)
= the number of the COM port

 

Example

Dim iPort as interger
iPort = Modem.FindComPort(3,10) 'find which COM port is modem connected to beginning at COM port 3 until 10
If iPort > 0 then
   Modem.Init(iPort) 'if found, then initialised the GSM modem
Else
   MsgBox "Modem not found!"
End If

 

Init

Modem.Init (ByVal intPort As Integer, Optional ByVal PIN As String) As InitStatus

To initialise and to connect PC to the GSM Modem. This is the first method that should be called before the rest of the methods can be used.

Arguments

  • intPort: the COM port where the modem is connected to
  • PIN: optional, the PIN to unlock SIM

Return Value
= 0 (Fail) if connection failed
= 1 (OK) if connection is successfully established
= 2 (PINRequired) if connection failed, because SIM PIN is required
= 3 (PINWrong) if connection failed, because incorrect PIN is entered
= 4 (SIMBlocked) if connection failed, because SIM card has been blocked
= 5 (SIMError) if connection failed, because SIM card has problem or error

Warning: DO NOT use this method in a loop nor in timer control. If you place both method, Init() and ShutDown(), in a timer control with 5 seconds interval, then it is like switching on and off your hand phone every 5 seconds.

 

Reboot

Modem.Reboot () As Boolean

To reboot the modem, it is a soft reboot.
Return value:
= TRUE (if success)
= FALSE

It will take at least 12 seconds to reboot.
Use this method if any one of the following conditions arises:

  • modem is not responding
  • cannot send SMS after many times
  • cannot read SMS after many times

Tip: This method is a soft reset. If modem is still not responsive, then a hard reset — switch off then on the power to the modem, is required.

 

Programme Design Flow

Bad Design:

If SMS.SendSMS() = False then Modem.Init()

If you do so, very likely you will get “Modem.Init() = 0”

Good Design:

If SMS.SendSMS() = False then
   If Modem.Reboot() = True then
      Modem.Init()
   End If
End If

 

IsConnectToGSM

Modem.IsConnectToGSM () As Boolean

To check whether the GSM modem is connected to the GSM network.
Return Value
= TRUE (if connected)
= FALSE

This method can be called when the following events occur:

  • after Modem.Init( ) method returns “True”, and you want to make sure that the GSM network is connected
  • if you cannot send, nor read SMS

This method need not be called if the Modem.Init( ) method returns “0”.

 

OperatorName

Modem.OperatorName () As String

To get the name of GSM network operator.

 

SignalStrength

Modem.SignalStrength () As Integer

To get signal strength of GSM network.
Return Value
= -1 (unknown or cannot get any reading)
=   0 (no signal)
=   1 (weak)
=   2 (normal)
=   3 (strong)

 

Example

Public SMS As New MobitekSMSAPI7.SMS
Public Sub GetSignalStregth()

Dim iSS As Integer

iSS = SMS.GetSignalStrength
If iSS = -1 Then
   MsgBox "Unable to get signal strength!
ElseIf iSS = 0 Then
   MsgBox "NO signal strength!"
ElseIf iSS = 1 Then
   MsgBox "WEAK signal strength!"
ElseIf iSS = 2 Then
   MsgBox "NORMAL signal strength!"
ElseIf iSS = 3 Then
   MsgBox "STRONG signal strength!"
End If

End Sub

 

ShutDown

Modem.ShutDown() As Boolean

To close the connection to modem and power-off modem.
Return Value
= TRUE (if success)
= FALSE

Warning: DO NOT use this method in a loop nor in timer control. If you place both method, Init() and ShutDown(), in a timer control with 5 seconds interval, then it is like switching on and off your hand phone every 5 seconds.

 

GetMSISDN

Modem.GetMSISDN( ) As String

To get the Mobile Subscriber Integrated Services Digital Network Number (MSISDN). MSISDN is the telephone number of the SIM card in a mobile/cellular phone. MSISDN is stored in the SIM card. Some SIM card does not store it, and therefore will return empty string.

 

GetIMSI

Modem.GetIMSI() As String

To get the International Mobile Subscriber Identity. IMSI is stored in the SIM card. IMSI is used for identifying the user of a cellular network and it is a unique number.

 

PHONEBOOK CLASS

Subscriber Identity Module (SIM) card contains “Phone Book”, a memory that stores name and telephone number.

The Phonebook Class allows system integrator and software developer (SI/SD) to access the phone book entries store in the SIM card.

SI/SD are able to use Phonebook Class to develop the following applications or systems:

  1. Back-up Application – copy all entries from phone book to hard disk of computer.
  2. Address Book Application – to add, edit, delete entries in phone book via a Windows programme.
  3. Entries Transfer Application – copy all entries from phone book in old SIM card to Phonebook in new SIM card.
  4. Alert Applicaiton – upon an event trigger, send alert via SMS to numbers in phone book.
    Note:
    · Phonebook Class does not work with Universal SIM (USIM) card. USIM card is usually 128k.
    · Phonebook Class works with SIM card (16k, 32k, or 64k) only.

 

PHONEBOOK METHODS

TotalSpace

Phonebook.TotalSpace () As Integer

Check total memory space in phone book.
Return value is integer. If there is error, it returns “-

Example:

  1. If return value is “250”, it means the phone book can store up to 250 entries.
  2. If return value is “-1”, it means there is an error in accessing SIM card or phone book.

 

TotalUsed

Phonebook.TotalUsed () As Integer

Check total memory used in phone book.
Return value is integer. If there is error, it returns “-1”.

Example:

  1. If return value is “10”, it means the phone book has used 10 memory space or has 10 entries in phone book.
  2. If return value is “-1”, it means there is an error in accessing SIM card or phone book.

 

PhoneBookRead

Phonebook.PhoneBookRead (location of the phone book) As Boolean

To read a phone book entr

Accepts 1 argument:

  1. location of phone book (integer)

Return value can be either:
= TRUE (if read)
= FALSE (if cannot be read)

When return value is “True”, then call the following properties to retrieve values:

  • PhonebookName = name of contact
  • PhonebookNumber = mobile number of contact

When return value is “False”, then there is no need to retrieve the above values.

 

PhoneBookWrite

Phonebook.PhoneBookWrite (location of the phone book) As Boolean

To write a phonebook entry.

Accepts 1 argument:

  1. location of phone book (integer)

Return value can be either:
= TRUE (if can be written)
= FALSE (if cannot be written)

 

PhoneBookDelete

Phonebook.PhoneBookDelete (location of the phone book) As Boolean

To delete a phonebook entry.
Accepts 1 argument:

  1. location of phone book (integer)

Return value can be either:
= TRUE (if deleted)
= FALSE (if cannot be deleted)

 

PHONEBOOK PROPERTIES

 

PhoneBookNumber

Data type: string

The mobile number stored in the phonebook.

When PhonebookRead( ) return value is “True”, then call the following properties to retrieve values:

  • PhonebookName = name of contact
  • PhonebookNumber = mobile number of contact

When return value is “False”, then there is no need to retrieve the above values.

 

PhoneBookName

Data type: string

The name stored in phonebook.

When PhonebookRead() return value is “True”, then call the following properties to retrieve values:

  • PhonebookName = name of contact
  • PhonebookNumber = mobile number of contact

When return value is “False”, then there is no need to retrieve the above values.

 

SAMPLE CODE

Option Explicit
Public PB As New MobitekSMSAPI7.Phonebook
Public Sub PhonebookRead()
'To read a phone book entry in the specified location
If PB.PhonebookRead(frmPB.txtLocation) = True Then
   frmPB.txtNumber.Text = PB.PhonebookNumber
   frmPB.txtName = PB.PhonebookName
Else
   MsgBox "No record!"
End If
End Sub

Public Sub PhonebookWrite()
'To write a phonebook entry at the specified location, with number, with name
If PB.PhonebookWrite(frmPB.txtLocation, frmPB.txtNumber, frmPB.txtName) = True Then
   MsgBox "Contact saved!"
Else
   MsgBox "Contact NOT saved!"
End If
End Sub

Public Sub PhonebookDelete()
'To delete a phonebook entry at the specified location
If PB.PhonebookDelete(frmPB.txtLocation) = True Then
   MsgBox "Contact deleted!"
Else
   MsgBox "Contact NOT deleted!"
End If
End Sub

Public Sub PhonebookCheck()
Dim iSpace As Integer
Dim iUsed As Integer
'Check total memory space in phone book
iSpace = PB.TotalSpace
'Check total memory used in phone book
iUsed = PB.TotalUsed
If iSpace = -1 Then
   MsgBox "Unable to get information from SIM card!"
   Exit Sub
End If

If iUsed = -1 Then
   MsgBox "Unable to get information from SIM card!"
   Exit Sub
End If

frmPB.lblSpace.Caption = "The memory available in SIM card is " & iSpace & "." & vbCrLf & _
 "Total memory used is " & iUsed & "."

End Sub

 

SMS CLASS

SMS class contains 8 methods or functions:-

  1. SMS.SendSMSText
  2. SMS.SendSMSUnicode
  3. SMS.SendLMSText
  4. SMS.SendSMS (deprecated)
  5. SMS.ReadSMS
  6. SMS.IsOnLine
  7. SMS.DeliveryReportOn
  8. SMS.GetDeliveryReport
  9. SMS.DeliveryReportOff

 

SMS METHODS

SendSMSText

SMS.SendSMSText(strMobileNumber As String, strMesage As String) As Boolean

To send SMS

Arguments

  • strMobileNumber: mobile / hand phone number of recipient
  • strMessage: message to recipient (must be less than or equal to 160 characters)

Return Value

  • TRUE (if SMS is successfully sent); or
  • FALSE

Note

  1. When “SendSMSText() = True”, then retrieve value from the following property:
    MR – Message Reference Number
  2. MR is automatically generated by SMSC (SMS Centre) upon successfully calling the SendSMS() method.
  3. Use this number to match with property DRMsgRef- number from the delivery status report
  4. The MR has a range of 0 to 255. And it is incremental. Once the number reaches 255, it will start from 0 and increased by 1 for each SMS successfully sent
  5. No need to retrieve MR if “SendSMS() = False”.
  6. This method neither concatenates nor joins SMS that is longer than 160 characters.
  7. It does not support sending SMS containing Chinese characters.
  8. You must call the DeliveryReportOn() method first before sending out SMS, in order to receive delivery status report.

 

SendSMSUnicode

SMS.SendSMSUnicode (strMobileNumber As String, strMessage As String) As Boolean

To send unicode SMS, e.g. Chinese characters

Arguments

  • strMobileNumber: mobile / hand phone number of recipient
  • strMessage: unicode message in hexadecimal format; maximum length of hexadecimal character is 140 (70 unicode characters x 2)

Return Value

  • TRUE (if SMS is successfully sent); or
  • FALSE

Example
To send a character “á”, first you need to convert the unicode character into hexadecimal format, then call this function:

  • SendSMSUnicode(“+60123331111”, “00E0”) <– CORRECT; on how to convert “á” to “00E0”, please refer to the VB.net sample code.
  • SendSMSUnicode(“+0123331111”, “á”) <– WRONG

Note

  1. When “SendSMSUnicode() = True”, then retrieve value from the following property:
    MR – Message Reference Number
  2. MR is automatically generated by SMSC (SMS Centre) upon successfully calling the SendSMS() method.
  3. Use this number to match with property DRMsgRef- number from the delivery status report
  4. The MR has a range of 0 to 255. And it is incremental. Once the number reaches 255, it will start from 0 and increased by 1 for each SMS successfully sent
  5. No need to retrieve MR if “SendSMS() = False”.
  6. This method neither concatenates nor joins SMS that is longer than 70 unicode characters.
  7. You must call the DeliveryReportOn() method first before sending out SMS, in order to receive delivery status report.

 

SendLMSText

SMS.SendLMSText (strMobileNumber As String, strMessage As String, intMessageRefference As Integer) As Boolean

To send a long message by concatenating multiple parts of SMS into 1 SMS.

Arguments

  • strMobileNumber: the recipient’s number
  • strMessage: message (more than 160 characters; maximum number of characters is depended on GSM network operator)
  • intMessageReference: reference number for the concatenate/long message, value can be 0 to 255; do not repeat the value

Return Value

  • TRUE (if SMS is successfully sent); or
  • FALSE

Note

  1. When concatenating or joining 2 SMS, the maximum character of 2 SMS is not 160 x 2. It is 153 x 2. In other words, when you exceed 2 SMS, the maximum number of character is 153 per SMS.
  2. It is recommended that the optimum number of SMS to be concatenated is 6 or 918 characters (153 x 6).
  3. If you concatenate 3 SMS into 1 SMS, the cost of sending SMS is not 1. The cost is still 3 SMS.
  4. When “SendLMSText() = True”, then retrieve value from the following property — MR – Message Reference Number
  5. MR is automatically generated by SMSC (SMS Centre) upon successfully calling the SendSMS() method.
  6. Use this number to match with property DRMsgRef- number from the delivery status report
  7. The MR has a range of 0 to 255. And it is incremental. Once the number reaches 255, it will start from 0 and increased by 1 for each SMS successfully sent
  8. No need to retrieve MR if “SendSMS() = False”.
  9. You must call the DeliveryReportOn() method first before sending out SMS, in order to receive delivery status report.

 

SendSMS

SMS.SendSMS (mobile number As String, outgoing message As String) As Boolean

To send SMS with Delivery Status Report (to be used by Wavecom and iTegno GSM modem only)

Arguments

  • mobile number: the number of the recipient (string type)
  • outgoing message: the message in text only, with a maximum length of 160 characters (string type)

Return Value

  • TRUE (if SMS is successfully sent); or
  • FALSE

Note

  1. When return value is “True”, then retrieve value from the following property:
    MR – Message Reference Number
  2. MR is automatically generated by SMSC (SMS Centre) upon successfully calling the SendSMS() method.
  3. Use this number to match with property DRMsgRef- number from the delivery status report
  4. The MR has a range of 0 to 255. And it is incremental. Once the number reaches 255, it will start from 0 and increased by 1 for each SMS successfully sent
  5. No need to retrieve MR if “SendSMS() = False”.
  6. This method neither concatenates nor joins SMS that is longer than 160 characters.
  7. It does not support sending SMS containing Chinese characters.
  8. You must call the DeliveryReportOn() method first before sending out SMS, in order to receive delivery status report.

 

ReadSMSText

SMS.ReadSMSText() As Boolean

To read incoming SMS.

Return Value

  • TRUE (if successfully read or there is incoming message); or
  • FALSE if there is no incoming message

When return value is “True”, then call the following properties to retrieve values:

  • MN = Mobile number of sender
  • MSG = Message sent by the sender
  • SCTS = SMSC (SMS Centre) time stamp – time of the message received by SMSC in the format of “yy/mm/dd hh:mm:ss”
  • SMSC = SMSC (SMS Centre) number

When return value is “False”, then there is no need to retrieve the above values.

Note

  1. This method does not concatenate or join SMS that is longer than 160 characters. Nevertheless, it can receive SMS longer than 160 characters separately.
  2. It does not support reading SMS containing Chinese characters.

Programme Design Flow

Suggested Design no. 1

ModemInit() = 1
|
Timer Control
|
ReadSMSText() = True
|
Get values from ReadSMSText Property:
· MN
· MSG
· SCTS
· SMSC

Warning: Do not place ReadSMSText() in a Do…Loop, or else your SMS application may go into infinite loop, and you may jump into a wrong conclusion that the modem hangs. It is advisable to place ReadSMSText() in a timer subroutine

 

ReadSMS

SMS.ReadSMS() As Boolean

To read incoming SMS.

Return Value

  • TRUE (if successfully read or there is incoming message); or
  • FALSE if there is no incoming message

When return value is “True”, then call the following properties to retrieve values:

  • MN = Mobile number of sender
  • MSG = Message sent by the sender
  • SCTS = SMSC (SMS Centre) time stamp – time of the message received by SMSC in the format of “yy/mm/dd hh:mm:ss”
  • SMSC = SMSC (SMS Centre) number

When return value is “False”, then there is no need to retrieve the above values.

Note

  1. This method does not concatenate or join SMS that is longer than 160 characters. Nevertheless, it can receive SMS longer than 160 characters separately.
  2. It does not support reading SMS containing Chinese characters.

Programme Design Flow

Suggested Design no. 1

ModemInit() = 1
|
Timer Control
|
ReadSMS() = True
|
Get values from ReadSMS Property:
· MN
· MSG
· SCTS
· SMSC

Warning: Do not place ReadSMS() in a Do…Loop, or else your SMS application may go into infinite loop, and you may jump into a wrong conclusion that the modem hangs. It is advisable to place ReadSMS() in a timer subroutine

 

IsOnline

SMS.IsOnline (sNumber As String, [iWait_Second As integer = 10]) As Boolean

To check if a recipient’s number is on-line or not by dialing the number.

Arguments

  • sNumber: the recipient’s mobile number
  • iWait:optional, how long to wait before hanging up, default is 10 seconds

Return Value

  • TRUE if number is on-line / active ; or
  • FALSE if number is not on-line / inactive

Example

Dim bOnline as boolean
bOnline = SMS.IsOnline ("0126622111") 'modem will call the number, wait for 10 seconds, and hang up; if number is on-line, then return value is "True"
If bOnline = True then
   SMS.SendSMSText("0126622111", "Hello!") 'if recipient's mobile is online or valid, then send SMS; this will save SMS cost
End If

Note

  1. If a number is NOT valid (i.e. the number terminated, or not registered) then IsOnline() = False
  2. If a number is valid and hand phone is switched on, then IsOnline() = True
  3. If a number is valid, but hand phone is switched off, then IsOnline() = True
  4. If a number is valid and call waiting is enabled, then IsOnline() = True
  5. If a number is valid and has caller ring tone, then IsOnline() = True
  6. The accuracy also depends on how long “wait”, the longer, the more accurate
  7. Please click to view a demonstration.

 

DeliveryReportOn

SMS.DeliveryReportOn() As Boolean

To turn ON the SMS delivery status report.

Return Value

  • TRUE (if it is successfully turn on); or
  • FALSE

 

GetDeliveryReport

SMS.GetDeliveryReport() As Boolean

To get delivery status report.

Return Value

  • TRUE (if there is delivery report); or
  • FALSE (if there is no delivery report)

If return value is “True” then get the values from GetDelvieryReport Property
You must call the DeliveryReportOn() method first before sending out SMS and getting delivery status report.

Programme Design Flow

DeliveryReportOn() = True
|
SendSMS() = True
|
GetDeliveryReport = True
|
Get values from

DRFDate

DRFTime

DRMNRecipient

DRMsgRef

DRRDate

DRRTime

DRStatus

 

DeliveryReportOff

SMS.DeliveryReportOff() As Boolean

To turn OFF the SMS delivery status report.

Return Value

  • TRUE (if it is successfully turn on); or
  • FALSE

 

SMS PROPERTIES

PROPERTY OF ReadSMS

When SMS.ReadSMS() returns “True”, then retrieve values from the following properties:

  • MN = Mobile number of sender
  • Msg = Message sent by the sender
  • SCTS = SMSC (SMS Centre) time stamp – time of the message received by SMSC in the format of “yy/mm/dd hh:mm:ss”
  • SMSC = SMSC (SMS Centre) number
    It is not required to retrieve the above values if SMS.ReadSMS() returns “False”.

 

MN

Property MN As String

Mobile number of sender

 

MSG

Property Msg As String

SMS Message.

 

SCTS

Property SCTS As String

SMSC (SMS Centre) time stamp – time of the message received by SMSC.

 

SMSC

Property SMSC As String

SMSC (SMS Centre) number

 

PROPERTY OF SendSMS

When SMS.SendSMS() returns “True”, then retrieve value from the following property:

  • MR – Message Reference Number

MR is automatically generated by SMSC (SMS Centre) upon successfully calling the SendSMS() method.

Use this number to match with property DRMsgRef – number from the delivery status report

The MR has a range of 0 to 255. And it is incremental. Once the number reaches 255, it will start from 0 and increased by 1 for each SMS successfully sent

It is not required to retrieve MR if SMS.SendSMS() return “False”.

 

MR

Property MR As String

Message Reference Number – automatically generated by SMSC whenever SMS is sent.

Use this number to match with property “DRMsgRef” – number from the delivery status report.

 

ToNumber

Property ToNumber As String

Recipient’s mobile number

Only used in Java.

 

ToMessage

Property ToMessage As Variant

Message to the recipient
Only used in Java

 

PROPERTY OF GetDeliveryReport

When GetDeliveryReport( ) returns “True”, then retrieve values from the following properties:

  • DRFDate – (string) date of SMS forwarded to recipient’s mobile number by SMSC
  • DRFTime – (string) time of SMS forwarded to recipient’s mobile number by SMSC
  • DRMNRecipient – (string) recipient’s mobile number
  • DRMsgRef – (string) Message Reference Number. Use this number to match with the property MR – message reference number generated after calling the SendSMS( ) function
  • DRRDate – (string) date of SMS received by SMSC
  • DRRTime – (string) time of SMS received by SMSC
  • DRStatus – (integer) status of the outgoing SMS,
    • 0 UNDELIVERED if SMS is not delivered by SMSC
    • 1 DELIVERED if SMS is delivered to recipient’s mobile by SMSC
    • 2 UNKNOWN if status is unknown

The following statement illustrates the above properties when the outgoing SMS is successfully delivered to the recipient, i.e. DRStatus = 1 :
The status of your outgoing SMS with reference number, DRMsgRef, is DRStatus.
Your outgoing SMS was received by the SMS Centre on DRRDate, at DRRTime, and was successfully delivered to DRMNReceipient, on DRFDate, at DRFTime.

The following statement illustrates the above properties when the outgoing SMS is NOT successfully delivered to the recipient, i.e. DRStatus = 0 :
The status of your outgoing SMS with reference number, DRMsgRef, is DRStatus.
Your outgoing SMS was received by the SMS Centre on DRRDate, at DRRTime, and was NOT successfully delivered to DRMNReceipient.

The following statement illustrates the above properties when the outgoing SMS does not have any status, i.e. DRStatus = 2 :
The status of your outgoing SMS with reference number, DRMsgRef, is DRStatus.
Your outgoing SMS was received by the SMS Centre on DRRDate, at DRRTime, and no status is available.

 

DRFDate

Property DRFDate As String
Delivery Status Report – date of SMS forwarded to recipient’s mobile number by SMSC

 

DRFTime

Property DRFTime As String
Devliery Status Report – time of SMS forwarded to recipient’s mobile number by SMSC

 

DRMNRecipient

Property DRMNRecipient As String
Delivery Status Report – Recipient’s mobile number

 

DRMsgRef

Property DRMsgRef As String

Delivery Status Report – Message Reference Number.

Use this number to match with the propertry “MR” – message reference number generated after calling the SendSMSWC2() function.

 

DRRDate

Property DRRDate As String

Delivery Status Report – date of SMS received by SMSC

 

DRRTime

Property DRRTime As String

Delivery Status Report – time of SMS received by SMSC

 

DRStatus

Property DRStatus As DeliveryStatus

Delivery Status Report – Status of the outgoing SMS

Value is:

  • DELIVERED (if SMS is delivered to recipient’s mobile by SMSC);
  • UNDELIVERED (if SMS is not delivered by SMSC); or
  • UNKNOWN (if status is unknown)

 

IDD

Property IDD As String
IDD prefix
Not in used.

 

USSD CLASS

Unstructured Supplementary Service Data (“USSD”) is a feature offered by GSM network. It allows data communication with the Network Operator (“CELCO”) in wireless mode. It is generally associated with real-time or instant messaging type phone services. There is no store-and-forward capability that is typical of ‘normal’ short messages (in other words, an SMSC is not present in the processing path). Response times for interactive USSD based services are generally quicker than those used for SMS.

USSD is typically used as a ‘trigger’ to invoke independent calling services which don’t require the overhead and additional usage costs of an SMSC, such as a callback service (e.g. cheaper phone charges while roaming), or interactive menuing service (e.g. stock quotes, sporting results).

USSD is a standard for transmitting information over GSM signalling channels. It is mostly used as a method to query the available balance and other similar information in pre-paid GSM services.

Example USSD command:
· “*122#” – to check account balance of Hotlink
· “*126#” – to check account balance of Digi Prepaid
· “*124#” – to check account balance of XPax
· “*111*<14 digit PIN>#” – to reload or top-up Hotlink
· “*123*<16 digit PIN>#” – to reload or top-up Digi Prepaid

As a comparison, USSD is similar to telnet, while SMS is similar to mail.

USSD is instead session oriented, unlike SMS, which is a store-and-forward, transaction-oriented technology.

Users do not need to access any particular phone menu to access services with USSD- they can enter the Unstructured Supplementary Services Data (USSD) command direct from the initial mobile phone screen.

USSD commands are routed back to the home mobile network’s Home Location Register (HLR), allowing for the virtual home environment concept – the ability for services (based on USSD in this case) to work just as well and in exactly the same way when users are roaming.

In SMS API version 5 you are able to send USSD command to the CELCO, and obtain a response. Before you can use the USSD method, please refer to your IDE guide on setting up the USSD class.

Use USSD Class to develop the following applications or systems:

  1. Check Credit Balance – check the credit balance of prepaid account (Hotlink, Xpax, Digi Prepaid) without the need of removing the SIM card from modem.
  2. Reload Account – to reload or top-up prepaid account without the need of removing the SIM card from modem.

 

USSD

USSD.USSD (Command As String) As String

To submit a command via Unsturctured Supplementary Service Data, and get a response.

Arguments

  1. Command (string type) – the command. For example:
  • USSD(“*122#”) – to check account balance of Hotlink
  • USSD(“*126#”) – to check account balance of Digi Prepaid
  • USSD(“*124#”) – to check account balance of XPax
  • USSD(“*111*12345678901234#”) – to reload or top-up Hotlink
  • USSD(“*111*1234567890123456#”) – to reload or top-up Digi Prepaid

Return Value

  1. empty string (if there is no response, or an error has occured); or
  2. a response from GSM network operator. For example, “Account Balance: RM45.65, top-up by 31.03.2007 to keep making calls/SMS”.

Example

Option Explicit
Public USSD As New MobitekSMSAPI7.USSD

Sub USSD()
Dim sUSSD As String
sUSSD = USSD.USSD("*122#")'send command, and retrieve response from network
If sUSSD <> "" Then
   MsgBox sUSSD
Else
   MsgBox "No response from network!"
End If
End Sub

 

USSDListen

USSD.USSDListen (Optional ByVal iTimeOutSeconds As Integer = 3)

This function call will listen for USSD prompt from the network operator and capture it. While listening, no other functions are allowed to be called, it will stop upon time-out (default is 3 seconds).

If USSDListen() is not called, any USSD prompt is sent by network operator, then it will not be captured.

If USSDListen() is called after USSD prompt is sent by network operator, then it will not be captured.

Arguments

  • iTimeOutSeconds: how long to listen, default is 3 seconds

 

VOICE CLASS

It contains methods and properties for voice calling.

Note: VOICE CLASS is only supported by MOBITK Q24 SMS Modem. Other modems ARE NOT supported.

 

VOICE METHODS

AnswerCall

Voice.AnswerCall( ) As Boolean

To answer incoming call.

Call this function only if CheckCall() = True

Return Value
Return value is either:-

  • True (if call is successfully answered); or
  • False

 

CheckCall

Voice.CheckCall( ) As Boolean

Check for incoming call.

Return Value

  • True (if there is incoming call then call property “CallerID” to get the caller’s number); or
  • False (if no incoming call)

 

EndCall

Voice.EndCall( ) As Boolean

To end a call.

Return Value

  • True (if call has ended successfully); or
  • False

 

MakeCall

Voice.MakeCall(Number As String ) As Boolean

To make a voice call, e.g. MakeCall (“01012345678”).

Return Value

  • True (if call is connected); or
  • False

 

VOICE PROPERTIES

CallerID

(to be documented later)

 

APPLICATION DESIGN

  1. Your application can only use voice functions/methods exclusively. It must not call other methods, e.g. SMS at the same time.
  2. The recommended voice application design is as follows:-
    • put a timer in your code
    • in timer, call Voice.CheckCall(), if return “True”, then get value from Voice.CallerID and call Voice.AnswerCall(),
    • if your application call Voice.CheckCall(), then stop timer; resume the timer when your application call Voice.EndCall().

 

GOOD PROGRAMMING DESIGN

This section will provide advices and tips on developing a SMS Gateway.

  1. Modem communication is a serial communication (1 at a time). Serial communication (even if using USB) can only accept one instruction at one time.
  2. Your code must be serialised. DO NOT call 2 or more functions at the same time. If you do so, the modem will lock-up and you need to turn-off and on the modem (hard reboot).
  3. Serialised — calling 1 function/method at one time, after receiving a return value, then only call the 2nd function, wait for return value, then call another function, etc
  4. Your code must be synchronous, i.e. must wait for function to return a value before making next function call.
  5. User Timer to Poll
    • do not use Do…Loop, your programme may go into infinite loop and may deceive you into thinking that the SMS modem has hung
  6. Thread — do not have 2 or more threads calling SMS API. Use only 1 thread for calling SMS API.
  7. To ascertain that the cause of SMS send failure is caused by no or weak signal strength
    • SendSMS() = False > Modem.GetSignalStrength() = 0 or 1
  8. To ascertain that that the cause of SMS send failure is caused by disconnection between SMS modem and GSM network
    • SendSMS() = False > Modem.IsConnectToGSM() = False

 

SMS GATEWAY DESIGN

How do I design a SMS Gateway that automatically alerts me when there is any incoming SMS?

The SMS API does not have an “Event” that will be triggered when there is incoming SMS. You, as a software developer, are required to design the “Event” using polling method.

When you poll, DO NOT use Do…Loop, your programme may go into infinite loop and may deceive you into thinking that the SMS modem has hung. You should use a timer control.

 

REBOOTING MODEM

When should I reset the SMS modem?

Call Modem.Reboot() to reboot or reset the modem when you encounter these situations:

  • modem is not responding;
  • No GSM signal, e.g. Modem.GetSignalStrength() = 0 or -1
  • cannot send SMS after many times;
  • cannot read SMS after many times; or
  • Modem.Init() method returns “0”.

Refer to topic Modem.Reboot() for the programme design flow.

 

DEPLOYMENT

When you want to deploy your SMS application on another PC, you need to run the setup file (setup.exe) for MOBITEK® SMS API which is located in the CD. You can use an Installer (e.g. Wise Installer, MSI etc.) to include the “setup.exe” with your application.

 

SUPPORT

MOBITEK SMS Modem purchased from us comes with free standard support plan during the warranty period, usually 12 months, of modem.

Terms and Conditions

  1. Support is conducted through e-mail only, there is no on-site support nor telephone support.
  2. Support will not be provided if warranty of modem has expired.
  3. Send e-mail to Customer Support Team
  4. e-mail must contain the following information:-
    • company name
    • invoice number (can be located at the back of modem)
    • description of problem
  5. Customer Support Team will response to all e-mails within 3 working days subject to public holiday and off for training.
  6. Customer Support Team will only provide support to matters related to:-
    • MOBITEK Modem
    • SMS API Methods / Functions / Properties. e.g. SendSMS() method fail to work
  7. Customer Support Team does not provide any assistance in technical issues such as programming (e.g. how do I write a     programme to send out SMS) and integration (e.g. how do I write a programme that connects to a database).
  8. If the warranty of modem has expired, then please sign-up for the Annual Suppport Programme to enjoy continue support from MOBITEK.

 

ANNUAL SUPPORT PROGRAMME

Please refer to http://www.mobitek.my/main/product/annual-support-programme/