IP*Works! V9

ipworks
Class Smpp

java.lang.Object
  extended by ipworks.Smpp

public class Smpp
extends java.lang.Object

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 smppCIMD2
           
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 smppSMPP
           
static int smppVersion33
           
static int smppVersion34
           
static int smppVersion50
           
 
Constructor Summary
Smpp()
          Creates an instance of Smpp Bean.
Smpp(java.lang.String runtimeLicense)
          Creates an instance of Smpp Bean with specified run-time license.
 
Method Summary
 void addRecipient(int recipientType, java.lang.String recipientAddress)
          Will add a recipient of the specified type to the recipient list.
 void addSmppEventListener(SmppEventListener l)
           
 void cancelMessage(java.lang.String messageId)
          Will cancel the specified message.
 void checkLink()
          Will check the connection to the server.
 void checkMessageStatus(java.lang.String messageId)
          Will retrieve the status of the specified message.
 java.lang.String config(java.lang.String configurationString)
          Sets or retrieves a configuration setting.
 void connect(java.lang.String userId, java.lang.String password)
          Will bind as a transceiver to the SMPP service.
 void disconnect()
          Will disconnect from the SMPP service.
 void doEvents()
          Processes events from the internal message queue.
 Firewall getFirewall()
          A set of properties related to firewall access.
 java.lang.String getLocalHost()
          The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
 java.lang.String getMessageExpiration()
          Denotes the validity period of the current message.
 java.lang.String getMessageId()
          The identifier of the most recently sent message.
 int getMessagePriority()
          The priority level of the current message.
 java.lang.String getPassword()
          Contains the user's password.
 int getProtocol()
          The SMPP protocol to be used.
 SMPPRecipientList getRecipients()
          A list of message recipients.
 java.lang.String getScheduledDelivery()
          Tells the server when to deliver the current message.
 java.lang.String getSenderAddress()
          The address of the ESME.
 int getServiceType()
          Indicates the type of service for the current message.
 int getSMPPPort()
          The server port for SMPP (default 2775).
 java.lang.String getSMPPServer()
          The SMPP entity to which the component will connect.
 int getSMPPVersion()
          The SMPP version to be used throughout the connection.
 java.lang.String getSystemType()
          A string representing the type of system during a connection.
 int getTimeout()
          A timeout for the bean.
 java.lang.String getUserId()
          Used for identification with the SMPP service.
 void interrupt()
          Interrupt the current method.
 boolean isConnected()
          Indicates whether or not the bean is bound.
 boolean isIdle()
          The current status of the component.
 void removeSmppEventListener(SmppEventListener l)
           
 void replaceMessage(java.lang.String messageId, java.lang.String newMessage)
          Replaces a previously sent message with a new one.
 byte[] sendCommand(int commandId, byte[] payload)
          Will format and send a PDU using the specified command identifier and payload.
 java.lang.String sendData(byte[] data)
          Sends raw data to Recipients .
 java.lang.String sendMessage(java.lang.String message)
          Sends a message to all recipients in the recipient list.
 void setFirewall(Firewall firewall)
          A set of properties related to firewall access.
 void setLocalHost(java.lang.String localHost)
          The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
 void setMessageExpiration(java.lang.String messageExpiration)
          Denotes the validity period of the current message.
 void setMessagePriority(int messagePriority)
          The priority level of the current message.
 void setPassword(java.lang.String password)
          Contains the user's password.
 void setProtocol(int protocol)
          The SMPP protocol to be used.
 void setScheduledDelivery(java.lang.String scheduledDelivery)
          Tells the server when to deliver the current message.
 void setSenderAddress(java.lang.String senderAddress)
          The address of the ESME.
 void setServiceType(int serviceType)
          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)
          The SMPP entity to which the component will connect.
 void setSMPPVersion(int SMPPVersion)
          The SMPP version to be used throughout the connection.
 void setSystemType(java.lang.String systemType)
          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)
          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

smppMessagePriorityLow

public static final int smppMessagePriorityLow
See Also:
Constant Field Values

smppMessagePriorityNormal

public static final int smppMessagePriorityNormal
See Also:
Constant Field Values

