public class Cimd2SmsService extends AbstractSmsService implements SmsService, WindowingService, ManualAck
The message will be sent through a SMS Center (SMSC) reachable by either TCP/IP or a analog/ISDN modem.
CIMD2 requires a "large volume account" at the SMSC of your Mobile Network Provider. Contact your local provider for further information.
CIMD2 supports three different SME (Short Message Entity) types. The type used for your account depends on how your operator has set it up.
started
and stopped
. Furthermore,
Status Reports
can not be received automatically, you
have to query them by calling getStatusReport(Message)
.register
a MessageEventListener
and
call startReceiving()
.
init(Properties)
properties.
A word about Manual Acknowledgement (ManualAck
): For receiving SME types,
a incoming Message will be dispatched to your MessageEventListener
only once. However, for querying SME types, the same message will be delivered to
your MessageEventListener over and over again until you acknowledge the
Message. (the CIMD2 SMSC will deliver unacknowledged messages each time jSMS queries
for new messages).
Please note: for Windowing to work, this has to be enabled by your SMSC provider.
Modifier and Type | Class and Description |
---|---|
class |
Cimd2SmsService.MessagePoller
Check for new messages asynchronously.
|
Modifier and Type | Field and Description |
---|---|
static int |
CANCEL_ALL
Cancel all sent messages.
|
static int |
CANCEL_DEST
Cancel all messages with same destination address.
|
static int |
CANCEL_THIS
Cancel a message where the destination address and the time
stamp match with a short message submitted earlier.
|
static java.lang.String |
CFG_BPS
CFG_BPS is the name of the constant holding the value "cimd2.serial.bps".
|
static java.lang.String |
CFG_CONNECTOR
CFG_CONNECTOR is the name of the constant holding the value "cimd2.connector".
|
static java.lang.String |
CFG_DATABITS
CFG_DATABITS is the name of the constant holding the value "cimd2.serial.databits".
|
static java.lang.String |
CFG_FLOWCTRL
CFG_FLOWCTRL is the name of the constant holding the value "cimd2.serial.flowcontrol".
|
static java.lang.String |
CFG_HOST_ADDRESS
CFG_HOST_ADDRESS is the name of the constant holding the value "cimd2.host.address".
|
static java.lang.String |
CFG_HOST_PORT
CFG_HOST_PORT is the name of the constant holding the value "cimd2.host.port".
|
static java.lang.String |
CFG_INITSTRING
CFG_INITSTRING is the name of the constant holding the value "cimd2.serial.initstring".
|
static java.lang.String |
CFG_LOCAL_ADDRESS
CFG_LOCAL_ADDRESS is the name of the constant holding the value "cimd2.local.address".
|
static java.lang.String |
CFG_LOCAL_PORT
CFG_LOCAL_PORT is the name of the constant holding the value "cimd2.local.port".
|
static java.lang.String |
CFG_LOGIN
CFG_LOGIN is the name of the constant holding the value "cimd2.login".
|
static java.lang.String |
CFG_PARITY
CFG_PARITY is the name of the constant holding the value "cimd2.serial.parity".
|
static java.lang.String |
CFG_PASSWORD
CFG_PASSWORD is the name of the constant holding the value "cimd2.password".
|
static java.lang.String |
CFG_POLL_INTERVAL
CFG_POLL_INTERVAL is the name of the constant holding the value "cimd2.poll.interval".
|
static java.lang.String |
CFG_PORT
CFG_PORT is the name of the constant holding the value "cimd2.port.name".
|
static java.lang.String |
CFG_SME_TYPE
CFG_SME_TYPE is the name of the constant holding the value "cimd2.sme.type".
|
static java.lang.String |
CFG_SMSC
CFG_SMSC is the name of the constant holding the value "cimd2.smsc.number".
|
static java.lang.String |
CFG_STATUSREPORT_PARAMETER
CFG_STATUSREPORT_PARAMETER is the name of the constant holding the value
"cimd2.statusreport.parameter".
|
static java.lang.String |
CFG_STOPBITS
CFG_STOPBITS is the name of the constant holding the value "cimd2.serial.stopbits".
|
static java.lang.String |
CFG_VERSION
CFG_VERSION is the name of the constant holding the value "cimd2.version".
|
static java.lang.String |
CFG_WINDOW_SIZE
CFG_WINDOW_SIZE is the name of the constant holding the value "cimd2.window.size".
|
static java.lang.String |
CONNECTOR_SERIAL
CONNECTOR_SERIAL is the name of the constant holding the value "SERIAL".
|
static java.lang.String |
CONNECTOR_TCP
CONNECTOR_TCP is the name of the constant holding the value "TCP".
|
static java.lang.String |
SME_TYPE_QUERYING
SME_TYPE_QUERYING is the name of the constant holding the value "query".
|
static java.lang.String |
SME_TYPE_RECEIVING
SME_TYPE_RECEIVING is the name of the constant holding the value "receive".
|
static java.lang.String |
SME_TYPE_SENDONLY
SME_TYPE_SENDONLY is the name of the constant holding the value "send-only".
|
Constructor and Description |
---|
Cimd2SmsService()
Creates a new Cimd2SmsService.
|
Modifier and Type | Method and Description |
---|---|
void |
acknowledge(Message msg)
Accept a incoming message.
|
void |
acknowledge(Message msg,
java.lang.Object status)
Accept/reject a incoming message.
|
void |
cancel(Message msg)
Cancel a previously submitted message.
|
void |
cancelMessage(int mode,
Message message)
This method can be used to cancel a message sent earlier by the subscriber.
|
void |
connect()
Connect to the GSM device or SMS gateway.
|
void |
destroy()
Release allocated resources and destroy this service.
|
void |
disableManualAck()
Disable manual acknowledgement.
|
void |
disconnect()
Disconnect from the GSM device or SMS gateway.
|
void |
enableManualAck()
Enable manual acknowledgement.
|
int |
getNumberOfMessagesWaiting()
Get total number of messages waiting to be received.
|
int |
getNumberOfPendingMessages()
Returns the number of pending (unprocessed messages).
|
java.lang.String |
getServiceName()
Returns the name of the service.
|
StatusReportMessage |
getStatusReport(Message msg)
Get a status report for given Message.
|
int |
getWindowSize()
Returns the current window size or 1 if windowing is disabled.
|
boolean |
hasCapability(Capability capability)
Determine if a SMS Service has a specific capability.
|
void |
init(java.util.Properties props)
Initialize the service.
|
boolean |
isManualAckEnabled()
Check if manual acknowledgement is enabled/disabled.
|
void |
query(Message msg)
Query the status of a previously submitted message.
|
void |
resetSession()
Reset the CIMD2 session.
|
void |
sendMessage(Message msg)
Send a message to a GSM recipient.
|
void |
setWindowSize(int windowSize)
Set the window size for this service.
|
void |
startReceiving()
Start receiving Messages.
|
void |
stopReceiving()
Stop receiving Messages.
|
boolean |
supportReadMessage()
Deprecated.
since jSMS 2.1.8, use
hasCapability(Capability.RECEIVE)
instead. |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
addMessageEventListener, getKeepAliveInterval, getLastIsAliveTime, getProperties, init, init, isAlive, isConnected, isInitialized, isKeepAliveActive, isReceiving, removeMessageEventListener, replace, setKeepAliveInterval, supportDeleteMessage
public static final java.lang.String CFG_HOST_ADDRESS
public static final java.lang.String CFG_HOST_PORT
public static final java.lang.String CFG_LOCAL_ADDRESS
public static final java.lang.String CFG_LOCAL_PORT
public static final java.lang.String CFG_LOGIN
public static final java.lang.String CFG_VERSION
public static final java.lang.String CFG_PASSWORD
public static final java.lang.String CFG_SME_TYPE
public static final java.lang.String CFG_POLL_INTERVAL
public static final java.lang.String CFG_WINDOW_SIZE
public static final java.lang.String CFG_CONNECTOR
public static final java.lang.String CONNECTOR_TCP
public static final java.lang.String CONNECTOR_SERIAL
public static final java.lang.String CFG_SMSC
public static final java.lang.String CFG_PORT
public static final java.lang.String CFG_BPS
public static final java.lang.String CFG_DATABITS
public static final java.lang.String CFG_PARITY
public static final java.lang.String CFG_STOPBITS
public static final java.lang.String CFG_FLOWCTRL
public static final java.lang.String CFG_INITSTRING
public static final java.lang.String CFG_STATUSREPORT_PARAMETER
Possible values are:
The default value used by jSMS is 62.
public static final java.lang.String SME_TYPE_QUERYING
public static final java.lang.String SME_TYPE_RECEIVING
public static final java.lang.String SME_TYPE_SENDONLY
public static final int CANCEL_DEST
public static final int CANCEL_ALL
public static final int CANCEL_THIS
public Cimd2SmsService()
init(Properties)
public final java.lang.String getServiceName()
SmsService
getServiceName
in interface SmsService
public void sendMessage(Message msg) throws MessageException, Cimd2Exception, TimeoutException
SmsService
If the message to send is not a binary or unicode message, the
service will convert the message to the default GSM character set
using GsmHelper.iso2gsm()
.
This method will broadcast a MessageEvent
to all registered
MessageEventListener's. In case of success a MessageEvent
of type MESSAGE_SENT is broadcasted. Otherwise, the MessageEvent is of
type MESSAGE_NOT_SENT.
sendMessage
in interface SmsService
msg
- the message to send.MessageException
- if the message could not be sent.Cimd2Exception
TimeoutException
public void init(java.util.Properties props) throws MessageException
Key | Description |
---|---|
cimd2.connector | Type of connection to the SMSC: Use SERIAL
for Modem connections, TCP for TCP/IP
connections. Default: TCP .
|
cimd2.login | Login (Short ID) |
cimd2.password | Password |
cimd2.version | Version of the CIMD2 specification that the SMSC complies with. Allowed values
are 4 for CIMD2 V4.x, or 5 for CIMD2 V5.x. Defaults
to 5. This property influences the character conversion from/to
the SMSC.
|
cimd2.sme.type | Type of SME (as defined by your SMSC operator). There are three types of SME:
Receiving types, Querying (polling) types and send-only types. Values allowed are either
query , receive or send-only .
|
cimd2.poll.interval | Incoming messages: Polling interval in seconds (default: 5). Used only
if cimd2.sme.type=query |
cimd2.keepalive.interval | Keepalive interval in seconds. Set to 0 to turn off keep-alive. Defaults to 60. |
cimd2.connector.timeout | Communication timeout in milliseconds. Defaults to 10000 (10 secs) |
cimd2.statusreport.parameter | Status Report parameter to use (defaults to 62 if unset). Have a look at the CIMD2 specification for more information about possible values. |
cimd2.window.size | Windowing size to use. (Defaults to 1 (Windowing disabled)) |
cimd2.host.address | Hostname or IP-Address of the SMSC. E.g. smsc.yourdomain.com |
cimd2.host.port | IP port number of the SMSC. E.g. 4711 |
cimd2.local.address | Local address (interface) to bind. Example: 192.168.1.1 (if unset, the
operating system decides which interface to use, based on the SMSC host address).
|
cimd2.local.port | Local port to bind (if unset or 0, the port will be chosen by the operating system) |
cimd2.smsc.number | Phone number of your SMSC. This number will be dialed when establishing a modem connection to your CIMD2 SMSC. |
cimd2.serial.port | Name of the serial port where your modem is connected (e.g. COM1 ).
|
cimd2.serial.bps | Port speed (bits per second), If unset, 9600 will be used.
|
cimd2.serial.databits | Number of data bits (5,6,7,8 ).
|
cimd2.serial.parity | Parity (NONE, ODD, EVEN ).
|
cimd2.serial.stopbits | Number of stop bits (1, 1.5, 2 ).
|
cimd2.serial.flowcontrol | Flow Control (NONE, RTSCTS, XONXOFF )
|
cimd2.serial.initstring | Modem init string (defaults to ATZ\nATQ0V1E0\n )
|
init
in interface SmsService
MessageException
SmsService.init()
,
SmsService.init(java.io.File)
public void disconnect() throws Cimd2Exception, TimeoutException, MessageException
SmsService
MessageEvent.DEVICE_NOT_READY
even to all
registered MessageEventListeners.disconnect
in interface SmsService
Cimd2Exception
TimeoutException
MessageException
MessageEvent
,
MessageEventListener
public void connect() throws MessageException, TimeoutException, Cimd2Exception
SmsService
MessageEvent.DEVICE_READY
event to all registered
MessageEventListeners.connect
in interface SmsService
MessageException
TimeoutException
Cimd2Exception
MessageEvent
,
MessageEventListener
public void cancelMessage(int mode, Message message) throws java.io.IOException, Cimd2Exception, TimeoutException, MessageException, java.lang.IllegalArgumentException
There are three possible cancel modes:
CANCEL_DEST
: Cancel all messages with the same destination address.CANCEL_ALL
: Cancel all sent messages.CANCEL_THIS
: Cancel a message where the destination address and the
time stamp match with a short message submitted earlier.mode
- the cancel mode to usemessage
- the Message to cancel or null if mode is CANCEL_ALL.java.io.IOException
- if the communication to the SMSC unexpectedly failed.Cimd2Exception
- if the SMSC signaled an errorTimeoutException
- if the communication with the SMSC timed out.MessageException
- if the service has not been initialized or
is currently not connected to the SMSC.java.lang.IllegalArgumentException
- if the arguments passed don't provide
all necessary data (e.g. recipient, timestamp) to cancel message(s).public void destroy()
SmsService
destroy
in interface SmsService
public void startReceiving() throws java.io.IOException, java.lang.IllegalStateException, java.lang.IllegalArgumentException
SmsService
MessageEventListener
with the Service. After receiving
has started, the service will broadcast a MessageEvent of type
MessageEvent.RECEIVING_STARTED
to all registered MessageEvent listeners.startReceiving
in interface SmsService
java.io.IOException
- if the communication with the SMS gateway/device failsjava.lang.IllegalStateException
- if the service isn't initialized and in connected
state or there are no registered Message Event Listeners.java.lang.IllegalArgumentException
SmsService.addMessageEventListener(MessageEventListener)
public void stopReceiving()
SmsService
MessageEvent.RECEIVING_STOPPED
to all registered MessageEvent listeners.stopReceiving
in interface SmsService
public int getNumberOfMessagesWaiting() throws java.io.IOException, MessageException, Cimd2Exception, TimeoutException
java.io.IOException
- if the connection to the SMSC is brokenMessageException
- if the service has not been initialized or
is currently not connected to the SMSC.Cimd2Exception
- if the SMSC signaled an errorTimeoutException
public void resetSession() throws java.io.IOException, MessageException, Cimd2Exception, TimeoutException
disconnect()
, otherwise, a connection to the SMSC will
be established,a LOGOUT operation will be submitted to the SMSC and the connection will
be closed. In the later case, the service will not broadcast
any MessageEvents
to registered listeners.java.io.IOException
- if an I/O Exception of some sort occurredMessageException
- if the service is currently connected, and disconnect()
failsTimeoutException
- if the SMSC did not respond to the LOGOUT operation within reasonable
timeCimd2Exception
- if the SMSC responded with an error operationpublic StatusReportMessage getStatusReport(Message msg) throws Cimd2Exception, java.io.IOException, java.lang.IllegalArgumentException
msg
- the message for which to query a statusjava.io.IOException
- if the service is not yet initialized, a connection to
the SMSC could not be established or the communication to the SMSC unexpectedly
fails.java.lang.IllegalArgumentException
- if the passed message is either null or
doesn't contain a recipient and timestamp.Cimd2Exception
- if the SMSC responded with an error operationpublic boolean supportReadMessage()
hasCapability(Capability.RECEIVE)
instead.supportReadMessage
in interface SmsService
public void acknowledge(Message msg) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.io.IOException
ManualAck
acknowledge
in interface ManualAck
msg
- the Message to acceptjava.lang.IllegalArgumentException
- if the Message is null or not a incoming message,
or if the message has been received by another SmsService.java.lang.IllegalStateException
- if the Service is not initialized or not
connected to the SMSC.IOException
- if the communication with the SMSC fails.public void acknowledge(Message msg, java.lang.Object status) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.io.IOException
acknowledge
in interface ManualAck
msg
- the Message to acknowledgestatus
- an Integer holding the CIMD2 error code or null to accept
the message.java.lang.IllegalArgumentException
- if the Message is null or not a incoming message,
or if the message has been received by another SmsService.java.lang.IllegalArgumentException
- if the status parameter is not an
instance of java.lang.Integerjava.lang.IllegalStateException
- if the Service is not initialized or not
connected to the SMSC.java.io.IOException
- if the communication with the SMSC fails.public void enableManualAck()
ManualAck
ManualAck.acknowledge(Message)
.enableManualAck
in interface ManualAck
public void disableManualAck()
ManualAck
disableManualAck
in interface ManualAck
public boolean isManualAckEnabled()
ManualAck
isManualAckEnabled
in interface ManualAck
public int getWindowSize()
WindowingService
getWindowSize
in interface WindowingService
public void setWindowSize(int windowSize)
WindowingService
setWindowSize
in interface WindowingService
windowSize
- the window sizepublic int getNumberOfPendingMessages()
WindowingService
getNumberOfPendingMessages
in interface WindowingService
public void query(Message msg) throws java.lang.UnsupportedOperationException, java.lang.IllegalStateException, java.lang.IllegalArgumentException, MessageException
SmsService
MessageEvent
of
type STATUS_RECEIVED
.query
in interface SmsService
msg
- the previously submitted message.java.lang.UnsupportedOperationException
- if the service does not support
canceling messages.java.lang.IllegalStateException
- if the service is not initialized or not
connected to the SMSC.java.lang.IllegalArgumentException
- if the message is null or doesn't contain
the information required for querying the message status (e.g. missing
message ID).MessageException
- if querying the status failed.public void cancel(Message msg) throws java.lang.UnsupportedOperationException, java.lang.IllegalStateException, java.lang.IllegalArgumentException, MessageException
SmsService
status report
,
a MessageEvent
of type STATUS_RECEIVED
will be generated upon cancellation of the message.cancel
in interface SmsService
msg
- The previously sent messagejava.lang.UnsupportedOperationException
- if the service does not support
canceling messages.java.lang.IllegalStateException
- if the service is not initialized or not
connected to the SMSC.java.lang.IllegalArgumentException
- if the message is null or doesn't contain
the information required for cancelling the message (e.g. missing
message ID).MessageException
- if cancellation failed.public boolean hasCapability(Capability capability)
SmsService
hasCapability
in interface SmsService
capability
- one of the Constants in the Capability
class.object XP, Inc. © 2000-2013. All rights reserved object XP