com.unipro.smlib
Class SmsManager

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--com.unipro.smlib.SmsManager
All Implemented Interfaces:
java.lang.Runnable

public class SmsManager
extends java.lang.Thread

Note: In the next version of SMLib this class will not extend java.lang.Thread and implement java.lang.Runnable
Please, plan your business logic accordingly


Main class of SMLib.

General description

SmsManager is the main class of SMLib.
This class represents almost all library's functionality: sending and receiving messages, configuring.
SmsManager's instance can be created using getInstance() static method.

Next picture represents general view of the system:



To send and receive SMS messages you need:
  1. Computer with free COM port
  2. Mobile phone, which can be connected to COM port
  3. Cable to connect mobile phone to the COM port
SmsManager creates SMS messages and sends them using mobile phone of GSM standard connected to a computer using data cable. The same way SmsManager processes SMS messages received by mobile phone and delivered to the computer.

The following "Hello World!" example shows how messages can be sent and received using SMLib.

Sending message

First, let's send message "Hello World!" to a mobile phone. To send the message the following steps should be completed:
  1. Create class test in test.java file
  2. Import SMLib classes
  3. Create an instance of SmsManager class
  4. Initialize library. Set your port settings in the new Configurator object
  5. Create new out message. Pass recipient number, SMSC number and message text to the constructor
  6. Stop the library