smppMessagePriorityHigh

public static final int smppMessagePriorityHigh
See Also:
Constant Field Values

smppMessagePriorityUrgent

public static final int smppMessagePriorityUrgent
See Also:
Constant Field Values

smppSMPP

public static final int smppSMPP
See Also:
Constant Field Values

smppCIMD2

public static final int smppCIMD2
See Also:
Constant Field Values

smppServiceDefault

public static final int smppServiceDefault
See Also:
Constant Field Values

smppServiceCMT

public static final int smppServiceCMT
See Also:
Constant Field Values

smppServiceCPT

public static final int smppServiceCPT
See Also:
Constant Field Values

smppServiceVMN

public static final int smppServiceVMN
See Also:
Constant Field Values

smppServiceVMA

public static final int smppServiceVMA
See Also:
Constant Field Values

smppServiceWAP

public static final int smppServiceWAP
See Also:
Constant Field Values

smppServiceUSSD

public static final int smppServiceUSSD
See Also:
Constant Field Values

smppServiceCBS

public static final int smppServiceCBS
See Also:
Constant Field Values

smppVersion50

public static final int smppVersion50
See Also:
Constant Field Values

smppVersion34

public static final int smppVersion34
See Also:
Constant Field Values

smppVersion33

public static final int smppVersion33
See Also:
Constant Field Values
Constructor Detail

Smpp

public Smpp()
Creates an instance of Smpp Bean.


Smpp

public Smpp(java.lang.String runtimeLicense)
Creates an instance of Smpp Bean with specified run-time license.

Method Detail

isConnected

public boolean isConnected()
Indicates whether or not the bean is bound.

The value of this property indicates 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 with a user identifier and password which will set the UserId and Password properties before connecting; or by setting those two properties and calling SendMessage while not connected.


getFirewall

public Firewall getFirewall()
A set of properties related to firewall access.

This is a Firewall type property which contains fields describing the firewall through which the bean will attempt to connect.


setFirewall

public void setFirewall(Firewall firewall)
                 throws IPWorksException
A set of properties related to firewall access.

This is a Firewall type property which contains fields describing the firewall through which the bean will attempt to connect.

Throws:
IPWorksException

isIdle

public boolean isIdle()
The current status of the component.

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.


getLocalHost

public java.lang.String getLocalHost()
The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.


setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException
The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

Throws:
IPWorksException

getMessageExpiration

public java.lang.String getMessageExpiration()
Denotes the validity period of the current message.

This property indicates the MC expiration time, after which the message should be discarded if not delivered to the destination. It can be set using absolute or relative time formats.

Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:

YY
the last two digits of the year (00-99)
MM
month (01-12)
DD
day (01-31)
hh
hour (00-23)
mm
minute (00-59)
ss
second (00-59)
t
tenths of a second (0-9)
nn
quarter-hour time difference between local time and UTC time (00-48)
p
"+" or "-" indicating the direction of the time offset in nn

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".


setMessageExpiration

public void setMessageExpiration(java.lang.String messageExpiration)
                          throws IPWorksException
Denotes the validity period of the current message.

This property indicates the MC expiration time, after which the message should be discarded if not delivered to the destination. It can be set using absolute or relative time formats.

Absolute Time Format is a 16-character string represented as "YYMMDDhhmmsstnnp" where:

YY
the last two digits of the year (00-99)
MM
month (01-12)
DD
day (01-31)
hh
hour (00-23)
mm
minute (00-59)
ss
second (00-59)
t
tenths of a second (0-9)
nn
quarter-hour time difference between local time and UTC time (00-48)
p
"+" or "-" indicating the direction of the time offset in nn

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".

Throws:
IPWorksException

getMessageId

public java.lang.String getMessageId()
The identifier of the most recently sent message.

This property indicates the identifier of the most recently sent message. After a successful call to SendMessage , this property will be set to the server-assigned id of that message.


getMessagePriority

public int getMessagePriority()
The priority level of the current message.

When sending a message, this 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.


setMessagePriority

public void setMessagePriority(int messagePriority)
                        throws IPWorksException
