|
IP*Works! V8 | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--ipworks.Smpp
The Smpp bean implements a lightweight message transmission interface using the Short Message Peer-to-Peer protocol, most known for its use in cellular text messaging.
The Smpp bean will bind as a transceiver, and thus can send and receive messages from the server. Additionally, it can send single and multi-recipient messages, and can upload data.
Using Smpp is quite easy. First, simply set the SMPPServer , SMPPPort , and, if needed, the SMPPVersion properties. Second,
a single call to the Connect method with a specified user id and
password will connect the bean.
Transmitting messages is just as easy. You can manipulate the Recipients collection
directly, or just use AddRecipient method to add recipients one-by-one to the recipient list.
After all recipients have been added, a single call to the SendMessage method
will transmit the specified message. If the send is successful, the method
will set and return the value of the MessageId property. Otherwise,
an Error event will fire for each unsuccessful message destination.
The Smpp bean supports message and data transmission, as well as
auxiliary operations such as CheckMessageStatus and ReplaceMessage . All
non-implemented features of the protocol are supported through the SendCommand method and PITrail event. Due to the nature of the
protocol, all methods and operations are implemented synchronously.
| Field Summary | |
static int |
smppMessagePriorityHigh
|
static int |
smppMessagePriorityLow
|
static int |
smppMessagePriorityNormal
|
static int |
smppMessagePriorityUrgent
|
static int |
smppServiceCBS
|
static int |
smppServiceCMT
|
static int |
smppServiceCPT
|
static int |
smppServiceDefault
|
static int |
smppServiceUSSD
|
static int |
smppServiceVMA
|
static int |
smppServiceVMN
|
static int |
smppServiceWAP
|
static int |
smppVersion33
|
static int |
smppVersion34
|
static int |
smppVersion50
|
| Constructor Summary | |
Smpp()
|
|
| Method Summary | |
void |
addRecipient(int recipientType,
java.lang.String recipientAddress)
This method will add a recipient of the specified type to the recipient list. |
void |
addSmppEventListener(ipworks.SmppEventListener l)
|
void |
cancelMessage(java.lang.String messageId)
This method will cancel the specified message. |
void |
checkLink()
This method will check the connection to the server. |
void |
checkMessageStatus(java.lang.String messageId)
This method will retrieve the status of the specified message. |
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a beanconfiguration setting. |
void |
connect(java.lang.String userId,
java.lang.String password)
This method will bind as a transceiver to the SMPP service. |
void |
disconnect()
This method will disconnect from the SMPP service. |
void |
doEvents()
This method processes events from the internal message queue. |
ipworks.Firewall |
getFirewall()
A set of properties related to firewall access. |
java.lang.String |
getMessageExpiration()
This property denotes the validity period of the current message. |
java.lang.String |
getMessageId()
This is the id of the most recently sent message. |
int |
getMessagePriority()
This is the priority level of the current message. |
java.lang.String |
getPassword()
This is the user's password. |
SMPPRecipientList |
getRecipients()
A list of message recipients. |
java.lang.String |
getScheduledDelivery()
This value tells the server when to deliver the current message. |
java.lang.String |
getSenderAddress()
The address of the ESME. |
int |
getServiceType()
This indicates the type of service for the current message. |
int |
getSMPPPort()
The server port for SMPP (default 2775). |
java.lang.String |
getSMPPServer()
This is the SMPP entity to which the component will connect. |
int |
getSMPPVersion()
This is the SMPP version to be used throughout the connection. |
java.lang.String |
getSystemType()
This is a string representing the type of system during a connection. |
int |
getTimeout()
A timeout for the bean. |
java.lang.String |
getUserId()
This value is used for identification with the SMPP service. |
void |
interrupt()
Interrupt the current method. |
boolean |
isConnected()
This property indicates whether or not the bean is bound. |
void |
removeSmppEventListener(ipworks.SmppEventListener l)
|
void |
replaceMessage(java.lang.String messageId,
java.lang.String newMessage)
This method replaces a previously sent message with a new one. |
byte[] |
sendCommand(int commandId,
byte[] payload)
This will format and send a PDU using the specified command id and payload. |
java.lang.String |
sendData(byte[] data)
This method sends raw data to Recipients . |
java.lang.String |
sendMessage(java.lang.String message)
The operation sends a message to all recipients in the recipient list. |
void |
setFirewall(ipworks.Firewall firewall)
A set of properties related to firewall access. |
void |
setMessageExpiration(java.lang.String messageExpiration)
This property denotes the validity period of the current message. |
void |
setMessagePriority(int messagePriority)
This is the priority level of the current message. |
void |
setPassword(java.lang.String password)
This is the user's password. |
void |
setRecipients(SMPPRecipientList recipients)
A list of message recipients. |
void |
setScheduledDelivery(java.lang.String scheduledDelivery)
This value tells the server when to deliver the current message. |
void |
setSenderAddress(java.lang.String senderAddress)
The address of the ESME. |
void |
setServiceType(int serviceType)
This indicates the type of service for the current message. |
void |
setSMPPPort(int SMPPPort)
The server port for SMPP (default 2775). |
void |
setSMPPServer(java.lang.String SMPPServer)
This is the SMPP entity to which the component will connect. |
void |
setSMPPVersion(int SMPPVersion)
This is the SMPP version to be used throughout the connection. |
void |
setSystemType(java.lang.String systemType)
This is a string representing the type of system during a connection. |
void |
setTimeout(int timeout)
A timeout for the bean. |
void |
setUserId(java.lang.String userId)
This value is used for identification with the SMPP service. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int smppMessagePriorityLow
public static final int smppMessagePriorityNormal
public static final int smppMessagePriorityHigh
public static final int smppMessagePriorityUrgent
public static final int smppServiceDefault
public static final int smppServiceCMT
public static final int smppServiceCPT
public static final int smppServiceVMN
public static final int smppServiceVMA
public static final int smppServiceWAP
public static final int smppServiceUSSD
public static final int smppServiceCBS
public static final int smppVersion50
public static final int smppVersion34
public static final int smppVersion33
| Constructor Detail |
public Smpp()
| Method Detail |
public boolean isConnected()
This value shows whether or not the bean has successfully
bound to the SMPPServer . It will not be true until a
successful Connected event has fired.
There are two ways to bind: by calling Connect whith a user
id and password and will set the UserId and Password properties before connecting; or by setting those two properties
and calling SendMessage while not connected.
public ipworks.Firewall getFirewall()
This is a FIREWALL type property which
contains fields describing the firewall
through which the bean will attempt to connect.
public void setFirewall(ipworks.Firewall firewall)
throws IPWorksException
This is a FIREWALL type property which
contains fields describing the firewall
through which the bean will attempt to connect.
IPWorksExceptionpublic java.lang.String getMessageExpiration()
The MessageExpiration property indicates the MC expiration time,
after which the message should be discarded if not delivered to the
desintation. It can be set using absolute or relative time formats.
Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:
Relative Time Format is the same 16-character string where "p" should be set to "R" for "relative". For relative time, "tnn" are ignored and thus should be set to a constant value of "000".
public void setMessageExpiration(java.lang.String messageExpiration)
throws IPWorksException
The MessageExpiration property indicates the MC expiration time,
after which the message should be discarded if not delivered to the
desintation. It can be set using absolute or relative time formats.
Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:
Relative Time Format is the same 16-character string where "p" should be set to "R" for "relative". For relative time, "tnn" are ignored and thus should be set to a constant value of "000".
IPWorksExceptionpublic java.lang.String getMessageId()
After a successful call to SendMessage , the MessageId property will be set to the server-assigned id of that message.
public int getMessagePriority()
When sending a message, the MessagePriority property will
tell the server what type of priority to assign to the
message. The effect of the message priority setting is
dependent upon the Message Center manufacturer and the network
on which the target recipient lies. For example, some
MCs may immediately forward "urgent" messages, some
networks may use the priority setting as a visual indicator
of the message's urgency (e.g. blinking icons, etc.), and
some networks may entirely ignore the priority setting.
public void setMessagePriority(int messagePriority)
throws IPWorksException
When sending a message, the MessagePriority property will
tell the server what type of priority to assign to the
message. The effect of the message priority setting is
dependent upon the Message Center manufacturer and the network
on which the target recipient lies. For example, some
MCs may immediately forward "urgent" messages, some
networks may use the priority setting as a visual indicator
of the message's urgency (e.g. blinking icons, etc.), and
some networks may entirely ignore the priority setting.
IPWorksExceptionpublic java.lang.String getPassword()
When binding to the SMPPServer , the client must provide
a known user id and a valid password for that id.
There are two ways to bind: by calling Connect whith a user
id and password and will set the UserId and Password properties before connecting; or by setting those two properties
and calling SendMessage while not connected.
public void setPassword(java.lang.String password)
throws IPWorksException
When binding to the SMPPServer , the client must provide
a known user id and a valid password for that id.
There are two ways to bind: by calling Connect whith a user
id and password and will set the UserId and Password properties before connecting; or by setting those two properties
and calling SendMessage while not connected.
IPWorksExceptionpublic SMPPRecipientList getRecipients()
This property is how you specify the recipient(s)
of the message. Each recipient is represented by an SMPPRECIPIENT type, which contains fields for the address and type of address for the recipient.
There is an AddRecipient method which also
may be used to add recipients to this collection
property.
This collection is indexed from 0 to Count - 1.
public void setRecipients(SMPPRecipientList recipients)
throws IPWorksException
This property is how you specify the recipient(s)
of the message. Each recipient is represented by an SMPPRECIPIENT type, which contains fields for the address and type of address for the recipient.
There is an AddRecipient method which also
may be used to add recipients to this collection
property.
This collection is indexed from 0 to Count - 1.
IPWorksExceptionpublic java.lang.String getScheduledDelivery()
ScheduledDelivery is used by the bean when sending a
message to inform the Message Center (MC) to forward the message
to the intended recipients at a specific time. It can be set
using absolute or relative time formats.
Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:
Relative Time Format is the same 16-character string where "p" should be set to "R" for "relative". For relative time, "tnn" are ignored and thus should be set to a constant value of "000".
public void setScheduledDelivery(java.lang.String scheduledDelivery)
throws IPWorksException
ScheduledDelivery is used by the bean when sending a
message to inform the Message Center (MC) to forward the message
to the intended recipients at a specific time. It can be set
using absolute or relative time formats.
Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:
Relative Time Format is the same 16-character string where "p" should be set to "R" for "relative". For relative time, "tnn" are ignored and thus should be set to a constant value of "000".
IPWorksExceptionpublic java.lang.String getSenderAddress()
The SMPP protocol allows an External Short Messaging Entity (ESME) to specify its
address, whether it is a phone number or an IP address. If SenderAddress is not set, the bean will default to the value in LocalHost .
public void setSenderAddress(java.lang.String senderAddress)
throws IPWorksException
The SMPP protocol allows an External Short Messaging Entity (ESME) to specify its
address, whether it is a phone number or an IP address. If SenderAddress is not set, the bean will default to the value in LocalHost .
IPWorksExceptionpublic int getServiceType()
When sending messages, the ServiceType property is used
define the SMS application service to be associated with the
message. The MC will use the value to determine the
availability of enhanced messaging services and to control
the teleservice used on the air interface.
The values are defined in the SMPP 5.0 specification as the following:
public void setServiceType(int serviceType)
throws IPWorksException
When sending messages, the ServiceType property is used
define the SMS application service to be associated with the
message. The MC will use the value to determine the
availability of enhanced messaging services and to control
the teleservice used on the air interface.
The values are defined in the SMPP 5.0 specification as the following:
IPWorksExceptionpublic int getSMPPPort()
A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
public void setSMPPPort(int SMPPPort)
throws IPWorksException
A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed once a connection is established. Any attempt to change this property while connected will fail with an error.
IPWorksExceptionpublic java.lang.String getSMPPServer()
This is the instant messaging server to which the bean will connect
when the Connect method is called. The SMPPServer property must
contain a valid SMPP service application address.
public void setSMPPServer(java.lang.String SMPPServer)
throws IPWorksException
This is the instant messaging server to which the bean will connect
when the Connect method is called. The SMPPServer property must
contain a valid SMPP service application address.
IPWorksExceptionpublic int getSMPPVersion()
Currently, the most widely used version of the SMPP protocol is
version 3.4. However, since the newest version is 5.0, the default
value for the bean is smppVersion50 (0). The value is used by
the bean when binding to the SMPPServer to indicate
to the server which version of the protocol to use when
interpreting commands received from the bean.
Changing the value will not limit the functionality of the bean
when performing any operation, as each version of SMPP is backward
compatible with previous implementations. However, if the SMPPServer does not recognize a particular command, it will
respond with an error indicating that the PDU was erred. Which
commands are recognizable is strictly dependent on the
implementation of the server, and the adherence to protocol
guidelines of that implementation.
public void setSMPPVersion(int SMPPVersion)
throws IPWorksException
Currently, the most widely used version of the SMPP protocol is
version 3.4. However, since the newest version is 5.0, the default
value for the bean is smppVersion50 (0). The value is used by
the bean when binding to the SMPPServer to indicate
to the server which version of the protocol to use when
interpreting commands received from the bean.
Changing the value will not limit the functionality of the bean
when performing any operation, as each version of SMPP is backward
compatible with previous implementations. However, if the SMPPServer does not recognize a particular command, it will
respond with an error indicating that the PDU was erred. Which
commands are recognizable is strictly dependent on the
implementation of the server, and the adherence to protocol
guidelines of that implementation.
IPWorksExceptionpublic java.lang.String getSystemType()
Some SMS servers require that a system type be supplied during connection. The system type is a string representation, usually as an abbreviation, of a particular kind of system. The string cannot exceed 12 bytes.
public void setSystemType(java.lang.String systemType)
throws IPWorksException
Some SMS servers require that a system type be supplied during connection. The system type is a string representation, usually as an abbreviation, of a particular kind of system. The string cannot exceed 12 bytes.
IPWorksExceptionpublic int getTimeout()
If the Timeout property is set to 0, all operations
will run uninterrupted until successful completion, or an error condition
is encountered.
If Timeout is set to a positive value, the bean will
wait for the operation to complete before returning control.
The bean will use DoEvents to enter an efficient wait loop
during any potential waiting period, making sure that all system events
are processed immediately as they arrive. This ensures that the host
application does not "freeze" and remains responsive.
If Timeout expires, and the operation is not yet complete,
the bean throws an IPWorksException
raises an IPWorksException exception
.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout seconds when
data is successfully sent or received.
Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum
of Timeout seconds since the beginning of the operation, without
extending the timeout period during communications.
This behavior is controlled by theAbsoluteTimeoutconfiguration setting.
The default value for the Timeout property is 60 (seconds).
public void setTimeout(int timeout)
throws IPWorksException
If the Timeout property is set to 0, all operations
will run uninterrupted until successful completion, or an error condition
is encountered.
If Timeout is set to a positive value, the bean will
wait for the operation to complete before returning control.
The bean will use DoEvents to enter an efficient wait loop
during any potential waiting period, making sure that all system events
are processed immediately as they arrive. This ensures that the host
application does not "freeze" and remains responsive.
If Timeout expires, and the operation is not yet complete,
the bean throws an IPWorksException
raises an IPWorksException exception
.
Please note that by default, all timeouts are inactivity timeouts ,
i.e. the timeout period is extended by Timeout seconds when
data is successfully sent or received.
Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum
of Timeout seconds since the beginning of the operation, without
extending the timeout period during communications.
This behavior is controlled by theAbsoluteTimeoutconfiguration setting.
The default value for the Timeout property is 60 (seconds).
IPWorksExceptionpublic java.lang.String getUserId()
When binding to the SMPPServer , the client must provide
a known user id and a valid password for that id.
There are two ways to bind: by calling Connect whith a user
id and password and will set the UserId and Password properties before connecting; or by setting those two properties
and calling SendMessage while not connected.
public void setUserId(java.lang.String userId)
throws IPWorksException
When binding to the SMPPServer , the client must provide
a known user id and a valid password for that id.
There are two ways to bind: by calling Connect whith a user
id and password and will set the UserId and Password properties before connecting; or by setting those two properties
and calling SendMessage while not connected.
IPWorksException
public void addRecipient(int recipientType,
java.lang.String recipientAddress)
throws IPWorksException
For normal-type recipients, the addresses should be either a dotted IPv4 address (for sending messages to other SMS-enabled applications) or the directory number of a mobile phone. For sending messages to distributed lists, the name of the list should be used.
IPWorksException
public void cancelMessage(java.lang.String messageId)
throws IPWorksException
The CancelMessage method will cancel the message stored on the SMPPServer under the value in MessageId .
IPWorksException
public void checkLink()
throws IPWorksException
The check link operation is mostly used to ensure that the host
on the other end of the connection is still active, or that it
is still available. While a socket connection may still be
available between the client and server, the SMS application
on the server may have been taken offline without releasing
the socket, or the CPU may be bogged down, etc. The CheckLink method will send a PDU to the server and wait
the length of Timeout for a response.
IPWorksException
public void checkMessageStatus(java.lang.String messageId)
throws IPWorksException
CheckMessageStatus will retrieve the last known status of the message stored on the server under MessageId . The bean will fire a MessageStatus containing the parsed response from the server.
IPWorksException
public java.lang.String config(java.lang.String configurationString)
throws IPWorksException
Config is a generic method available in every bean.
It is used to set and retrieveconfiguration settingsfor the
bean.
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config method.
To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.
IPWorksException
public void connect(java.lang.String userId,
java.lang.String password)
throws IPWorksException
The Connect method will establish a socket connection to
the SMPPServer and attempt to bind as a transceiver. Once
the bind operation has completed, a Connected event will
be fired containing the status of the connection.
IPWorksException
public void disconnect()
throws IPWorksException
Disconnect will send an unbind command and close the socket
connection to the SMPPServer . After a unbind operation and
socket closing, a Disconnected event will be fired
containing the status of the unbind operation.
IPWorksException
public void doEvents()
throws IPWorksException
When DoEvents is called, the bean processes any
available events. If no events are available, it waits for a
preset period of time, and then returns.
IPWorksException
public void interrupt()
throws IPWorksException
If there is no method in progress, Interrupt simply returns doing nothing.
IPWorksException
public void replaceMessage(java.lang.String messageId,
java.lang.String newMessage)
throws IPWorksException
Assuming that there is a message on the SMPPServer stored under
the value in MessageId , ReplaceMessage will replace that
message with the value in NewMessage .
If there is no message corresponding to MessageId , the SMS service will respond with an error message.
IPWorksException
public byte[] sendCommand(int commandId,
byte[] payload)
throws IPWorksException
The SendCommand method offers a way to do more with the bean
than is directly supported. This method takes a command id and a payload,
which includes every required and optional field after the header, and
will create the 16-byte header for it before sending it to the server.
The response PDU is returned both in the PITrail and by this method.
IPWorksException
public java.lang.String sendData(byte[] data)
throws IPWorksException
Recipients .
Up to 64KB of additional data can be supplied at a time for
transmission to the SMPPServer . Unlike the SendMessage method, SendData can only send to one destination at a
time. The target is whatever value is in the Recipients collection.
IPWorksException
public java.lang.String sendMessage(java.lang.String message)
throws IPWorksException
The message sent is specified by the MessageText property.
The return value of SendMessage is the server-assigned id of the message.
IPWorksException
public void addSmppEventListener(ipworks.SmppEventListener l)
throws java.util.TooManyListenersException
java.util.TooManyListenersExceptionpublic void removeSmppEventListener(ipworks.SmppEventListener l)
|
IP*Works! V8 | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||