ipworksssl
Class Smpps

java.lang.Object
  ipworksssl.Smpps

public class Smpps
extends java.lang.Object

The SmppS 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
static int	sslAutomatic
static int	sslExplicit
static int	sslImplicit
static int	sslNone

Constructor Summary

Smpps()
Creates an instance of Smpps Bean.

Smpps(java.lang.String runtimeLicense)
Creates an instance of Smpps 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	addSmppsEventListener(SmppsEventListener 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 {@link ipworksssl.Smpps#config 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() This property contains the server port for secure SMPP (default 3551).
java.lang.String	getSMPPServer() The SMPP entity to which the component will connect.
int	getSMPPVersion() The SMPP version to be used throughout the connection.
Certificate	getSSLAcceptServerCert() Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.
Certificate	getSSLCert() The certificate to be used during SSL negotiation.
Certificate	getSSLServerCert() The server certificate for the last established connection.
int	getSSLStartMode() Determines how the bean starts the SSL negotiation.
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	removeSmppsEventListener(SmppsEventListener 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) This property contains the server port for secure SMPP (default 3551).
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	setSSLAcceptServerCert(Certificate SSLAcceptServerCert) Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.
void	setSSLCert(Certificate SSLCert) The certificate to be used during SSL negotiation.
void	setSSLStartMode(int SSLStartMode) Determines how the bean starts the SSL negotiation.
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

sslAutomatic

public static final int sslAutomatic

See Also:

Constant Field Values

sslImplicit

public static final int sslImplicit

See Also:

Constant Field Values

sslExplicit

public static final int sslExplicit

See Also:

Constant Field Values

sslNone

public static final int sslNone

See Also:

Constant Field Values

Constructor Detail

Smpps

public Smpps()

Creates an instance of Smpps Bean.

Smpps

public Smpps(java.lang.String runtimeLicense)

Creates an instance of Smpps 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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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)

CIMD2 for Nokia Short Message Service Center servers

setProtocol

public void setProtocol(int protocol)
                 throws IPWorksSSLException

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)

CIMD2 for Nokia Short Message Service Center servers

Throws:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

getSMPPPort

public int getSMPPPort()

This property contains the server port for secure SMPP (default 3551).

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 IPWorksSSLException

This property contains the server port for secure SMPP (default 3551).

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

getSSLAcceptServerCert

public Certificate getSSLAcceptServerCert()

Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.

If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert . If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

setSSLAcceptServerCert

public void setSSLAcceptServerCert(Certificate SSLAcceptServerCert)
                            throws IPWorksSSLException

Instructs the bean to unconditionally accept the server certificate that matches the supplied certificate.

If it finds any issues with the certificate presented by the server, the bean will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert . If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

Throws:

IPWorksSSLException

getSSLCert

public Certificate getSSLCert()

The certificate to be used during SSL negotiation.

The digital certificate that the bean will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

setSSLCert

public void setSSLCert(Certificate SSLCert)
                throws IPWorksSSLException

The certificate to be used during SSL negotiation.

The digital certificate that the bean will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

Throws:

IPWorksSSLException

getSSLServerCert

public Certificate getSSLServerCert()

The server certificate for the last established connection.

SSLServerCert contains the server certificate for the last established connection.

SSLServerCert is reset every time a new connection is attempted.

getSSLStartMode

public int getSSLStartMode()

Determines how the bean starts the SSL negotiation.

The SSLStartMode property may have one of the following values:

0 (sslAutomatic - default)

If the remote port is set to the standard plaintext port of the protocol (where applicable), the bean will behave the same as if SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit ( sslImplicit ).

1 (sslImplicit)

The SSL negotiation will start immediately after the connection is established.

2 (sslExplicit)

The bean will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.

3 (sslNone)

No SSL negotiation, no SSL security. All communication will be in plaintext mode.

setSSLStartMode

public void setSSLStartMode(int SSLStartMode)
                     throws IPWorksSSLException

Determines how the bean starts the SSL negotiation.

The SSLStartMode property may have one of the following values:

0 (sslAutomatic - default)