The priority level of the current message.

When sending a message, this 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.

Throws:
IPWorksException

getPassword

public java.lang.String getPassword()
Contains the user's password.

This property contains the user's password. When binding to the SMPPServer , the client must provide a known user identifier and a valid password for that ID.

There are two ways to bind: by calling Connect with a user identifier and password which will set the UserId and this property properties before connecting; or by setting those two properties and calling SendMessage while not connected.


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
Contains the user's password.

This property contains the user's password. When binding to the SMPPServer , the client must provide a known user identifier and a valid password for that ID.

There are two ways to bind: by calling Connect with a user identifier and password which will set the UserId and this property properties before connecting; or by setting those two properties and calling SendMessage while not connected.

Throws:
IPWorksException

getProtocol

public int getProtocol()
The SMPP protocol to be used.

This property defines the protocol to be used when connecting to the server. Possible values are:

0 (smppSMPP - default)
SMPP for traditional SMPP servers
1 (smppCIMD2)\011\011\011\011\011
CIMD2 for Nokia Short Message Service Center servers


setProtocol

public void setProtocol(int protocol)
                 throws IPWorksException
The SMPP protocol to be used.

This property defines the protocol to be used when connecting to the server. Possible values are:

0 (smppSMPP - default)
SMPP for traditional SMPP servers
1 (smppCIMD2)\011\011\011\011\011
CIMD2 for Nokia Short Message Service Center servers

Throws:
IPWorksException

getRecipients

public SMPPRecipientList getRecipients()
A list of message recipients.

This property is used to 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 size - 1.


getScheduledDelivery

public java.lang.String getScheduledDelivery()
Tells the server when to deliver the current message.

This property 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:

YY
the last two digits of the year (00-99)
MM
month (01-12)
DD
day (01-31)
hh
hour (00-23)
mm
minute (00-59)
ss
second (00-59)
t
tenths of a second (0-9)
nn
quarter-hour time difference between local time and UTC time (00-48)
p
"+" or "-" indicating the direction of the time offset in nn

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".


setScheduledDelivery

public void setScheduledDelivery(java.lang.String scheduledDelivery)
                          throws IPWorksException
Tells the server when to deliver the current message.

This property 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:

YY
the last two digits of the year (00-99)
MM
month (01-12)
DD
day (01-31)
hh
hour (00-23)
mm
minute (00-59)
ss
second (00-59)
t
tenths of a second (0-9)
nn
quarter-hour time difference between local time and UTC time (00-48)
p
"+" or "-" indicating the direction of the time offset in nn

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".

Throws:
IPWorksException

getSenderAddress

public java.lang.String getSenderAddress()
The address of the ESME.

This property contains the address of the ESME. 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 This property is not set, the bean will default to the value in LocalHost .


setSenderAddress

public void setSenderAddress(java.lang.String senderAddress)
                      throws IPWorksException
The address of the ESME.

This property contains the address of the ESME. 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 This property is not set, the bean will default to the value in LocalHost .

Throws:
IPWorksException

getServiceType

public int getServiceType()
Indicates the type of service for the current message.

When sending messages, this 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:

"" (NULL)
the MC default
CMT
Cellular Messaging
CPT
Cellular Paging
VMN
Voice Mail Notification
VMA
Voice Mail Alerting
WAP
Wireless Application Protocol
USSD
Unstructured Supplementary Services Data
CBS
Cell Broadcast Service


setServiceType

public void setServiceType(int serviceType)
                    throws IPWorksException
Indicates the type of service for the current message.

When sending messages, this 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:

"" (NULL)
the MC default
CMT
Cellular Messaging
CPT
Cellular Paging
VMN
Voice Mail Notification
VMA
Voice Mail Alerting
WAP
Wireless Application Protocol
USSD
Unstructured Supplementary Services Data
CBS
Cell Broadcast Service

Throws:
IPWorksException

getSMPPPort

public int getSMPPPort()
The server port for SMPP (default 2775).

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.


setSMPPPort

public void setSMPPPort(int SMPPPort)
                 throws IPWorksException
The server port for SMPP (default 2775).

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.

