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:-

Microsoft’s IDE (e.g. VB6, C++, C#, VB.net)

PHP (version 5 and above)

Delphi

Cold Fusion

Java (with JACOB)

General Features:-

to initialise modem; to connect and disconnect GSM modem with PC/Server

COPYRIGHT

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.2

API Type: COM/ActiveX or ActiveX Dll

Supported Operating System:

Windows XP Home / Pro 32 bit and 64 bit

Windows Vista 32 bit and 64 bit

Windows Server 2008 32 bit and 64 bit

Windows 7 32 bit and 64 bit

Windows 8 32 bit and 64 bit

Windows Server 2012

Windows 10 32 bit and 64 bit

COM: MobitekSMSAPI9.dll

Requirements

You must be a software developer or a system integrator, and you must posses programming skill and knowledge on using ActiveX component.

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

rapid development of a SMS Gateway

full control of the message flow, business logic and the design of SMS Gateway

can decide how to handle incoming- trigger an event, or launch an external application

can decide where to store the incoming message – in database, in text, or in XML

can decide who should receive outgoing message, when to send, what to send

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 S63

XTEND

GL6110

MODEM

FindCOMPort

YES

NO

YES

YES

MODEM

Init

YES

YES

YES

YES

MODEM

Reboot

YES

NO

YES

NO

MODEM

IsConnectToGSM

YES

YES

YES

YES

MODEM

OperatorName

YES

YES

YES

YES

MODEM

GetSignalStrengh

YES

YES

YES

YES

MODEM

ShutDown

YES

YES

YES

YES

MODEM

GetMSISDN

YES

NO

YES

YES

MODEM

GetIMSI

YES

NO

YES

YES

PHONEBOOK

TotalSpace

YES

NO

YES

YES

PHONEBOOK

TotalUsed

YES

NO

YES

YES

PHONEBOOK

PhonebookRead

YES

NO

YES

YES

PHONEBOOK

PhonebookWrite

YES

NO

YES

YES

PHONEBOOK

PhonebookDelete

YES

NO

YES

YES

SMS

SendSMSText

YES

YES

YES

YES

SMS

SendLMSText

YES

NO

YES

YES

SMS

SendSMSUnicode

YES

NO

YES

YES

SMS

SendSMS

YES

YES

YES

YES

SMS

ReadSMS

YES

YES

YES

YES

SMS

IsOnline

YES

NO

YES

YES

SMS

DeliveryReportOn

YES

NO

YES

YES

SMS

GetDeliveryReport

YES

NO

YES

YES

SMS

DeliveryReportOff

YES

NO

YES

YES

USSD

USSD

YES

NO

YES

YES

USSDListen

USSD

YES

NO

YES

YES

RELEASE NOTE

Version 9.2 (beta)

Release Date:

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

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.

MOBITEK may not release a final version of this API.

It is recommended to use this API for the purpose of research and development.

You grant MOBITEK, without charge, the right to use, share and commercialize your feedback in any way and for any purpose.

The API is supplied “as-is.” You bear the risk of using it.

MOBITEK MAKES NO WARRANTY, EXPRESS OR IMPLIED.

You have the ability to give feedbak about the API to MOBITEK.

MOBITEK may or may not provide any fix nor patch for the API.

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:

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

Go to “Project > References”

Click “MobitekSMSAPI9”

Create object for Modem
Dim Modem as New MobitekSMSAPI9.Modem

Create object for SMS
Dim Modem as New MobitekSMSAPI9.SMS

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:

Click Project, and then click Add Reference.

In the Add Reference dialog box, click the COM tab.

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.

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:

Modem.FindCOMPort()

Modem.Init()

Modem.Reboot()

Modem.IsConnectToGSM()

Modem.OperatorName()

Modem.GetMSISDN()

Modem.GetIMSI()

Modem.SignalStrength

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

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

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 PROPERTIES

PhoneBookNumber

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:-

SMS.SendSMSText

SMS.SendSMSUnicode

SMS.SendLMSText

SMS.SendSMS (deprecated)

SMS.ReadSMS

SMS.IsOnLine

SMS.DeliveryReportOn

SMS.GetDeliveryReport

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

When “SendSMSText() = True”, then retrieve value from the following property:
MR – Message Reference Number

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

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

If a number is NOT valid (i.e. the number terminated, or not registered) then IsOnline() = False

If a number is valid and hand phone is switched on, then IsOnline() = True

If a number is valid, but hand phone is switched off, then IsOnline() = True

If a number is valid and call waiting is enabled, then IsOnline() = True

If a number is valid and has caller ring tone, then IsOnline() = True

The accuracy also depends on how long “wait”, the longer, the more accurate

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.

MR

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.

DRMNRecipient

DRMsgRef

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.

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.

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

Your application can only use voice functions/methods exclusively. It must not call other methods, e.g. SMS at the same time.

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(),

GOOD PROGRAMMING DESIGN

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

Modem communication is a serial communication (1 at a time). Serial communication (even if using USB) can only accept one instruction at one time.

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).

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

Your code must be synchronous, i.e. must wait for function to return a value before making next function call.

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

Thread — do not have 2 or more threads calling SMS API. Use only 1 thread for calling SMS API.

To ascertain that the cause of SMS send failure is caused by no or weak signal strength

SendSMS() = False > Modem.GetSignalStrength() = 0 or 1

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

Support is conducted through e-mail only, there is no on-site support nor telephone support.

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).

If the warranty of modem has expired, then please sign-up for the Annual Suppport Programme to enjoy continue support from MOBITEK.