com.objectxp.msg
Class GsmSmsService

java.lang.Object
  AbstractSmsService
      com.objectxp.msg.GsmSmsService

All Implemented Interfaces:

SmsService

public class GsmSmsService
extends AbstractSmsService
implements SmsService

This class may be used to send and receive GSM Short Messages (SMS) using a GSM mobile device. The device may be attached to the serial port or to a TCP/IP capable terminal server.

Before the service can be used, it has to be initalized with the proper configuration settings. The configuration must be passed as Properties to the init() method.

For incoming messages, the GsmSmsService provides the originating SMSC number as a Message property with the key SMSC_ADDR_PROPERTY. The SMSC address returned is an instance of the GsmAddress class.

Consult the jSMS Users Guide for examples how to use this class.

Nested Class Summary

class	GsmSmsService.MessageReader
class	GsmSmsService.MessageReaderPolling

Field Summary

static java.lang.String	CONFIG_GSM_CHECK_ON_SEND CONFIG_GSM_CHECK_ON_SEND is the name of the constant holding the value "sms.gsm.checkonsend".
static java.lang.String	CONFIG_GSM_CONNECTOR CONFIG_GSM_CONNECTOR is the name of the constant holding the value "sms.gsm.connector".
static java.lang.String	CONFIG_GSM_CPIN_ETSI CONFIG_GSM_CPIN_ETSI is the name of the constant holding the value "sms.gsm.cpin.etsi".
static java.lang.String	CONFIG_GSM_GET_UNREAD_MSG CONFIG_GSM_GET_UNREAD_MSG is the name of the constant holding the value "sms.gsm.receive.unreadmsg".
static java.lang.String	CONFIG_GSM_GPRS CONFIG_GSM_GPRS is the name of the constant holding the value "sms.gprs".
static java.lang.String	CONFIG_GSM_INITSTRING CONFIG_GSM_INITSTRING is the name of the constant holding the value "sms.gsm.initstring".
static java.lang.String	CONFIG_GSM_INITTIME CONFIG_GSM_INITTIME is the name of the constant holding the value "sms.gsm.inittime".
static java.lang.String	CONFIG_GSM_NMI_MODE CONFIG_GSM_NMI_MODE is the name of the constant holding the value "sms.gsm.nmi".
static java.lang.String	CONFIG_GSM_STORAGE CONFIG_GSM_STORAGE is the name of the constant holding the value "sms.gsm.storage".
static java.lang.String	CONFIG_GSM_WAITFORNET CONFIG_GSM_WAITFORNET is the name of the constant holding the value "sms.gsm.waitfornet".
static java.lang.String	CONFIG_GSM_WAITFORNET_INTERVAL CONFIG_GSM_WAITFORNET_INTERVAL is the name of the constant holding the value "sms.gsm.waitfornet.interval".
static java.lang.String	CONFIG_PIN CONFIG_PIN is the name of the constant holding the value "sms.pin".
static java.lang.String	CONFIG_POLL_INTERVAL CONFIG_POLL_INTERVAL is the name of the constant holding the value "sms.receive.poll_interval".
static java.lang.String	CONFIG_PUK CONFIG_PUK is the name of the constant holding the value "sms.puk".
static java.lang.String	SMSC_ADDR_PROPERTY SMSC_ADDR_PROPERTY is the name of the constant holding the value "gsm.smsc.addr".

Fields inherited from interface com.objectxp.msg.SmsService

VERSION

Constructor Summary

GsmSmsService()
Creates a new GsmSmsService.

Method Summary