Throws:
IPWorksException

getSMPPServer

public java.lang.String getSMPPServer()
The SMPP entity to which the component will connect.

This property is the instant messaging server to which the bean will connect when the Connect method is called. This property must contain a valid SMPP service application address.


setSMPPServer

public void setSMPPServer(java.lang.String SMPPServer)
                   throws IPWorksException
The SMPP entity to which the component will connect.

This property is the instant messaging server to which the bean will connect when the Connect method is called. This property must contain a valid SMPP service application address.

Throws:
IPWorksException

getSMPPVersion

public int getSMPPVersion()
The SMPP version to be used throughout the connection.

This property contains the SMPP version to be used throughout the connection.

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.


setSMPPVersion

public void setSMPPVersion(int SMPPVersion)
                    throws IPWorksException
The SMPP version to be used throughout the connection.

This property contains the SMPP version to be used throughout the connection.

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.

Throws:
IPWorksException

getSystemType

public java.lang.String getSystemType()
A string representing the type of system during a connection.

This property contains a string representing the type of system during a connection. 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.


setSystemType

public void setSystemType(java.lang.String systemType)
                   throws IPWorksException
A string representing the type of system during a connection.

This property contains a string representing the type of system during a connection. 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.

Throws:
IPWorksException

getTimeout

public int getTimeout()
A timeout for the bean.

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 exception.

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

Optionally, the behavior 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 the AbsoluteTimeout configuration setting.

The default value for the Timeout property is 60 (seconds).


setTimeout

public void setTimeout(int timeout)
                throws IPWorksException
A timeout for the bean.

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 exception.

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when any amount of data is successfully sent or received.

Optionally, the behavior 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 the AbsoluteTimeout configuration setting.

The default value for the Timeout property is 60 (seconds).

Throws:
IPWorksException

getUserId

public java.lang.String getUserId()
Used for identification with the SMPP service.

This property is used for identification with the SMPP service. When binding to the SMPPServer , the client must provide a known user identifier and a valid password for that ID.

There are two ways to bind: by calling Connect with 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.


setUserId

public void setUserId(java.lang.String userId)
               throws IPWorksException
Used for identification with the SMPP service.

This property is used for identification with the SMPP service. When binding to the SMPPServer , the client must provide a known user identifier and a valid password for that ID.

There are two ways to bind: by calling Connect with 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.

Throws:
IPWorksException

addRecipient

public void addRecipient(int recipientType,
                         java.lang.String recipientAddress)
                  throws IPWorksException
Will add a recipient of the specified type to the recipient list.

This method will add a recipient of the specified type to the recipient list. 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.

Valid values for RecipientType are:

0 (smppRecipientTypeNormal)
Normal SME (Short Message Entity) Address
1 (smppRecipientTypeList)
Distribution List

Throws:
IPWorksException

cancelMessage

public void cancelMessage(java.lang.String messageId)
                   throws IPWorksException
Will cancel the specified message.

This method will cancel the message stored on the SMPPServer under the value in MessageId .

Throws:
IPWorksException

checkLink

public void checkLink()
               throws IPWorksException
Will check the connection to the server.

This method will check the connection to the server. This method is 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. This method will send a PDU to the server and wait the length of Timeout for a response.

Throws:
IPWorksException

checkMessageStatus

public void checkMessageStatus(java.lang.String messageId)
                        throws IPWorksException
Will retrieve the status of the specified message.

This method 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.

Throws:
IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException
Sets or retrieves a configuration setting.

Config is a generic method available in every bean. It is used to set and retrieve configuration settings for 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.

The bean accepts one or more of the following configuration settings . 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.

SMPP Configuration Settings

AddressRange
Specifies the addr_range parameter when binding
The addr_range parameter is used when binding as a receiver or transceiver to specify a set of SME addresses serviced by the ESME client. A single SME address may also be specified in the address_range parameter. UNIX Regular Expression notation should be used to specify a range of addresses. Messages addressed to any destination in this range shall be routed to the ESME.Note 1: For IP addresses, it is only possible to specify a single IP address. A range of IP addresses are not allowed. IP version 6.0 is not currently supported in this version of the protocol.