Code:
 // Import SMLib classes
 import com.unipro.smlib.*;
 public class test {
   public static void main(String[] s) {
     // Create an instance of SmsManager class
     SmsManager smsManager = SmsManager.getInstance();
     try {
       // Initialize library. Set your port settings in the new Configurator object
       smsManager.init(new Configurator(Configurator.PORT_COM1,Configurator.BAUD_19200));
     } catch (Exception e) {
       // Handle exceptions of initializations here
     }
     try {
       // Create new out message. Pass recipient number, SMSC number and message text to the constructor
       // Send the message using sendMessage method
       smsManager.sendMessage(new OutMessage("79029261105","79029261405","Hello World!"));
     } catch (Exception e) {
       // Handle exceptions of sending here
} // Stop the library smsManager.close(); } }

Receiving the message

To run some processes when the in message received message listener should be implemented and registered in the SmsManager.
  1. Create class TestListener that implements SmsListener interface. SmsManager runs processMessage method of the listener each time the SMS message is received
  2. Implement processMessage method of the SmsListener interface
  3. Modify previous code, register new listener in the SmsManager
 import com.unipro.smlib.*;
 class TestListener implements SmsListener {
   // Method to process the in message
   public void processMessage(InMessage mess) {
     System.out.println("New message is received from "+mess.getSenderNumber()+" '"+mess.getText()+"'");
   }
 }
Modify the previous code to add the listener to SmsManager.
 smsManager.addMessageListener(new TestListener());
 

Listeners

SMLib can receive in messages and ACK reports (status reports). Create instance of SmsListener or ACKListener correspondingly, and register the listener by calling addMessageListener()/addACKListener() method of SmsManager. You can add listeners before and after calling of init() method, but messages and ACKs will be received only after calling init() method. It is possible to change listeners at runtime (while SMLib is initialized). Old listener must be deleted first by calling deleteMessageListener()/deleteACKListener() of SmsManager. After that it's possible to add new listener. If message/ACK is received while no listener is registered in the SmsManager, it will be saved in the pool and will be processed by the next appropriate listener. Only one message (ACK) listener can be registered in the SmsManager. Registering second listener throws TooManyListenersException.

Pools

When SmsManager is initialized by method init() of SmsManager, ACKs and SMS messages pools are created.
They save all in ACK or messages if no ACKListener or SmsListener is registered until ACKListener or SmsListener is registered in the SmsManager. When appropriate listener is attached it process all messages (or ACKs) from the pool. Pool can save up to 50 items by default and up to set value if this value is set in the Configurator parameter of the init() method of SmsManager. Pool works like FIFO queue (first in - first out). Pools are working as long as library is working. If init() is called pools are working while method close() is called.

Using several phones

SMLib is able to work with several phones simultaneously. To use several phones attach them to different COM ports. It is necessary to invoke SmsManager.getInstance() for several times which returns different instances of SmsManager. Each instance of SmsManager should be initialized with a Configurator associated with COM port with which each phone is connected. For example, there are two phones attached to COM1 and COM2. The following code example shows how to initialize one listener for these phones:
 // Import SMLib classes
 import com.unipro.smlib.;
 public class SendMessage {
   public static void main(String[] s) {
     // Create an instance of SmsManager class
     SmsManager smsManager1 = SmsManager.getInstance();
     SmsManager smsManager2 = SmsManager.getInstance();
     try {
       // Initialize library
 // Set your port settings in the new Configurator object
       smsManager1.init(new Configurator(
         Configurator.PORT_COM1,Configurator.BAUD_19200
       ));
       smsManager2.init(new Configurator(
        Configurator.PORT_COM2,Configurator.BAUD_19200
       ));
     } catch (Exception e) {
       // Handle exceptions of initializations here
     }
    try {
      smsManager1.addMessageListener(new TestListener());
      smsManager2.addMessageListener(new TestListener());
    } catch (TooManyListenersException e) {}
   }
 }
 


Field Summary
static int MAX_MOB_SIZE
           
static int SMLIB_CLOSED
          One of statuses that can be returned by getStatus method.
SMLib is not initialized.
static int SMLIB_DISCONNECT
          One of statuses that can be returned by getStatus method.
SMLib was initialized but after that cable was unplugged.
It is possible to return SMLib to the correct state by reconnecting the cable.
static int SMLIB_ERROR_CONNECT
          One of statuses that can be returned by getStatus method.
SMLib was initialized but after that cable was unplugged with error.
static int SMLIB_ERROR_PORT
          One of statuses that can be returned by getStatus method.
SMLib was initialized but after that error of communication port occurred.
It is necessary to close SMLib and initialize it again.
static int SMLIB_INIT_NONRECEPT
          One of statuses that can be returned by getStatus method.
SMLib was initialized and isn't receiving messages.
static int SMLIB_INIT_RECEPT
          One of statuses that can be returned by getStatus method.
SMLib was initialized and is receiving messages.
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Method Summary
 void addACKListener(ACKListener listener)
          Registers listener object that can process input ACKs.
 void addMessageListener(SmsListener listener)
          Registers listener object that can process input messages.
 void allowReception(boolean al)
          Allows or forbids reception of input messages and ACKs.
It can be able to refuse input messages and ACKs by calling allowReception(false).
 void close()
          Stops SMLib: stops 2 internal threads that were created by init() method and release COM port.
 void deleteACKListener()
          Deletes ACK listener (About listeners).
 void deleteMessageListener()
          Deletes messages listener (About listeners).
static SmsManager getInstance()
          Creates SmsManager's instance.
 int getStatus()
          Gets the status of SMLib.
 void init(Configurator pc)
          Initializes SMLib with the specified settings.
This method initializes two threads: first runs java comm API and second runs method for getting SMS from mobile phone.
 void run()
           
 int sendMessage(OutMessage SMMessage)
          Sends an SMS message.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SMLIB_CLOSED

public static final int SMLIB_CLOSED
One of statuses that can be returned by getStatus method.
SMLib is not initialized.

SMLIB_INIT_RECEPT

public static final int SMLIB_INIT_RECEPT
One of statuses that can be returned by getStatus method.
SMLib was initialized and is receiving messages. For prohibition of receiving messages call allowReception(false).

SMLIB_INIT_NONRECEPT

public static final int SMLIB_INIT_NONRECEPT
One of statuses that can be returned by getStatus method.
SMLib was initialized and isn't receiving messages. For being able to receive messages call allowReception(true).

SMLIB_DISCONNECT

public static final int SMLIB_DISCONNECT
One of statuses that can be returned by getStatus method.
SMLib was initialized but after that cable was unplugged.
It is possible to return SMLib to the correct state by reconnecting the cable.

SMLIB_ERROR_CONNECT

public static final int SMLIB_ERROR_CONNECT
One of statuses that can be returned by getStatus method.
SMLib was initialized but after that cable was unplugged with error.
It is impossible to return SMLib to the correct state by reconnecting the cable.
It is necessary to close SMLib and initialize it again.

SMLIB_ERROR_PORT

public static final int SMLIB_ERROR_PORT
One of statuses that can be returned by getStatus method.
SMLib was initialized but after that error of communication port occurred.
It is necessary to close SMLib and initialize it again.

MAX_MOB_SIZE

public static final int MAX_MOB_SIZE
Method Detail

getStatus

public int getStatus()
Gets the status of SMLib.
Returns:
status that represents SMLib state in the current moment of the time. More about smlib statuses see SMLIB_XXX constants. There are:
  1. SMLIB_CLOSED
  2. SMLIB_INIT_RECEPT
  3. SMLIB_INIT_NONRECEPT
  4. SMLIB_DISCONNECT
  5. SMLIB_ERROR_CONNECT
  6. SMLIB_ERROR_PORT

getInstance

public static SmsManager getInstance()
Creates SmsManager's instance. To use several phones attach them to different COM ports. It is necessary to invoke SmsManager.getInstance() for several times which returns different instances of SmsManager. Each instance of SmsManager should be initialized with a Configurator associated with COM port with which each phone is connected.

init

public void init(Configurator pc)
          throws PortConnectionException,
                 MobileException
Initializes SMLib with the specified settings.
This method initializes two threads: first runs java comm API and second runs method for getting SMS from mobile phone. Also ACK and Message pools begin to work (See more about pools). After calling of init method SmsManager is ready to send messages and receive messages and ACKs. Received items will be processed by listener or saved in the pool if no listener is registered. It is possible to initialize diferent SmsManages using differenr communication ports.
Parameters:
pc - settings of COM port and pools, if pc=null then default settings is used.
Default values.
Throws:
PortConnectionException - if there are any problems with COM port or data cable
  1. If it is unable to initialize connection using current settings.
  2. If there is no response from mobile phone.
  3. If communication port is busy by another application or SmsManager.
  4. *
MobileException - if there are any problems with mobile AT interface.
  1. If there is unable to initialize mobile PDU mode.
Additional information about SMLib exceptions - SMLib exceptions.

allowReception

public void allowReception(boolean al)
Allows or forbids reception of input messages and ACKs.
It can be able to refuse input messages and ACKs by calling allowReception(false). It is possible to switch on/off the reception before and after initialization of SmsManager. When the reception of the messages and ACKs is forbidden they will not be processed by listeners as well as saved in the pool. Use allowReception(false) when using SMLib only for sending messages. It will save resources of the computer.
Parameters:
al - true allows, false forbid the reception. True by default.

sendMessage

public int sendMessage(OutMessage SMMessage)
                throws PortConnectionException,
                       SendException
Sends an SMS message. If message's text is more than 160 symbols, message is sent as concatenated short message, otherwise message is sent as single SMS.
Parameters:
OutMessage - object that represents output message.
Returns:
message reference value for message which was sent. Message reference parameter can take on value of 0-256. If value is -1 - message reference was not correctly determinated.
more about references
Throws:
SendException - if there are problems with sending message from mobile phone or error of sending occurred (see more in SendException description).
PortConnectionException - if there is no connection with mobile phone: mobile phone is not responding during long period of time (about 30 sec).

Additional information about SMLib exceptions - smlib exceptions..

addMessageListener

public void addMessageListener(SmsListener listener)
                        throws java.util.TooManyListenersException
Registers listener object that can process input messages. Only one listener can be registered in the SmsManager (About listeners).
Parameters:
SmsListener - message listener.
Throws:
java.util.TooManyListenersException - if SmsListener is already registered in the SmsManager.

addACKListener

public void addACKListener(ACKListener listener)
                    throws java.util.TooManyListenersException
Registers listener object that can process input ACKs. Only one ACKs listener can be registered in the SmsManager (About listeners).
Parameters:
ACKListener - message listener
Throws:
java.util.TooManyListenersException - if ACKListener is already registered in the SmsManager.

deleteMessageListener

public void deleteMessageListener()
Deletes messages listener (About listeners).

deleteACKListener

public void deleteACKListener()
Deletes ACK listener (About listeners).

close

public void close()
Stops SMLib: stops 2 internal threads that were created by init() method and release COM port. Destroys messages and ACKs pools. Messages and ACKs cannot be sent or received.

run

public void run()
Overrides:
run in class java.lang.Thread