void	connect() Connect to the GSM device or SMS gateway.
void	deleteAllMessages() Delete all messages currently stored on the GSM device.
void	deleteMessage(int msgNr) Delete a specific message from the GSM device.
void	destroy() Destroy this service.
void	disconnect() Disconnect from the SMS gateway.
java.lang.String	getManufacturer() Returns the Manufacturer of the GSM device in use (e.g.
Message	getMessage(int msgNr) Get a specific Message from the GSM device.
Message	getMessage(int msgNr, boolean delete) Get a specific Message from the GSM device.
java.util.Vector	getMessages() Returns a list of all messages currently stored in the GSM device.
java.util.Vector	getMessages(boolean delete) Returns a list of all messages currently stored in the GSM device.
java.lang.String	getModel() Returns the Model of the GSM device in use (e.g.
int	getNetworkRegistration() Returns the status of the network registration (AT+CREG).
java.lang.String	getRevision() Returns the GSM device revision
java.lang.String	getServiceCentreAddress() Return the Service Centre Address as configured on the Phone GSM device.
java.lang.String	getServiceName() Gets the name of the service.
int[]	getSignalQuality() Get the quality of the radiosignal between the GSM device and the base station.
java.lang.String[]	getSubscriberNumber() Returns the MSISDNs related to the subscriber (this information can be stored in the SIM or in the ME).
boolean	hasCapability(Capability capability) The GsmSmsService supports the following capabilities: Capability.RECEIVE Capability.SEND
void	init(java.util.Properties props) Initialize the service.
void	resetDevice() Reset the GSM device by sending the command "AT+CFUN=1,1".
AtReply	sendATCommand(java.lang.String cmd) Send an AT-command to the GSM modem.
void	sendMessage(Message message) Send a message to a GSM recipient.
void	sendMessage(Message message, java.lang.String smsc) Send a message to a GSM recipient using a specific SMSC address.
void	startReceiving() Start receiving Messages.
void	stopReceiving() Stop receiving Messages.
boolean	supportDeleteMessage() Deprecated. since jSMS 2.1.8
boolean	supportReadMessage() Deprecated. since jSMS 2.1.8, use hasCapability(Capability.RECEIVE) instead.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.objectxp.msg.SmsService

addMessageEventListener, cancel, getKeepAliveInterval, getLastIsAliveTime, getProperties, init, init, isAlive, isConnected, isInitialized, isKeepAliveActive, isReceiving, query, removeMessageEventListener, replace, setKeepAliveInterval

Field Detail

CONFIG_PIN

public static final java.lang.String CONFIG_PIN

CONFIG_PIN is the name of the constant holding the value "sms.pin".

See Also:

Constant Field Values

CONFIG_PUK

public static final java.lang.String CONFIG_PUK

CONFIG_PUK is the name of the constant holding the value "sms.puk".

See Also:

Constant Field Values

CONFIG_GSM_CONNECTOR

public static final java.lang.String CONFIG_GSM_CONNECTOR

CONFIG_GSM_CONNECTOR is the name of the constant holding the value "sms.gsm.connector".

See Also:

Constant Field Values

CONFIG_POLL_INTERVAL

public static final java.lang.String CONFIG_POLL_INTERVAL

CONFIG_POLL_INTERVAL is the name of the constant holding the value "sms.receive.poll_interval".

See Also:

Constant Field Values

CONFIG_GSM_STORAGE

public static final java.lang.String CONFIG_GSM_STORAGE

CONFIG_GSM_STORAGE is the name of the constant holding the value "sms.gsm.storage".

See Also:

Constant Field Values

CONFIG_GSM_NMI_MODE

public static final java.lang.String CONFIG_GSM_NMI_MODE

CONFIG_GSM_NMI_MODE is the name of the constant holding the value "sms.gsm.nmi".

See Also:

Constant Field Values

CONFIG_GSM_GET_UNREAD_MSG

public static final java.lang.String CONFIG_GSM_GET_UNREAD_MSG

CONFIG_GSM_GET_UNREAD_MSG is the name of the constant holding the value "sms.gsm.receive.unreadmsg".

See Also:

Constant Field Values

CONFIG_GSM_INITTIME

public static final java.lang.String CONFIG_GSM_INITTIME

CONFIG_GSM_INITTIME is the name of the constant holding the value "sms.gsm.inittime".

See Also:

Constant Field Values

CONFIG_GSM_WAITFORNET

public static final java.lang.String CONFIG_GSM_WAITFORNET

CONFIG_GSM_WAITFORNET is the name of the constant holding the value "sms.gsm.waitfornet".

See Also:

Constant Field Values

CONFIG_GSM_WAITFORNET_INTERVAL

public static final java.lang.String CONFIG_GSM_WAITFORNET_INTERVAL

CONFIG_GSM_WAITFORNET_INTERVAL is the name of the constant holding the value "sms.gsm.waitfornet.interval".

See Also:

Constant Field Values

CONFIG_GSM_GPRS

public static final java.lang.String CONFIG_GSM_GPRS

CONFIG_GSM_GPRS is the name of the constant holding the value "sms.gprs".

See Also:

Constant Field Values

CONFIG_GSM_INITSTRING

public static final java.lang.String CONFIG_GSM_INITSTRING

CONFIG_GSM_INITSTRING is the name of the constant holding the value "sms.gsm.initstring".

See Also:

Constant Field Values

CONFIG_GSM_CPIN_ETSI

public static final java.lang.String CONFIG_GSM_CPIN_ETSI

CONFIG_GSM_CPIN_ETSI is the name of the constant holding the value "sms.gsm.cpin.etsi".

See Also:

Constant Field Values

CONFIG_GSM_CHECK_ON_SEND

public static final java.lang.String CONFIG_GSM_CHECK_ON_SEND

CONFIG_GSM_CHECK_ON_SEND is the name of the constant holding the value "sms.gsm.checkonsend".

See Also:

Constant Field Values

SMSC_ADDR_PROPERTY

public static final java.lang.String SMSC_ADDR_PROPERTY

SMSC_ADDR_PROPERTY is the name of the constant holding the value "gsm.smsc.addr".

See Also:

Constant Field Values

Constructor Detail

GsmSmsService

public GsmSmsService()

Creates a new GsmSmsService. The service has to be initialized by calling init().

See Also:

init(Properties)

Method Detail

getServiceName

public final java.lang.String getServiceName()

Gets the name of the service.

Specified by:

getServiceName in interface SmsService

sendMessage

public void sendMessage(Message message)
                 throws MessageException,
                        GsmException,
                        TimeoutException

Send a message to a GSM recipient. The recipient must be a valid GSM subscriber number. Make sure that the message length does not exceed 160 characters (or 140 octets for binary messages).

Specified by:

sendMessage in interface SmsService

Parameters:

message - the message to send.

Throws:

GsmException - if the message could not be sent.

TimeoutException - if the communication with the device timed out.

MessageException - if the message could not be sent.

sendMessage

public void sendMessage(Message message,
                        java.lang.String smsc)
                 throws MessageException,
                        GsmException,
                        TimeoutException

Send a message to a GSM recipient using a specific SMSC address.

Parameters:

message - the message to send.

smsc - the address (phone number) of the SMSC to use

Throws:

GsmException - if the message could not be sent.

TimeoutException - if the communication with the device timed out.

MessageException - if the message could not be sent.

getMessages

public java.util.Vector getMessages()
                             throws MessageException

Returns a list of all messages currently stored in the GSM device. The messages will be kept on the device.

Returns:

a vector containing Message objects or null if no messages are available.

Throws:

MessageException

getMessages

public java.util.Vector getMessages(boolean delete)
                             throws MessageException

Returns a list of all messages currently stored in the GSM device.

Parameters:

delete - if 'true', the messages will be removed from the device.

Returns:

a vector containing Message objects or null if no messages are available.

Throws:

MessageException

getMessage

public Message getMessage(int msgNr)
                   throws MessageException

Get a specific Message from the GSM device.

Parameters:

msgNr - the storage location (index) of the message to fetch.

Returns:

the message or null, if no message is available at the given location.

Throws:

MessageException

getMessage

public Message getMessage(int msgNr,
                          boolean delete)
                   throws MessageException

Get a specific Message from the GSM device.

Parameters:

msgNr - the storage location (index) of the message to fetch.

delete - if 'true', the messages will be removed from the device.

Returns:

the message or null, if no message is available at the given location.

Throws:

MessageException

deleteMessage

public void deleteMessage(int msgNr)
                   throws MessageException

Delete a specific message from the GSM device.

Parameters:

msgNr - the storage location (index) of the message to erase.

Throws:

MessageException

deleteAllMessages

public void deleteAllMessages()
                       throws MessageException

Delete all messages currently stored on the GSM device.

Throws:

MessageException

supportReadMessage

public boolean supportReadMessage()

Deprecated. since jSMS 2.1.8, use hasCapability(Capability.RECEIVE) instead.

Description copied from interface: SmsService

This method returns true if the Service is able to receive messages from the SMS device or gateway, false otherwise.

Specified by:

supportReadMessage in interface SmsService

supportDeleteMessage

public boolean supportDeleteMessage()

Deprecated. since jSMS 2.1.8

Description copied from interface: SmsService

This method returns true if the Service allows messages to be deleted from the device or gateway, false otherwise.

Specified by:

supportDeleteMessage in interface SmsService

connect

public void connect()
             throws MessageException

Description copied from interface: SmsService

Connect to the GSM device or SMS gateway. Before sending and receiving messages, this method must be called. When the connection is established, the Service broadcasts a MessageEvent.DEVICE_READY event to all registered MessageEventListeners.

Specified by:

connect in interface SmsService

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

disconnect

public void disconnect()
                throws MessageException

Disconnect from the SMS gateway. Call this method after sending/receiving messages.

Specified by:

disconnect in interface SmsService

Throws:

MessageException

See Also:

MessageEvent, MessageEventListener

init

public void init(java.util.Properties props)
          throws MessageException

Initialize the service. The Properties object passed as argument to this method may contain the following properties:

sms.gsm.connector	The connector to use ("SERIAL" or "IP")
sms.pin	The PIN code (Personal Identification Number) used to activate the SIM card
sms.puk	THE PUK (Personal UnlocK) code used to unlock a barred SIM card
sms.receive.poll_interval	Polling Intervall in milliseconds (for devices not supporting asynchronous receiving)
sms.gsm.storage	Prefered message store for incoming messages ("SM" (SIM memory), "ME", (Phone memory))
sms.gsm.receive.unreadmsg	If this property is set to "true", jSMS will try to read unread messages from the device when startReceiving is called. Defaults to true.
sms.gsm.inittime	Number of seconds to wait for GSM device to become ready. Defaults to 1 second. Try increasing this parameter if calls to init() fail.
sms.gsm.waitfornet	Make sure that the GSM device is registered to the network when initializing the Service. Allowed values are either true or false. Defaults to false.
sms.gsm.waitfornet.interval	Network registration check interval in milliseconds. Only applies if sms.gsm.waitfornet is enabled. Defaults to 1000.
sms.gsm.gprs	If this property is set to "true", jSMS will try to use the GPRS network for transmitting SMS. Defaults to false.
connector.serial.port	Name of the serial port to use, e.g. COM1 (if sms.gsm.connector is set to "SERIAL")
connector.serial.bps	Port speed (default: 9600)
connector.serial.databits	Number of data bits (5,6,7,8)
connector.serial.parity	Parity ("N" (none)," E" (even), "O" (odd), "M" (mark), "S" (pace)
connector.serial.stopbits	Number of stop bits (1, 15 (1.5), 2)
connector.serial.flowctrl	Flow control. It can be a combination of the following (separated by spaces or commas): NONE: no flow control RTSCTS_IN: RTS/CTS (hardware) flow control for input RTSCTS_OUT: RTS/CTS (hardware) flow control for output XONXOFF_IN: XON/XOFF (software) flow control for input XONXOFF_OUT: XON/XOFF (software) flow control for output (RTSCTS_IN RTSCTS_OUT, RTSCTS_IN, RTSCTS_IN RTSCTS_OUT XONXOFF_IN XONXOFF_OUT,...)
connector.serial.DTR	Sets or clears the DTR (Data Terminal Ready) bit in the UART, if supported by the underlying implementation of the java COMMUNICATION API.
connector.serial.RTS	Sets or clears the RTS (Request To Send) bit in the UART, if supported by the underlying implementation of the java COMMUNICATION API.
connector.tcp.host	host name or IP adress of the terminal server where the GSM device is connected
connector.tcp.port	port number of terminal server at which the GSM device can be reached
sms.connector.timeout	Communication timeout of the connector in milliseconds. Defaults to 10'000
sms.gsm.cpin.etsi	set this property to "true" if the response from your GSM device on the command "AT+CPIN?" does NOT contain a final "OK". If unset, jSMS uses the GSM vendor identification to determine the behaviour of the device.
sms.gsm.checkonsend	Setting this property to "true" results in jSMS checking the connection to the GSM device before sending a SMS. Checking is done by calling the isAlive() method. If the check fails, the GsmSmsService will either broadcast a DEVICE_NOT_RESPONDING event to all registered event handlers (if the init property "keepalive.disconnects" is false) or disconnect itself from the device by calling disconnect() (if the init property "keepalive.disconnects" is true). Please note that enabling this feature increases the time it takes for sending a SMS. Defaults to false.

(Optional parameters are printed in italics, default values are shown in bold)

Specified by:

init in interface SmsService

Throws:

MessageException - if jSMS is unable to communicate with your GSM device or the GSM device doesn't support SMS

See Also:

SmsService.init(), SmsService.init(java.io.File)

destroy

public void destroy()

Destroy this service. Has to be invoked when the SMS Service will not be used anymore.

Specified by:

destroy in interface SmsService

getSignalQuality

public int[] getSignalQuality()

Get the quality of the radiosignal between the GSM device and the base station. For information see GSM documentation AT+CSQ. If the service is not connected to the device, this method will return null.

On successful query, this method will return a int[] with size 2. The Received Signal Strength Indication (RSSI) will be returned at position 0 in the array. The channel Bit Error Rate (BER) ist returned at position 1.

Defined Values for RSSI

0	-113 dBm or less
1	-111 dBm
2...30	-109... -53 dBm
31 -51	dBm or greater
99	not known or not detectable

Defined Values for BER

0	Less than 0.1 %
1	0.26 % to 0.30 %
2	0.51 % to 0.64 %
3	1.0 % to 1.3 %
4	1.9 % to 2.7 %
5	3.8 % to 5.4 %
6	7.6 % to 11.0 %
7	Greater than 15.0 %
99	99 not known or not detectable

Returns:

the signal quality as described above.

getServiceCentreAddress

public java.lang.String getServiceCentreAddress()
                                         throws MessageException

Return the Service Centre Address as configured on the Phone GSM device.

Returns:

the number of the SMSC

Throws:

MessageException - if service is not initialized, not connected or the device does not support querying the SMSC address

getNetworkRegistration

public int getNetworkRegistration()

Returns the status of the network registration (AT+CREG).

Possible return values are:

• 0: not registered, ME is not currently searching a new operator to register to
• 1: registered, home network
• 2: not registered, but ME is currently searching a new operator to register to
• 3: registration denied
• 4: unknown
• 5: registered, roaming

Returns:

the status of network registration.

resetDevice

public void resetDevice()

Reset the GSM device by sending the command "AT+CFUN=1,1". This will reset the device before setting the phone to full functionality.

sendATCommand

public AtReply sendATCommand(java.lang.String cmd)
                      throws MessageException,
                             TimeoutException,
                             java.io.IOException

Send an AT-command to the GSM modem.

The following example demonstrates how to query the TA serial number:

 GsmSmsService service = new GsmSmsService();
 service.init(configFile);
 service.connect();
 AtReply reply = service.sendATCommand("AT+CGSN");
 if( !reply.isError() ) {
   String serial = reply.getReply();
   System.out.println("TA Serial-Number: "+serial);
 }
 

Parameters:

cmd - the AT-Command

Returns:

the reply from the GSM modem.

Throws:

MessageException - if the service is not connected.

TimeoutException - if the communication with the GSM device timed out

java.io.IOException - if an I/O error occurs

Since:

jSMS 1.8.2

getManufacturer

public java.lang.String getManufacturer()

Returns the Manufacturer of the GSM device in use (e.g. "WAVECOM").

getModel

public java.lang.String getModel()

Returns the Model of the GSM device in use (e.g. "T68i")

getRevision

public java.lang.String getRevision()

Returns the GSM device revision

hasCapability

public boolean hasCapability(Capability capability)

The GsmSmsService supports the following capabilities:

• Capability.RECEIVE
• Capability.SEND

Specified by:

hasCapability in interface SmsService

Parameters:

capability - one of the Constants in the Capability class.

Returns:

true if the service provides the capability.

startReceiving

public void startReceiving()
                    throws java.io.IOException,
                           java.lang.IllegalStateException

Start receiving Messages. The Service has to be initialized and must be connected to the GSM device. Furthermore, you have to register at least one MessageEventListener with the Service. After receiving has started, the service will broadcast a MessageEvent of type RECEIVING_STARTED to all registered MessageEvent listeners.

The GSM SmsService will first retrieve all unread messages stored on the GSM device . For each unread message, a MESSAGE_RECEIVED event will be broadcasted to the registered listeners. The messages will then be deleted from the phone. Further receiving will be done by either using asynchronous receiving (if the device supports this) or by polling for incoming messages.

Specified by:

startReceiving in interface SmsService

Throws:

java.io.IOException - if the communication with the SMS gateway/device fails

java.lang.IllegalStateException - if the service isn't initialized and in connected state or there are no registered Message Event Listeners.

See Also:

SmsService.addMessageEventListener(MessageEventListener)

stopReceiving

public void stopReceiving()

Description copied from interface: SmsService

Stop receiving Messages. If the service isn't currently receiving messages, this method will return immediately. After receiving has stopped, the service will broadcast a MessageEvent of type MessageEvent.RECEIVING_STOPPED to all registered MessageEvent listeners.

Specified by:

stopReceiving in interface SmsService

getSubscriberNumber

public java.lang.String[] getSubscriberNumber()
                                       throws MessageException,
                                              GsmException,
                                              TimeoutException

Returns the MSISDNs related to the subscriber (this information can be stored in the SIM or in the ME). If the subscriber has different MSISDN for different services, multiple MSISDN's are returned.

Returns:

String[] an array of subscriber numbers (MSISDN) or null.

Throws:

MessageException - if the service is not connected.

GsmException - if the GSM device doesn't support querying the subscriber numbers

TimeoutException - if the communication with the GSM device times out