Note 2: It is likely that the addr_range field is not supported or deliberately ignored on most Message Centres. The reason for this is that most carriers will not allow an ESME control the message routing as this can carry the risk of mis-routing messages. In such circumstances, the ESME will be requested to set the field to NULL.

BindAsReceiver
Causes the component to bind as a receiver
Setting this will instruct the component to bind to the SMPP service as a receiver instead of a transceiver.
BindAsTransmitter
Causes the component to bind as a transmitter
Setting this will instruct the component to bind to the SMPP service as a transmitter instead of a transceiver.
DataCoding
The data encoding mechanism to be used for the current message
This value informs the message recipient about how the data was encoded. The possible values are as follows:
0
MC Specific encoding
1
IA5 (CCITT T.50)/ASCII (ANSI X3.4)
2
Octet unspecified (8-bit binary)
3
Latin 1 (ISO-8859-1)
4
Octet unspecified (8-bit binary)
5
JIS (X 0208-1990)
6
Cyrillic (ISO-8859-5)
7
Latin/Hebrew (ISO-8859-8)
8
UCS2 (ISO/IEC-10646)
9
Pictogram Encoding
10
ISO-2022-JP (Music Codes)
11
Reserved
12
Reserved 2
13
Extended Kanji JIS (X 0212-1990)
14
KS C 5601
DestinationNPI
The Number Planning Indicator for the destination ESME
When sending messages, this value is used to indicate the numbering plan the destination ESME. For a list of possible values, please see SourceNPI .
DestinationTON
The Type of Number for the destination ESME
When sending messages, this value is used to indicate the Type of Number for the destination ESME. For a list of possible values, please see SourceTON .
HexString
A hex-encoded binary string to be sent to the current recipient
Setting this config property will cause the component to internally call SendMessage with the binary contents of the hex-encoded string. The return value when setting this property is the server-assigned id of the message. Querying this property will result in an empty string.
IntermediateNotification
Causes the component to request intermediate notification
Setting this will request intermediate notification. By default, intermediate notification is not requested.
MCReceipt
The Type of MC Delivery Receipt requested
When sending a message, this value is used to determine whether or not an MC delivery receipt is requested. This value is 0 by default, and no receipt is requested. The possible values are:
0
No MC Delivery Receipt requested (default).
1
MC Delivery Receipt is requested after final delivery (success or failure).
2
MC Delivery Receipt is requested after a failed delivery.
3
MC Delivery Receipt is requested after a successful delivery.
MessageInReceiptedMessageId
The receipted_message_id field of an incoming deliver_sm PDU
This value indicates the ID of the message being receipted in a MC Delivery Receipt. Note that this is only applicable within the MessageIn event.
MessageMode
The Type of Messaging Mode requested
When sending a message, this value is used to specify the Messaging Mode in the outgoing request. For incoming messages this value can be queried from within the MessageIn event. The possible values are:
0
Default SMSC Mode (e.g. Store and Forward).
1
Datagram mode.
2
Forward (i.e. Transaction) mode.
3
Store and Forward mode.
MessageType
The Type of Message
When sending a message, this value is used to specify the Message Type in the outgoing request. For incoming messages this value can be queried from within the MessageIn event. The possible values are:
0
Default message Type (i.e. normal message).
1
Short Message contains MC Delivery Receipt.
2
Short Message contains Intermediate Delivery Notification.
ProtocolId
The protocol identifier
This config property allows control of the protocol identifier field value used in the outgoing messages.
SMEAcknowledgement
The Type of SME originated acknowledgement requested
When sending a message, this value is used to determine whether or not an SME acknowledgement is requested. This value is 0 by default, and no acknowledgement is requested. The possible values are:
0
No SME acknowledgement requested (default).
1
SME delivery acknowledgement is requested.
2
SME manual/user acknowledgement is requested.
3
Both delivery and manual/user acknowledgement is requested.
SplitLargeMessages
Determines whether large messages are split into multiple parts
The default value is false. If set to true and the message is larger than 140 characters the message will automatically be split into parts when SendMessage is called. Note that this is only valid for GSM networks.When receiving a message that has been split, the MessageIn event provides parameters to re-assemble the message.

