ipworks
Class Snpp

java.lang.Object
  |
  +--ipworks.Snpp

public class Snpp

extends java.lang.Object

The SNPP bean is used to send pages through the internet using the SNPP protocol.

It is a client implementation of Simple Network Paging Protocol Version 3 as specified in RFC 1861. Service extensions level 2 are supported intrinsically and the user can access all of level 3 extensions.

SNPP allows for immediate notification of message delivery, gives absolute flexibility over the content sent to the recipient, allows the specification of multiple choice responses, etc.

To send a message the ServerName , recipient's PagerId and Message properties should be filled out (at a minimum). The Send method is then used to deliver the message.

The server's response is given in the PITrail events and by the LastReply property. Customized commands may be sent using the Command property.

Optional properties include: CallerId , ServerPort and LocalHost

Field Summary

static int	fwNone
static int	fwSOCKS4
static int	fwSOCKS5
static int	fwTunnel

Constructor Summary

Snpp()

Method Summary

void	addSnppEventListener(SnppEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	connect() Connect to an SNPP server.
void	disconnect() Disconnect from an SNPP gateway.
void	doEvents() Processes events from the internal message queue.
java.lang.String	getCallerId() The id of the caller.
java.lang.String	getFirewallHost() Name or IP address of firewall (optional).
java.lang.String	getFirewallPassword() A password if authentication is to be used when connecting through the firewall.
int	getFirewallPort() Port of the firewall to connect to.
int	getFirewallType() Determines the type of firewall to connect through.
java.lang.String	getFirewallUser() A user name if authentication is to be used connecting through a firewall.
java.lang.String	getLastReply() The last reply from the server.
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	getMessage() The message being sent (alphanumeric).
java.lang.String	getPagerId() The id number of the pager to send a Message to.
java.lang.String	getServerName() The name or address of the SNPP server.
int	getServerPort() The server port for SNPP (default 444).
int	getTimeout() A timeout for the bean.
void	interrupt() Interrupt the current method.
boolean	isConnected() Shows whether the bean is connected.
boolean	isIdle() The current status of the component.
void	removeSnppEventListener(SnppEventListener l)
void	reset() Resets the server state created during the connection.
void	send() Send the current message.
void	setCallerId(java.lang.String callerId) The id of the caller.
void	setCommand(java.lang.String command) Can be used to send additional commands directly to the server.
void	setConnected(boolean connected) Shows whether the bean is connected.
void	setFirewallHost(java.lang.String firewallHost) Name or IP address of firewall (optional).
void	setFirewallPassword(java.lang.String firewallPassword) A password if authentication is to be used when connecting through the firewall.
void	setFirewallPort(int firewallPort) Port of the firewall to connect to.
void	setFirewallType(int firewallType) Determines the type of firewall to connect through.
void	setFirewallUser(java.lang.String firewallUser) A user name if authentication is to be used connecting through a firewall.
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	setMessage(java.lang.String message) The message being sent (alphanumeric).
void	setPagerId(java.lang.String pagerId) The id number of the pager to send a Message to.
void	setServerName(java.lang.String serverName) The name or address of the SNPP server.
void	setServerPort(int serverPort) The server port for SNPP (default 444).
void	setTimeout(int timeout) A timeout for the bean.

Methods inherited from class java.lang.Object

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

Field Detail

fwNone

public static final int fwNone

See Also:

Constant Field Values

fwTunnel

public static final int fwTunnel

See Also:

Constant Field Values

fwSOCKS4

public static final int fwSOCKS4

See Also:

Constant Field Values

fwSOCKS5

public static final int fwSOCKS5

See Also:

Constant Field Values

Constructor Detail

Snpp

public Snpp()

Method Detail

getCallerId

public java.lang.String getCallerId()

The id of the caller.

This may also provide authentication to the SNPP server and may include other authentication information as requested by the server you are connecting to.

setCallerId

public void setCallerId(java.lang.String callerId)
                 throws IPWorksException

The id of the caller.

This may also provide authentication to the SNPP server and may include other authentication information as requested by the server you are connecting to.

IPWorksException

setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException

Can be used to send additional commands directly to the server.

Check the LastReply property and/or trap the PITrail events coming from the server to get the response.

IPWorksException

isConnected

public boolean isConnected()

Shows whether the bean is connected.

Use this property to determine whether the bean is connected to the remote host or not.

setConnected

public void setConnected(boolean connected)
                  throws IPWorksException

Shows whether the bean is connected.

Use this property to determine whether the bean is connected to the remote host or not.

IPWorksException

getFirewallHost

public java.lang.String getFirewallHost()

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 property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.

setFirewallHost

public void setFirewallHost(java.lang.String firewallHost)
                     throws IPWorksException

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 property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost property is set to the corresponding address. If the search is not successful, an error is returned.

IPWorksException

getFirewallPassword

public java.lang.String getFirewallPassword()

A password if authentication is to be used when connecting through the firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

setFirewallPassword

public void setFirewallPassword(java.lang.String firewallPassword)
                         throws IPWorksException

A password if authentication is to be used when connecting through the firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

IPWorksException

getFirewallPort

public int getFirewallPort()

Port of the firewall to connect to.

The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

setFirewallPort

public void setFirewallPort(int firewallPort)
                     throws IPWorksException

Port of the firewall to connect to.

The TCP port for the FirewallHost . See the description of the FirewallHost property for details.

Note that the FirewallPort is set automatically when FirewallType is set to a valid value. See the description of the FirewallType property for details.

IPWorksException

getFirewallType

public int getFirewallType()

Determines the type of firewall to connect through.

The applicable values are the following:

fwNone (0)

No firewall (default setting).

fwTunnel (1)

Connect through a tunneling proxy. FirewallPort is set to 80.

fwSOCKS4 (2)

Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.

fwSOCKS5 (3)

Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

setFirewallType

public void setFirewallType(int firewallType)
                     throws IPWorksException

Determines the type of firewall to connect through.

The applicable values are the following:

fwNone (0)

No firewall (default setting).

fwTunnel (1)

Connect through a tunneling proxy. FirewallPort is set to 80.

fwSOCKS4 (2)

Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.

fwSOCKS5 (3)

Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.

IPWorksException

getFirewallUser

public java.lang.String getFirewallUser()

A user name if authentication is to be used connecting through a firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

setFirewallUser

public void setFirewallUser(java.lang.String firewallUser)
                     throws IPWorksException

A user name if authentication is to be used connecting through a firewall.

if FirewallHost is specified, the FirewallUser and FirewallPassword properties are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

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.

getLastReply

public java.lang.String getLastReply()

The last reply from the server.

This is the last reply received from the server. It can be used for information purposes. The same information and more can also be retrieved through the PITrail event.

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

IPWorksException

getMessage

public java.lang.String getMessage()

The message being sent (alphanumeric).

The message can be a single a line or split over multiple lines depending on what the restrictions of the receiving device and gateway. Normally messages are no longer than 100 bytes long.

setMessage

public void setMessage(java.lang.String message)
                throws IPWorksException

The message being sent (alphanumeric).

The message can be a single a line or split over multiple lines depending on what the restrictions of the receiving device and gateway. Normally messages are no longer than 100 bytes long.

IPWorksException

getPagerId

public java.lang.String getPagerId()

The id number of the pager to send a Message to.

Additional information such as a password or a PIN may be appended to the PagerId depending upon server requirements.

setPagerId

public void setPagerId(java.lang.String pagerId)
                throws IPWorksException

The id number of the pager to send a Message to.

Additional information such as a password or a PIN may be appended to the PagerId depending upon server requirements.

IPWorksException

getServerName

public java.lang.String getServerName()

The name or address of the SNPP server.

The ServerName property specifies the IP address (IP number in dotted internet format) or Domain Name of the SNPP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the ServerName property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the ServerName property is set to the corresponding address. If the search is not successful, an error is returned.

setServerName

public void setServerName(java.lang.String serverName)
                   throws IPWorksException

The name or address of the SNPP server.

The ServerName property specifies the IP address (IP number in dotted internet format) or Domain Name of the SNPP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the ServerName property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the ServerName property is set to the corresponding address. If the search is not successful, an error is returned.

IPWorksException

getServerPort

public int getServerPort()

The server port for SNPP (default 444).

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.

setServerPort

public void setServerPort(int serverPort)
                   throws IPWorksException

The server port for SNPP (default 444).

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.

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 IPWorksException raises an IPWorksException exception .

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

Optionally, the 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 theAbsoluteTimeoutconfiguration 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 IPWorksException raises an IPWorksException exception .

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

Optionally, the 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 theAbsoluteTimeoutconfiguration setting.

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

IPWorksException

config

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

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

connect

public void connect()
             throws IPWorksException

Connect to an SNPP server.

Connects to the SNPP server. Any number of messages can later be sent using the Send method.

Example (Send Page)

 SNPPControl.ServerName = "MyServer"
 SNPPControl.CallerId = "SenderPagerNumber"
 SNPPControl.PagerId = "RecipientPagerNumber"
 SNPPControl.Message = "Hello, this is my message!"
 SNPPControl.Connect()
 SNPPControl.Send()
 SNPPControl.Disconnect() 

IPWorksException

disconnect

public void disconnect()
                throws IPWorksException

Disconnect from an SNPP gateway.

Disconnects from the SNPP gateway.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

Processes events from the internal message queue.

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

IPWorksException

interrupt

public void interrupt()
               throws IPWorksException

Interrupt the current method.

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

IPWorksException

reset

public void reset()
           throws IPWorksException

Resets the server state created during the connection.

Resets the server state created during the connection, so that a new message may be sent to the gateway using the already established connection.

IPWorksException

send

public void send()
          throws IPWorksException

Send the current message.

If the bean is not already connected to the SNPP server then a connection is created. Then the bean attempts to deliver the current message.

Example (Send Page)

 SNPPControl.ServerName = "MyServer"
 SNPPControl.CallerId = "SenderPagerNumber"
 SNPPControl.PagerId = "RecipientPagerNumber"
 SNPPControl.Message = "Hello, this is my message!"
 SNPPControl.Send() 

IPWorksException

addSnppEventListener

public void addSnppEventListener(SnppEventListener l)
                          throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeSnppEventListener

public void removeSnppEventListener(SnppEventListener l)