How to Send and Read SMS in Java with MOBITEK SMS API v. 9

Table of Contents

MANUAL REVISION HISTORY

EDITION	ISSUED DATE	REMARK
1^st	14^th of January, 2016	SMS API version 9 released for Java

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 trademark that belongs to MOBITEK System Sdn. Bhd.

DISCLAIMER

MOBITEK System Sdn. Bhd. (hereafter “MOBITEK”) makes no representations or warranties with respect to the contents hereof 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.

Trademarks and Registered Trademarks Products and product names mentioned in this document may be trademarks or registered trademarks of their respective owners.

ACKNOWLEDGEMENT

We like to extend our appreciation to the following persons for their contribution in revising this manual:-

Ms. Nur Shafiqah binti Muhamad Baharum, UNIVERSITI PERTAHANAN NASIONAL MALAYSIA

INTRODUCTION

Our MOBITEK^® SMS Gateway Development Kit (SMS GDK) contains various kits or software components. SMS GDK allows system integrator and software developer (SI/SD) to build SMS gateway, SMS application and SMS solution.

One of the kits or components is SMS Application Programming Interface (SMS API ). The type of API is Microsoft’s Component Object Model (COM) in the form of an ActiveX Dll file. We will call it COM-ActiveX.

COM-ActiveX is a Microsoft’s technology (http://www.microsoft.com/com/default.mspx). In order to use COM-ActiveX , SI/SD needs to use Microsoft’s programming language or integrated development environment (IDE) such as VB6, VC++, Visual Studio, Visual Studio.Net, VB.Net and C#.

On the other side, Java is Oracle’s (formerly Sun) technology. Unfortunately, Java cannot use COM-ActiveX. A solution for Java developer is to use Java COM Bridge (JACOB). For more information, please refer to — http://danadler.com/jacob/

With JACOB, SI/SD can use Java with MOBITEK^® SMS API.

BENEFITS

Use Java programming language to build a SMS application or SMS gateway.
SI/SD do not need to worry about the firmware changes to the GSM modem. Any underlying changes on GSM modem will not affect SI/SD’s application or system.

LIMITATIONS

Linux not supported.
JACOB belongs to 3^rd party.
Warranty of Modem does not cover failure of Java to call SMS API via JACOB. The warranty only covers hardware failure.

REQUIREMENTS

SI/SD must posses knowledge of Java programming, JRE and Eclipse (optional);
SI/SD must know how to use JACOB version 1.14.3;
JRE version 1.6 for Windows; and
Windows OS 32 bit / 64 bit.

LICENCE AGREEMENT

MOBITEK^® SMS API (hereafter refer as “API”) and JACOB is given free of charge. It is completely free of any registration, licensing or deployment fees. It may be deployed freely for use with any third-party software, whether for commercial purpose or not. Therefore, no warranty and support is given.
API must be used together with the GSM Modem supplied.
MOBITEK System Sdn. Bhd. (hereafter refer as “MOBITEK”) shall not be held liable for any loss nor damage as a result of using the API .
API is at beta stage. It is a pre-release version. It may or may not be compatible with the final version of the API will. MOBITEK may change it for the final version.
MOBITEK may not release a final version of this API.
It is not recommended to use the API to build an application that will be deployed.
It is recommended to use the 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 nor implied.
You have the ability to give feedback about the API to MOBITEK by writing to support2010@mobitek.com.my
MOBITEK may or may not provide any fix nor patch for the API.
The functionality of API depends on the model of the wireless/SMS/GSM modem. Certain model does not support all the functions.

INSTALLATION GUIDE

SMS/GSM Modem: follow the instruction in SMS Gateway Development CD to set-up the SMS/GSM modem.
MOBITEK^® SMS API version 9.0 : follow the instruction in CD to install.
JRE: install JRE version 1.6 from the CD.
JACOB: to install
1. Unzip the file “jacob-1.14.3.zip” that is in CD
2. For 32 bit, Copy these 2 files to “System32” folder:
  - jacob-1.14.3-x64.dll
  - jacob-1.14.3-x86.dll
3. For 64 bit, Copy these 2 files to “SysWOW64” folder:
  - jacob-1.14.3-x64.dll
  - jacob-1.14.3-x86.dll
ECLIPSE: install from CD; we choose ECLIPSE as the IDE for Java. You may use other IDE.

SETTING-UP ECLIPSE

Objective:-

To set up Eclipse with JACOB.
To use Java language calling functions of “MobitekSMSAPI7.dll” (MOBITEK^® SMS API version 9.0) in order to send SMS, read SMS, etc.

1. For 64 bit user, Before you run the eclipse.exe, right click at the icon eclipse and select “Run As Administrator”. For 32 bit user, you can run eclipse normally.
2. Add a new project, select “Java Project”
3. Type “SMSAPIv9” in “Project Name:” Click “Next”.
4. Go to “Libraries” tab.
5. Click on “Add External JARs” button
6. Select the file “jacob.jar” (that was unzip from “jacob-1.14.3.zip”)
7. The final outcome should be similar to figure below. Click Finish.
8. Add a new package, named it “SMSAPIv9”.
9. Add a new class, named it “SMSAPIv9.java”
10. And your final outcome should be similar to figure below:
11. Copy the Java sample code (scroll) and paste to “SMSAPIv9.java”.
12. In the sample code, change the COM port from “11” to the respective COM port:
  vMOBITEK = Modem.invoke(“Init”, 11);
13. In the Java code, change the “0176096718” to the intended recipient’s mobile number
  SMS.setProperty(“ToNumber”, “0176096718”);
14. Click “Run” button.
15. And you will see the result in “Console” tab:
```
GSM Modem is connected to computer.GSM Modem is connected to GSM network.
The operator of the GSM network is MY MAXIS.
SIM IMSI: 502123335953655
SIM MSISDN: 0176096718
The signal strength is NORMAL.
Main Balance: RM4.64, Status: Active, Active Until :16.01.2016. Bonus SMS (Hotlink) :0
Delivery status report is turned on.
Message sent!
No delivery status report available!
The status of your outgoing SMS with reference number, 250, is delivered.
Your outgoing SMS was received by the SMS Centre on 16/01/13, at 15:56:47, and was successfully delivered to 0176096718, on 16/01/13, at 15:56:50.
Incoming SMS Read
From: +60176096718
Message: Hello from JAVA with SMS API version 9. Test no. 6
Time: 16/01/13 15:56:47
GSM modem is rebooted.
Connection between GSM modem and computer is closed.
```
16. You have successfully used Java with MOBITEK^TM SMS API version 7.0 to:
  1. 1. connect SMS/GSM modem with PC/server;
    2. check connection with GSM network;
    3. check signal strength;
    4. get the name of GSM operator;
    5. get IMSI
    6. get MSISDN
    7. check the credit balance via USSD;
    8. send out SMS;
    9. get delivery status report;
    10. read SMS;
    11. reboot the SMS/GSM modem; and
    12. disconnect SMS/GSM modem with PC/server.

JAVA SAMPLE CODE

package SMSAPIv9;
import com.jacob.activeX.*; //SV: to import JACOB (for calling COM-ActieX from Java language)
import com.jacob.com.*;//SV: to import JACOB (for calling COM-ActieX from Java language)
public class SMSAPIv9
 {
//------------------- SV: declare global variables ----------------------
 static Variant vMOBITEK;
 static boolean bMOBITEK;
 static int iMOBITEK;
 static String sMOBITEK;
//construct objects for each class in "MobitekSMSAPI9.dll"; please install the API (in the CD)       before using/calling the functions/methods
 static ActiveXComponent Modem = new ActiveXComponent ("MobitekSMSAPI9.Modem");
 static ActiveXComponent SMS = new ActiveXComponent ("MobitekSMSAPI9.SMS");
 static ActiveXComponent USSD = new ActiveXComponent ("MobitekSMSAPI9.USSD");
 static ActiveXComponent PhoneBook = new ActiveXComponent ("MobitekSMSAPI9.PhoneBook");
 //------------------- SV: declare global variables ----------------------
public static void main(String[] args)
 {
 ModemInitialize();
 USSD();
 sendMessage();
 readMessage();
 ModemReboot();
 ModemShutDown();
 }
 public static void ModemInitialize()
 {
 //AQ : ModemInitialize() function is for modem to initialise the connection between the modem and  computer
//----------------------- CONNECT GSM MODEM WITH COMPUTER ------------------
 //call API to connect GSM modem with the computer at the specified COM port number; please refer to guide (in CD) on how to find the COM port number
 //SV: the return value of the function call is a variant type; store in vMOBITEK
 try
 {
 vMOBITEK = Modem.invoke("Init", 3); //NKL: please change the COM port number accordingly
 iMOBITEK = vMOBITEK.getInt(); //NKL: to extract the return value in integer
 switch (iMOBITEK)
 {
 case 0 : System.out.println("GSM Modem is NOT connected to computer!"); System.exit(0);
 case 1 : System.out.println("GSM Modem is connected to computer."); break;
 case 2 : System.out.println("GSM Modem is NOT connected to computer because a PIN is required!"); System.exit(0);
 case 3 : System.out.println("GSM Modem is NOT connected to computer because wrong PIN is entered!"); System.exit(0);
 case 4 : System.out.println("GSM Modem is NOT connected to computer because SIM card is blocked by network operator!"); System.exit(0);
 case 5 : System.out.println("GSM Modem is NOT connected to computer because SIM card has problem!"); System.exit(0);
 }
 }
 catch (com.jacob.com.ComFailException e) //NKL: if there is error in calling "Init" then display error message here
 {
 System.out.println("Fail to initialise the GSM Modem!");
 System.exit(1);//I:(1) is used when some error occurred, can use different values for different kind of errors.
 }
try
 {
 vMOBITEK = Modem.invoke("IsConnectToGSM"); //NKL: to check if GSM Modem is connected to GSM network or not
 bMOBITEK = vMOBITEK.getBoolean(); //NKL: to extract the boolean value -- "True" or "False"
if (bMOBITEK)
 {
 System.out.println("GSM Modem is connected to GSM network.");
 }
 else
 {
 System.out.println("GSM Modem is NOT connected to GSM network.");
 }
 }
 catch(com.jacob.com.ComFailException e)//I:this exception is used as try catch method for this program
 {
 System.out.println("GSM Modem is failed connected to GSM network!");
 System.exit(1);
 }
try
 {
 vMOBITEK = Modem.invoke("OperatorName");//I: to get the name of GSM network operator; it should display in strings (eg:MY MAXIS, U Mobile)
 // print operator name here ...
 sMOBITEK = vMOBITEK.getString();
if (sMOBITEK != "")
 {
 System.out.println ("The operator of the GSM network is " + sMOBITEK + ".");
 }
 else
 {
 System.out.println ("Operator name is unknown");
 }
 }
 catch (com.jacob.com.ComFailException e)
 {
 System.out.println("Operator name is unknown");
 System.exit(1);
 }
try
 {
 vMOBITEK = Modem.invoke("GetIMSI"); //NKL: to get the unique ID of SIM card, for more information, refer to http://mobitek-system.com/blog/2015/10/how-do-you-locate-a-sim-card-in-mobitek-q24-STK-modem-hub/
 sMOBITEK = vMOBITEK.getString();
 System.out.println("SIM IMSI: " + vMOBITEK.getString());
 }
 catch (com.jacob.com.ComFailException e)
 {
 System.out.println("IMSI is not available");
 System.exit(1);//I:The code will stop here if user use non dealer sim card
 }
try
 {
 vMOBITEK = Modem.invoke("GetMSISDN"); //NKL: to get the mobile number of the SIM card, sometime the infor is not stored inside the SIM
 sMOBITEK = vMOBITEK.getString();
 System.out.println("SIM MSISDN: " + vMOBITEK.getString());
 }
 catch (com.jacob.com.ComFailException e)
 {
 System.out.println("MSISDN is not available");
 System.exit(1);
 }
//------------------------------ check signal strength of GSM network ------------------------------
 //SV: to get a reading of the GSM network's signal strength
 //SV: the return value of the function call is a variant type; store in vMOBITEK
 vMOBITEK = Modem.invoke("SignalStrength");
 //since the return value of "SignalStrength" is an integer, so extract the return value as an integer and assign to "iMOBITEK"
 iMOBITEK = vMOBITEK.getInt();
 switch (iMOBITEK)
 {
 case -1 : System.out.println("Unable to get signal strength!"); break;
 case 0 : System.out.println("NO signal!"); break;
 case 1 : System.out.println("The signal strength is WEAK!"); break;
 case 2 : System.out.println("The signal strength is NORMAL."); break;
 case 3 : System.out.println("The signal strength is STRONG."); break;
 }
 //----------------------------- end: check signal strength of GSM network -------------------------
 }
public static void ModemReboot()
 {
 //SV: 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.
 vMOBITEK = Modem.invoke("Reboot");
 //since the return value of "ShutDown" is a boolean, so extract the return value as a boolean and assign to "bMOBITEK"
 bMOBITEK = vMOBITEK.getBoolean();
 if (bMOBITEK) System.out.println("GSM modem is rebooted." );
 else System.out.println("GSM modem cannot be rebooted!" );
 }
public static void ModemShutDown()
 {
 //SV: to close the connection to modem
 vMOBITEK = Modem.invoke("ShutDown");
 //since the return value of "ShutDown" is a boolean, so extract the return value as a boolean and assign to "bMOBITEK"
 bMOBITEK = vMOBITEK.getBoolean();
 if (bMOBITEK) System.out.println("Connection between GSM modem and computer is closed." );
 else System.out.println("Connection between GSM modem and computer CANNOT be closed!" );
 }
public static void sendMessage()
 //SV: to send SMS; maximum 160 characters
 {
 //########### turn delivery status report on #######################
 //call API to turn delivery status report on
 vMOBITEK = SMS.invoke("DeliveryReportOn");
 //the return value of "DeliveryReportOn" is a boolean
 bMOBITEK = vMOBITEK.getBoolean();
 //AQ : therefore assign bMOBITEK as return value of "DeliveryReportOn"
 if (bMOBITEK)
 {
 System.out.println("Delivery status report is turned on.");
 }
 else
 {
 System.out.println("Delivery status report is NOT turned on!");
 }
 //########### end: turn delivery status report on #######################
//------------------ send SMS ----------------------------------------
 //set value of property;
 //"ToNumber" is the recipient's number;
 SMS.setProperty("ToNumber", "0176096718");
 //"ToMessage" is the SMS to be send to the recipient; maximum 160 characters
 SMS.setProperty("ToMessage", "Hello from JAVA with SMS API version 9. Test no. 6");
 //AQ : call API to send new message
 vMOBITEK = SMS.invoke("SendSMS");
 //AQ : the return value of "SendSMS" is a boolean
 bMOBITEK = vMOBITEK.getBoolean();
 //AQ : therefore assign bMOBITEK as return value of "SendSMS"
if (bMOBITEK)
 {
 System.out.println("Message sent!");
//try 3 times
 for (int i=1; i<=3; i++)
 {
 try
 {
 //AQ : call API to get delivery report
 vMOBITEK = SMS.invoke("GetDeliveryReport");
 //AQ : the return value of "GetDeliveryReport" is a boolean
 //AQ : therefore assign bMOBITEK as return value of "GetDeliveryReport"
 bMOBITEK = vMOBITEK.getBoolean();
 if (bMOBITEK)
 {
 //when "GetDelIveryStatusReport = True", then get value of properties
 int DRStatus = SMS.getPropertyAsInt("DRStatus");
 String DRMNRecipient = SMS.getPropertyAsString("DRMNRecipient");
 String DRMsgRef = SMS.getPropertyAsString("DRMsgRef");
 String DRFDate = SMS.getPropertyAsString("DRFDate");
 String DRFTime = SMS.getPropertyAsString("DRFTime");
 String DRRDate = SMS.getPropertyAsString("DRRDate");
 String DRRTime = SMS.getPropertyAsString("DRRTime");
if (DRStatus == 1)
 {
 //System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is " + DRStatus + ".");
 System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is delivered.");
 System.out.println("Your outgoing SMS was received by the SMS Centre on " + DRRDate + ", at " + DRRTime + ", and was successfully delivered to " + DRMNRecipient + ", on " + DRFDate + ", at " + DRFTime + ".");
 }
 else
 if (DRStatus == 0)
 {
 //System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is " + DRStatus + ".");
 System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is not delivered.");
 System.out.println("Your outgoing SMS was received by the SMS Centre on " + DRRDate + ", at " + DRRTime + ", and was NOT successfully delivered to " + DRMNRecipient + ".");
 }
 else
 if (DRStatus == 2)
 {
 //System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is " + DRStatus + ".");
 System.out.println("The status of your outgoing SMS with reference number, " + DRMsgRef + ", is unknown.");
 System.out.println("Your outgoing SMS was received by the SMS Centre on " + DRRDate + ", at " + DRRTime + ", and NO status is available.");
 }
break;
}
else
 {
 System.out.println("No delivery status report available!");
 }
//SV: wait for 5 seconds before looping; delivery report from GSM network takes time
 Thread.sleep(5000);
 }
 catch (InterruptedException e)
 {
 // TODO Auto-generated catch block
 e.printStackTrace();
 }
 }
 }
 else
 {
 System.out.println("Message NOT sent!");
 }
 }
 public static void readMessage()
 {
 //AQ : readMessage() function is for modem to read incoming message from the sender
 //------------------------------------------- read SMS -------------------------------------------
 //call API to read incoming SMS
 vMOBITEK = SMS.invoke("ReadSMS");
 //AQ : the return value of "ReadSMS" is a boolean, therefore assign bMOBITEK as return value of "ReadSMS"
 bMOBITEK = vMOBITEK.getBoolean();
 //if there is new SMS, then get property
 if (bMOBITEK)
 {
 //property "MN" is the sender's mobile number
 String InNumber = SMS.getPropertyAsString("MN");
 //property "MSG" is the sender's message
 String InMessage = SMS.getPropertyAsString("MSG");
 //property "SCTS" time of the message received by SMS Centre
 String InTime = SMS.getPropertyAsString("SCTS");
 System.out.println("Incoming SMS Read \n From: " + InNumber + "\n Message: "+ InMessage + "\n Time: " + InTime );
 }
 else
 {
 System.out.println("No incoming SMS!");
 }
 //---------------------------------------- end: read SMS -----------------------------------------
 }
public static void USSD()
 {
 //SV: to submit a command via Unstructured Supplementary Service Data, and get a response.
 //SV: return value is variant type
 vMOBITEK = USSD.invoke("USSD" , "*122#");
 //SV: convert the variant to string, get the return value as string type
 sMOBITEK = vMOBITEK.getString();
 System.out.println(sMOBITEK);
 }
 }

TERMS AND CONDITIONS ON THE USE OF THE JAVA SAMPLE CODE

You are allowed to use, modify and distribute this code for free.
This sample code is provided on “as-is” basis. No warranty nor support is provided on the use of the code.
By using this code, you assume all the risk and responsibility.
MOBITEK System Sdn. Bhd. expressly disclaim any liability and warranty.

TERMS AND CONDITIONS ON SUPPORT

Support is NOT provided for the following matters:-
1. on how to write a Java application; and
2. on how to use JACOB.