SplitMessageMethod
Determines how large messages are split into multiple parts
The component can split large messages using either the UDH or SAR method. The mode used is determined by this configuration option. The possible values are:
0
UDH (Default)
1
SAR
SourceNPI
The Number Planning Indicator for the ESME
When binding, this value is used to specify the numbering plan of the ESME. Mobiles tend to set this value to 1. Since most ESMEs are mobiles, the default value for SourceNPI is 1. The possible value are:
Unknown (0)
ISDN (1)
Data (3)
Telex (4)
LandMobile (6)
National (8)
Private (9)
ERMES (10)
Internet (14)
WAP (18)
SourceTON
The Type of Number for the ESME
When binding, this value is used to indicate the Type of Number for the ESME address. The possible values are:
Unknown (0)
The number type is unknown
International (1)
The number includes the international trunk prefix
National (2)
The number includes the national trunk prefix
NetworkSpecific (3)
The number exists on a network that uses a specific delivery protocol
SubscriberNumber (4)
The number is just the subscriber number, without prefixes
Alphanumeric (5)
The address is human-readable (contains letters and digits)
Abbreviated (6)
The number is abbreviated
SynchronousSendCommand
Controls whether behaves synchronously or asynchronously
The default value is true which means SendCommand will not return until a response has been received. If set to false the bean returns and does not wait for a response from the server.
SynchronousSendMessage
Controls whether behaves synchronously or asynchronously
The default value is true which means SendMessage will not return until a response has been received. If set to false the bean returns the sequence number used and does not wait for a response from the server. You may then monitor the PITrail event to match the response from the server to the sent message.
CustomTLV
Optional TLV parameters added after the mandatory parameters and before the payload
The format of a TLV parameter is:
  • One two-byte integer containing the parameter type (tag).
  • One two-byte integer indicating the length of the data contained in this parameter.
  • The variable-length parameter data itself.