If the remote port is set to the standard plaintext port of the protocol (where applicable), the bean will behave the same as if SSLStartMode is set to sslExplicit . In all other cases, SSL negotiation will be implicit ( sslImplicit ).

1 (sslImplicit)

The SSL negotiation will start immediately after the connection is established.

2 (sslExplicit)

The bean will first connect in plaintext, and then explicitly start SSL negotiation through a protocol command such as STARTTLS.

3 (sslNone)

No SSL negotiation, no SSL security. All communication will be in plaintext mode.

Throws:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

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 ipworksssl.Smpps#config configuration setting.

The default value for the {@link ipworksssl.Smpps#getTimeout Timeout} property is 60 (seconds).

setTimeout

public void setTimeout(int timeout)
                throws IPWorksSSLException

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 ipworksssl.Smpps#config configuration setting.

The default value for the {@link ipworksssl.Smpps#getTimeout Timeout} property is 60 (seconds).

Throws:

IPWorksSSLException

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 IPWorksSSLException

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:

IPWorksSSLException

addRecipient

public void addRecipient(int recipientType,
                         java.lang.String recipientAddress)
                  throws IPWorksSSLException

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:

IPWorksSSLException

cancelMessage

public void cancelMessage(java.lang.String messageId)
                   throws IPWorksSSLException

Will cancel the specified message.

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

Throws:

IPWorksSSLException

checkLink

public void checkLink()
               throws IPWorksSSLException

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:

IPWorksSSLException

checkMessageStatus

public void checkMessageStatus(java.lang.String messageId)
                        throws IPWorksSSLException

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:

IPWorksSSLException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksSSLException

Sets or retrieves a ipworksssl.Smpps#config configuration setting.

{@link ipworksssl.Smpps#config Config} is a generic method available in every bean. It is used to set and retrieve {@link ipworksssl.Smpps#config configuration settingsfor the bean.

These 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 {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config .

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 {@link ipworksssl.Smpps#config .

HexString

A hex-encoded binary string to be sent to the current recipient

Setting this config property will cause the component to internally call {@link ipworksssl.Smpps#sendMessage 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.

MaxCIMDSMSLength

Indicates the maximum SMS message length for the CIMD protocol

This setting is only applicable when {@link ipworksssl.Smpps#config is true and {@link ipworksssl.Smpps#getProtocol Protocol} is set to CIMD2. The setting controls the maximum size of SMS messages before they are split and has a default value of 160.

MaxSMSLength

Indicates the maximum SMS message length

This setting is only applicable when {@link ipworksssl.Smpps#config is true. The setting controls the maximum size of SMS messages before they are split and has a default value of 140.

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 {@link ipworksssl.SmppsMessageInEvent 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 {@link ipworksssl.SmppsMessageInEvent 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 {@link ipworksssl.SmppsMessageInEvent 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 {@link ipworksssl.Smpps#config (or {@link ipworksssl.Smpps#config ) the message will automatically be split into parts when {@link ipworksssl.Smpps#sendMessage SendMessage} is called. Note that this is only valid for GSM networks.When receiving a message that has been split, the {@link ipworksssl.SmppsMessageInEvent 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 SendCommand behaves synchronously or asynchronously

The default value is true which means {@link ipworksssl.Smpps#sendCommand 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 SendMessage behaves synchronously or asynchronously

The default value is true which means {@link ipworksssl.Smpps#sendMessage 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 {@link ipworksssl.SmppsPITrailEvent 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 {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#sendMessage SendMessage} or {@link ipworksssl.Smpps#sendData 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 {@link ipworksssl.Smpps#getProtocol Protocol} is set to smppCIMD2 .

StatusReportRequest

Defines in what cases a status report is created by the server

This is only applicable when {@link ipworksssl.Smpps#getProtocol 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 {@link ipworksssl.Smpps#getProtocol 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

ConnectionTimeout

Sets a separate timeout value for establishing a connection

When set, this configuration setting allows you to specify a different timeout value for establishing a connection. Otherwise, the bean will use {@link ipworksssl.Smpps#getTimeout Timeout} for establishing a connection and transmitting/receiving data.

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 {@link ipworksssl.Smpps#config is given, requested connections will be authenticated through the specified firewall when connecting.If the {@link ipworksssl.Smpps#config setting is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the {@link ipworksssl.Smpps#config 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. {@link ipworksssl.Smpps#getRemoteHost RemoteHost} and {@link ipworksssl.Smpps#getRemotePort RemotePort} are used to tell the SOCKS firewall in which address and port to listen to. The firewall rules may ignore {@link ipworksssl.Smpps#getRemoteHost RemoteHost} , and it is recommended that {@link ipworksssl.Smpps#getRemoteHost RemoteHost} be set to empty string in this case.

{@link ipworksssl.Smpps#getRemotePort 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 {@link ipworksssl.SmppsConnectionStatusEvent ConnectionStatus} event.

The connection to the firewall is made by calling the {@link ipworksssl.Smpps#connect Connect} method.

FirewallPassword

Password to be used if authentication is to be used when connecting through the firewall

If {@link ipworksssl.Smpps#config is specified, the {@link ipworksssl.Smpps#config and {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config is set automatically when {@link ipworksssl.Smpps#config 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. {@link ipworksssl.Smpps#config is set to 80.

2

Connect through a SOCKS4 Proxy. {@link ipworksssl.Smpps#config is set to 1080.

3

Connect through a SOCKS5 Proxy. {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config is specified, the {@link ipworksssl.Smpps#config and {@link ipworksssl.Smpps#config 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, {@link ipworksssl.Smpps#config 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, {@link ipworksssl.Smpps#config will automatically be set to true. A TCP keep-alive packet will be sent after a period of inactivity as defined by {@link ipworksssl.Smpps#config . 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 {@link ipworksssl.Smpps#config 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, {@link ipworksssl.Smpps#config is a positive value, the system will attempt to send pending data until the specified {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#getLocalHost 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 {@link ipworksssl.Smpps#getLocalHost 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 {@link ipworksssl.Smpps#getLocalPort LocalPort} after the connection is established.

{@link ipworksssl.Smpps#getLocalPort 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

{@link ipworksssl.Smpps#config is the size of an internal buffer, which holds received data while waiting for an {@link ipworksssl.Smpps#getEOL EOL} string.If an {@link ipworksssl.Smpps#getEOL EOL} string is found in the input stream before {@link ipworksssl.Smpps#config bytes are received, the {@link ipworksssl.SmppsDataInEvent DataIn} event is fired with the EOL parameter set to True, and the buffer is reset.

If no {@link ipworksssl.Smpps#getEOL EOL} is found, and {@link ipworksssl.Smpps#config bytes are accumulated in the buffer, the {@link ipworksssl.SmppsDataInEvent DataIn} event is fired with the EOL parameter set to False, and the buffer is reset.

The minimum value for {@link ipworksssl.Smpps#config 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 {@link ipworksssl.Smpps#config and {@link ipworksssl.Smpps#config 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 setting determines whether the input or output stream is closed after the transfer completes. When set to True (default), all streams will be closed after a transfer is completed. In order to keep streams open after the transfer of data, set this to False. the default value is True.

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.

SSL Configuration Settings

ReuseSSLSession

Determines if the SSL session is reused

If set to true, the component will reuse the context if and only if the following criteria are met:

• The target host name is the same.
• The system cache entry has not expired (default timeout is 10 hours).
• The application process that calls the function is the same.
• The logon session is the same.
• The instance of the component is the same.

SSLCipherStrength

The minimum cipher strength used for bulk encryption

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.Please note that this setting contains the minimum cipher strength requested from the security library. The actual cipher strength used for the connection is shown by the {@link ipworksssl.SmppsSSLStatusEvent SSLStatus} event.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the {@link ipworksssl.Smpps#config config setting.

SSLEnabledProtocols

Used to enable/disable the supported security protocols

Used to enable/disable the supported security protocols.Not all supported protocols are enabled by default (the value of this setting is 192). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

TLS1.2

3072 (Hex C00)

TLS1.1

768 (Hex 300)

TLS1

192 (Hex C0) (Default)

SSL3

48 (Hex 30)

SSL2

12 (Hex 0C)

Please note that although a number of sites still support SSL2, it is usually a good idea to disable it because of potential security vulnerabilities.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the {@link ipworksssl.Smpps#config config setting.

TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

SSLProvider

The name of the security provider to use

Change this setting to use security providers other than the system default.Use this setting with caution. Disabling SSL security or pointing to the wrong provider could potentially cause serious security vulnerabilities in your application.

The special value "*" (default) picks the default SSL provider defined in the system.

Note: On Windows systems, the default SSL Provider is "Microsoft Unified Security Protocol Provider" and cannot be changed.

SSLSecurityFlags

Flags that control certificate verification

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

0x00000001

Ignore time validity status of certificate.

0x00000002

Ignore time validity status of CTL.

0x00000004

Ignore non-nested certificate times.

0x00000010

Allow unknown Certificate Authority.

0x00000020

Ignore wrong certificate usage.

0x00000100

Ignore unknown certificate revocation status.

0x00000200

Ignore unknown CTL signer revocation status.

0x00000400

Ignore unknown Certificate Authority revocation status.

0x00000800

Ignore unknown Root revocation status.

0x00008000

Allow test Root certificate.

0x00004000

Trust test Root certificate.

0x80000000

Ignore non-matching CN (certificate CN not-matching server name).

This functionality is currently not available in Java or when the provider is OpenSSL.

SSLContextProtocol

The protocol used when getting an SSLContext instance

Possible values are SSL, SSLv2, SSLv3, TLS and TLSv1. Use it only in case your security provider does not support TLS. This is the parameter "protocol" inside the SSLContext.getInstance(protocol) call.

SSLTrustManagerFactoryAlgorithm

The algorithm to be used to create a TrustManager through TrustManagerFactory

Possible values include SunX509. This is the parameter "algorithm" inside the TrustManagerFactory.getInstance(algorithm) call.

SSLEnabledCipherSuites

The cipher suite to be used in an SSL negotiation

The enabled cipher suites to be used in SSL negotiation.By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the component will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values:

 obj.config("SSLEnabledCipherSuites=*");
 obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA");
 obj.config("SSLEnabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA; SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA"); 

Possible values include:

• SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
• SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
• SSL_RSA_WITH_RC4_128_SHA
• SSL_RSA_WITH_DES_CBC_SHA
• SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
• SSL_DH_anon_WITH_DES_CBC_SHA
• SSL_RSA_EXPORT_WITH_RC4_40_MD5
• SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
• SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
• SSL_DHE_DSS_WITH_DES_CBC_SHA
• SSL_RSA_WITH_NULL_MD5
• SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
• SSL_DHE_RSA_WITH_DES_CBC_SHA
• SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
• SSL_RSA_WITH_NULL_SHA
• SSL_DH_anon_WITH_RC4_128_MD5
• SSL_RSA_WITH_RC4_128_MD5
• SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
• SSL_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_ECDH_ECDSA_WITH_NULL_SHA
• TLS_DH_anon_WITH_AES_128_CBC_SHA256
• TLS_ECDH_anon_WITH_RC4_128_SHA
• TLS_DH_anon_WITH_AES_128_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA
• TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
• TLS_KRB5_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
• TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_KRB5_EXPORT_WITH_RC4_40_SHA
• TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_RC4_128_SHA
• TLS_ECDH_ECDSA_WITH_RC4_128_SHA
• TLS_ECDH_anon_WITH_NULL_SHA
• TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
• TLS_RSA_WITH_NULL_SHA256
• TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA
• TLS_KRB5_WITH_RC4_128_MD5
• TLS_ECDHE_ECDSA_WITH_NULL_SHA
• TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
• TLS_ECDH_RSA_WITH_RC4_128_SHA
• TLS_EMPTY_RENEGOTIATION_INFO_SCSV
• TLS_KRB5_WITH_3DES_EDE_CBC_MD5
• TLS_KRB5_WITH_RC4_128_SHA
• TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_ECDH_RSA_WITH_NULL_SHA
• TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
• TLS_KRB5_WITH_DES_CBC_MD5
• TLS_KRB5_EXPORT_WITH_RC4_40_MD5
• TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
• TLS_ECDH_anon_WITH_AES_128_CBC_SHA
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_KRB5_WITH_DES_CBC_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA
• TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
• TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_NULL_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA

SSLEnabledCipherSuites is used together with SSLCipherStrength .

Note: This configuration setting is available only in .NET and Java.

SSLAlgorithmList

A string that controls the cipher algorithms to be used by SSL

This configuration option takes a semicolon (;) delimited list of cipher algorithms to specify what algorithms may be used by SSL. This option can be used in conjunction with SSLEnabledProtocols to control which ciphers are used.For example:

 obj.Config("SSLEnabledProtocols=3072"); // TLS1.2  (supports SHA_256)
   obj.Config("SSLAlgorithmList=CALG_SHA_256;CALG_MD5"); 

Possible values include:

• CALG_3DES
• CALG_3DES_112
• CALG_AES
• CALG_AES_128
• CALG_AES_192
• CALG_AES_256
• CALG_AGREEDKEY_ANY
• CALG_CYLINK_MEK
• CALG_DES
• CALG_DESX
• CALG_DH_EPHEM
• CALG_DH_SF
• CALG_DSS_SIGN
• CALG_ECDH
• CALG_ECDSA
• CALG_ECMQV
• CALG_HASH_REPLACE_OWF
• CALG_HUGHES_MD5
• CALG_HMAC
• CALG_KEA_KEYX
• CALG_MAC
• CALG_MD2
• CALG_MD4
• CALG_MD5
• CALG_NO_SIGN
• CALG_OID_INFO_CNG_ONLY
• CALG_OID_INFO_PARAMETERS
• CALG_PCT1_MASTER
• CALG_RC2
• CALG_RC4
• CALG_RC5
• CALG_RSA_KEYX
• CALG_RSA_SIGN
• CALG_SCHANNEL_ENC_KEY
• CALG_SCHANNEL_MAC_KEY
• CALG_SCHANNEL_MASTER_HASH
• CALG_SEAL
• CALG_SHA
• CALG_SHA1
• CALG_SHA_256
• CALG_SHA_384
• CALG_SHA_512
• CALG_SKIPJACK
• CALG_SSL2_MASTER
• CALG_SSL3_MASTER
• CALG_SSL3_SHAMD5
• CALG_TEK
• CALG_TLS1_MASTER
• CALG_TLS1PRF

This option is only valid in Windows.

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.Note: This option is not valid for UDP ports.

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.

UseDaemonThreads

Whether threads created by the bean are daemon threads

If set to True, when the bean creates a thread the thread's Daemon property will be explicitly set to True. By default this setting is False and the bean will not set the Daemon property on the created thread.

Throws:

IPWorksSSLException

connect

public void connect(java.lang.String userId,
                    java.lang.String password)
             throws IPWorksSSLException

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:

IPWorksSSLException

disconnect

public void disconnect()
                throws IPWorksSSLException

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:

IPWorksSSLException

doEvents

public void doEvents()
              throws IPWorksSSLException

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:

IPWorksSSLException

interrupt

public void interrupt()
               throws IPWorksSSLException

Interrupt the current method.

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

Throws:

IPWorksSSLException

replaceMessage

public void replaceMessage(java.lang.String messageId,
                           java.lang.String newMessage)
                    throws IPWorksSSLException

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:

IPWorksSSLException

sendCommand

public byte[] sendCommand(int commandId,
                          byte[] payload)
                   throws IPWorksSSLException

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:

IPWorksSSLException

sendData

public java.lang.String sendData(byte[] data)
                          throws IPWorksSSLException

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:

IPWorksSSLException

sendMessage

public java.lang.String sendMessage(java.lang.String message)
                             throws IPWorksSSLException

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:

IPWorksSSLException

addSmppsEventListener

public void addSmppsEventListener(SmppsEventListener l)
                           throws java.util.TooManyListenersException

Throws:

java.util.TooManyListenersException

removeSmppsEventListener

public void removeSmppsEventListener(SmppsEventListener l)