All of this must then be hex-encoded before setting the CustomTLV configuration setting.For instance, to add a gn_lookup_userdata parameter, the type/tag is decimal 5633 (that's 0x1601 in hex), and the data in this example is "Hello World" , which is 11 characters in length. So the TLV is: 5633 + 11 + "Hello World", or 0x16 0x01 0x00 0x0b and then the ASCII text "Hello World". When hex-encoded, this yields the string "1601000b48656c6c6f20576f726c64". This is the value you would then use to set the CustomTLV configuration setting. You are not restricted to only one optional parameter. Multiple TLV parameters may be concatenated together.

Note that this is advanced functionality, and the bean does not verify the data in this configuration setting prior to transmission. After the bean internally decodes the string back into binary, it is passed on inside the PDU as-is without validation or modification.

This setting is only applicable when using the SendMessage or SendData methods.

SubAddr
Defines a unique index for application instance
This is useful for correct delivery of status reports when multiple instances of the same application are connected.This setting is only applicable when Protocol is set to smppCIMD2 .

StatusReportRequest
Defines in what cases a status report is created by the server
This is only applicable when Protocol is set to smppCIMD2 . This may be set to request that the server create a status report for the given conditions. The assigned value should be the sum of all desired conditions. For instance a value of 62 means that a report should be created for all events except for a temporary error. Possible flags are:
1
Temporary Error
2
Validity Period Expired
4
Delivery Failed
8
Delivery Successful
16
Message Cancelled
32
Message Deleted By The Operator
WaitForBanner
Specifies the CIMD2 banner the bean will wait for when connecting
This is only applicable when Protocol is set to smppCIMD2 . If set, the bean will wait for a banner containing this string to be returned by the server before proceeding with the connection.

IPPort Configuration Settings

FirewallAutoDetect
Tells the bean whether or not to automatically detect and use firewall system settings, if available
This is the same as AutoDetect . This setting is provided for use by beans that do not directly expose Firewall properties.
FirewallHost
Name or IP address of firewall (optional)
If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.If the FirewallHost setting is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost setting is set to the corresponding address. If the search is not successful, an error is returned.

NOTE: This is the same as Host . This setting is provided for use by beans that do not directly expose Firewall properties.

FirewallListener
If true, the component binds to a SOCKS firewall as a server (IPPort only)
This entry is for IPPort only and does not work for other components that descend from IPPort.If this entry is set, the bean acts as a server. RemoteHost and RemotePort are used to tell the SOCKS firewall in which address and port to listen to. The firewall rules may ignore RemoteHost , and it is recommended that RemoteHost be set to empty string in this case.

RemotePort is the port in which the firewall will listen to. If set to 0, the firewall will select a random port. The binding (address and port) is provided through the ConnectionStatus event.

The connection to the firewall is made by calling the Connect method.

FirewallPassword
Password to be used if authentication is to be used when connecting through the firewall
If FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the given firewall. If the authentication fails, the bean throws an exception.NOTE: This is the same as Password . This setting is provided for use by beans that do not directly expose Firewall properties.

FirewallPort
The TCP port for the FirewallHost;
Note that the FirewallPort is set automatically when FirewallType is set to a valid value.NOTE: This is the same as Port . This setting is provided for use by beans that do not directly expose Firewall properties.

FirewallType
Determines the type of firewall to connect through
The appropriate values are as follows:
0
No firewall (default setting).
1
Connect through a tunneling proxy. FirewallPort is set to 80.
2
Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
3
Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.
NOTE: This is the same as FirewallType . This setting is provided for use by beans that do not directly expose Firewall properties.

FirewallUser
A user name if authentication is to be used connecting through a firewall
If the FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the Firewall. If the authentication fails, the bean throws an exception.NOTE: This is the same as User . This setting is provided for use by beans that do not directly expose Firewall properties.

KeepAliveTime
The inactivity time in milliseconds before a TCP keep-alive packet is sent
When set, TCPKeepAlive will automatically be set to true. By default the operating system will determine the time a connection is idle before a TCP keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many cases a shorter interval is more useful. Set this value to the desired interval in milliseconds.Note: This value is not applicable in Java.

KeepAliveInterval
The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received
When set, TCPKeepAlive will automatically be set to true. A TCP keep-alive packet will be sent after a period of inactivity as defined by KeepAliveTime . If no acknowledgement is received from the remote host the keep-alive packet will be re-sent. This setting specifies the interval at which the successive keep-alive packets are sent in milliseconds. This system default if this value is not specified here is 1 second.Note: This value is not applicable in Java or MAC.

Linger
When set to True, connections are terminated gracefully
This property controls how a connection is closed. The default is True.In the case that Linger is True (default), there are two scenarios for determining how long the connection will linger. The first, if LingerTime is 0 (default), the system will attempt to send pending data for a connection until the default IP protocol timeout expires.

In the second scenario, LingerTime is a positive value, the system will attempt to send pending data until the specified LingerTime is reached. If this attempt fails, then the system will reset the connection.

The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the bean returns control immediately, the system could hold system resources until all pending data is sent (even after your application closes).

Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (by a client acknowledgment, for example), setting this property to False might be the appropriate course of action.

LingerTime
Time in seconds to have the connection linger
LingerTime is the time, in seconds, to leave the socket connection linger. This value is 0 by default, which means it will use the default IP protocol timeout.
LocalHost
The name of the local host through which connections are initiated or accepted
The LocalHost setting contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.In multi-homed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost setting shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multi-homed hosts (machines with more than one IP interface).

LocalPort
The TCP port in the local host where the bean binds
This must be set before a connection is attempted. It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be shown by LocalPort after the connection is established.

LocalPort cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.

This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.

MaxLineLength
The maximum amount of data to accumulate when no EOL is found
MaxLineLength is the size of an internal buffer, which holds received data while waiting for an EOL string.If an EOL string is found in the input stream before MaxLineLength bytes are received, the DataIn event is fired with the EOL parameter set to True, and the buffer is reset.

If no EOL is found, and MaxLineLength bytes are accumulated in the buffer, the DataIn event is fired with the EOL parameter set to False, and the buffer is reset.

The minimum value for MaxLineLength is 256 bytes. The default value is 2048 bytes. The maximum value is 65536 bytes.

MaxTransferRate
The transfer rate limit in bytes per second
This setting can be used to throttle outbound TCP traffic. Set this to the number of bytes to be sent per second. By default this is not set and there is no limit.
TCPKeepAlive
Determines whether or not the keep alive socket option is enabled
If set to true, the socket's keep-alive option is enabled and keep-alive packets will be sent periodically to maintain the connection. Set KeepAliveTime and KeepAliveInterval to configure the timing of the keep-alive packets.Note: This value is not applicable in Java.

UseIPv6
Whether or not to use IPv6
By default, the component expects an IPv4 address for local and remote host properties, and will create an IPv4 socket. To use IPv6 instead, set this to True.
CloseStreamAfterTransfer
If true, the component will close the upload or download stream after the transfer
This entry is for bean and all the components that descend from it.This property is true by default. Therefore, by default, all streams will be closed after a transfer is completed. In order to keep streams open after the transfer of data, you must set this config to false.

TcpNoDelay
Whether or not to delay when sending packets
When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.By default, this config is set to false.

Socket Configuration Settings

AbsoluteTimeout
Determines whether timeouts are inactivity timeouts or absolute timeouts
If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.
FirewallData
Used to send extra data to the firewall
When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g. headers for custom authentication schemes).
InBufferSize
The size in bytes of the incoming queue of the socket
This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. Increasing the value of the InBufferSize setting can provide significant improvements in performance in some cases.Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the bean is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

OutBufferSize
The size in bytes of the outgoing queue of the socket
This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. Increasing the value of the OutBufferSize setting can provide significant improvements in performance in some cases.Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the bean is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

Base Configuration Settings

GUIAvailable
Tells the bean whether or not a message loop is available for processing events
In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The bean will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GuiAvailable to false will ensure that the bean does not attempt to process external events.

Throws:
IPWorksException

connect

public void connect(java.lang.String userId,
                    java.lang.String password)
             throws IPWorksException
Will bind as a transceiver to the SMPP service.

This 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.

Throws:
IPWorksException

disconnect

public void disconnect()
                throws IPWorksException
Will disconnect from the SMPP service.

This method 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.

Throws:
IPWorksException

doEvents

public void doEvents()
              throws IPWorksException
Processes events from the internal message queue.

When this method is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Throws:
IPWorksException

interrupt

public void interrupt()
               throws IPWorksException
Interrupt the current method.

If there is no method in progress, Interrupt simply returns, doing nothing.

Throws:
IPWorksException

replaceMessage

public void replaceMessage(java.lang.String messageId,
                           java.lang.String newMessage)
                    throws IPWorksException
Replaces a previously sent message with a new one.

Assuming that there is a message on the SMPPServer stored under the value in MessageId , this method 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.

Throws:
IPWorksException

sendCommand

public byte[] sendCommand(int commandId,
                          byte[] payload)
                   throws IPWorksException
Will format and send a PDU using the specified command identifier and payload.

This method offers a way to do more with the bean than is directly supported. This method takes a command identifier 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.

Throws:
IPWorksException

sendData

public java.lang.String sendData(byte[] data)
                          throws IPWorksException
Sends raw data to Recipients .

This method sends raw data to Recipients . Up to 64KB of additional data can be supplied at a time for transmission to the SMPPServer . Unlike the SendMessage method, this method can only send to one destination at a time. The target is whatever value is in the Recipients collection .

Throws:
IPWorksException

sendMessage

public java.lang.String sendMessage(java.lang.String message)
                             throws IPWorksException
Sends a message to all recipients in the recipient list.

The methods sends a message to all recipients in the recipient list. The return value of this method is the server-assigned identifier of the message. The max size of the message sent is 256 bytes.

Throws:
IPWorksException

addSmppEventListener

public void addSmppEventListener(SmppEventListener l)
                          throws java.util.TooManyListenersException
Throws:
java.util.TooManyListenersException

removeSmppEventListener

public void removeSmppEventListener(SmppEventListener l)

IP*Works! V9

Copyright (c) 2013 /n software inc. - All rights reserved.