|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--ipworks.Ipport
The IPPort control facilitates TCP/IP communications by providing an easy interface to Winsock functions. It allows a client application to communicate with a server using stream sockets.
Our main goal in designing IPPort was ease of use.
The control has a minimum of properties and five events: Connected
, DataIn
, Disconnected
, ReadyToSend
, and Error
.
The events are relatively self-explanatory.
The connection is attempted by calling the Connect
method or setting the Connected
property to True, and then waiting for the Connected
event.The destination is defined by setting RemoteHost
and RemotePort
. Data is sent by calling the Send
method
with Text as a parameter, or by assigning the data string to the DataToSend
property.
To disconnect, you just call the Disconnect
method or set the Connected
property to False. The Linger
property controls how the connection is
terminated.
The operation of the control is almost completely asynchronous. All the calls except the ones that deal with domain name resolution, operate through Windows messages (no blocking calls). The gain in performance is considerable when compared to using blocking calls.
Field Summary | |
static int |
fwNone
|
static int |
fwSOCKS4
|
static int |
fwSOCKS5
|
static int |
fwTunnel
|
Constructor Summary | |
Ipport()
|
Method Summary | |
void |
addIpportEventListener(IpportEventListener l)
|
void |
connect(java.lang.String host,
int port)
Connect to a remote host. |
void |
disconnect()
Disconnect from the remote host. |
void |
fireConnected(int statusCode,
java.lang.String description)
Fired immediately after a connection completes (or fails). |
void |
fireDataIn(byte[] text,
boolean EOL)
Fired when data (complete lines) comes in. |
void |
fireDisconnected(int statusCode,
java.lang.String description)
Fired when a connection is closed. |
void |
fireError(int errorCode,
java.lang.String description)
Information about errors during data delivery. |
void |
fireReadyToSend()
Fired when IPPort is ready to send data. |
int |
getBytesSent()
The number of bytes actually sent after an assignment to DataToSend . |
byte[] |
getEOL()
Used to break the incoming data stream into chunks separated by EOL. |
byte[] |
getFirewallData()
Used to send other data to firewall. |
java.lang.String |
getFirewallHost()
Name or IP address of firewall (optional). |
java.lang.String |
getFirewallPassword()
A password if authentication is to be used 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. |
int |
getInBufferSize()
The size in bytes of the incoming queue of the socket. |
java.lang.String |
getLocalHost()
The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
int |
getLocalPort()
The TCP port in the local host where IPPort binds. |
int |
getMaxLineLength()
The maximum amount of data to accumulate when no EOL is found. |
int |
getOutBufferSize()
The size in bytes of the outgoing queue of the socket. |
java.lang.String |
getRemoteHost()
The address of the remote host. |
int |
getRemotePort()
The TCP port in the remote host. |
int |
getTimeout()
A timeout for the component. |
boolean |
isAcceptData()
Enables or disables data reception (the DataIn event). |
boolean |
isConnected()
Triggers a connection or disconnection. |
boolean |
isKeepAlive()
When True, KEEPALIVE packets are enabled (for long connections). |
boolean |
isLinger()
When set to True, connections are terminated gracefully. |
void |
removeIpportEventListener(IpportEventListener l)
|
void |
send(byte[] text)
Send data to the remote host. |
void |
setAcceptData(boolean acceptData)
Enables or disables data reception (the DataIn event). |
void |
setConnected(boolean connected)
Triggers a connection or disconnection. |
void |
setDataToSend(byte[] dataToSend)
A string of data to be sent to the remote host. |
void |
setEOL(byte[] EOL)
Used to break the incoming data stream into chunks separated by EOL. |
void |
setFirewallData(byte[] firewallData)
Used to send other data to firewall. |
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 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 |
setInBufferSize(int inBufferSize)
The size in bytes of the incoming queue of the socket. |
void |
setKeepAlive(boolean keepAlive)
When True, KEEPALIVE packets are enabled (for long connections). |
void |
setLinger(boolean linger)
When set to True, connections are terminated gracefully. |
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 |
setLocalPort(int localPort)
The TCP port in the local host where IPPort binds. |
void |
setMaxLineLength(int maxLineLength)
The maximum amount of data to accumulate when no EOL is found. |
void |
setOutBufferSize(int outBufferSize)
The size in bytes of the outgoing queue of the socket. |
void |
setRemoteHost(java.lang.String remoteHost)
The address of the remote host. |
void |
setRemotePort(int remotePort)
The TCP port in the remote host. |
void |
setTimeout(int timeout)
A timeout for the component. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int fwNone
public static final int fwTunnel
public static final int fwSOCKS4
public static final int fwSOCKS5
Constructor Detail |
public Ipport()
Method Detail |
public boolean isAcceptData()
DataIn
event). Setting the property to True, reenables
data reception.
public void setAcceptData(boolean acceptData) throws IPWorksException
DataIn
event). Setting the property to True, reenables
data reception.
public int getBytesSent()
BytesSent
property shows how many bytes were sent after the last
assignment to DataToSend
. Please check the DataToSend
property for more
information.
public boolean isConnected()
Connected
property to True makes the control attempt
to connect to the host identified by the RemoteHost
property.
If successful, after the connection is achieved the value of the
property changes to True and the Connected
event is fired.
Setting Connected
to False closes the connection. How and when the
connection is closed is controlled by the Linger
property.
public void setConnected(boolean connected) throws IPWorksException
Connected
property to True makes the control attempt
to connect to the host identified by the RemoteHost
property.
If successful, after the connection is achieved the value of the
property changes to True and the Connected
event is fired.
Setting Connected
to False closes the connection. How and when the
connection is closed is controlled by the Linger
property.
public void setDataToSend(byte[] dataToSend) throws IPWorksException
DataToSend
property is an action property. Assigning
a string to this property makes the control send
the string to the remote host
.
If you are sending data to the remote host faster than it can
process it, or faster than the network's bandwidth allows, the outgoing
queue might fill up. When this happens, DataToSend
The BytesSent
property shows how many bytes were sent
(if any). If 0 bytes were sent, then you
can wait for the ReadyToSend
event before attempting to send data
again. (However, please note that ReadyToSend
is not fired when part
of the data is successfully sent).
public byte[] getEOL()
EOL
property is used to define boundaries in the input
stream using the value of the property.
The EOL
property is especially useful with ASCII files. Setting it to
"\\n"
(newline) enables splitting of the incoming ASCII text
stream into lines. In this case, one event is fired for each line
received (as well as in packet boundaries).
The
"\\n"
characters are discarded.
The EOL
property is a byte array string.
In particular, this means that it can be more than one character long,
and it can contain NULL ('\\0')
characters as well.
public void setEOL(byte[] EOL) throws IPWorksException
EOL
property is used to define boundaries in the input
stream using the value of the property.
The EOL
property is especially useful with ASCII files. Setting it to
"\\n"
(newline) enables splitting of the incoming ASCII text
stream into lines. In this case, one event is fired for each line
received (as well as in packet boundaries).
The
"\\n"
characters are discarded.
The EOL
property is a byte array string.
In particular, this means that it can be more than one character long,
and it can contain NULL ('\\0')
characters as well.
public byte[] getFirewallData()
public void setFirewallData(byte[] firewallData) throws IPWorksException
public java.lang.String getFirewallHost()
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 and 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.
public void setFirewallHost(java.lang.String firewallHost) throws IPWorksException
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 and 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.
public java.lang.String getFirewallPassword()
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.
public void setFirewallPassword(java.lang.String firewallPassword) throws IPWorksException
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.
public int getFirewallPort()
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.
public void setFirewallPort(int firewallPort) throws IPWorksException
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.
public int getFirewallType()
FirewallPort
is set to 80.
FirewallPort
is set to 1080.
FirewallPort
is set to 1080.
public void setFirewallType(int firewallType) throws IPWorksException
FirewallPort
is set to 80.
FirewallPort
is set to 1080.
FirewallPort
is set to 1080.
public java.lang.String getFirewallUser()
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.
public void setFirewallUser(java.lang.String firewallUser) throws IPWorksException
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.
public int getInBufferSize()
InBufferSize
property 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 a new connection is attempted
the InBufferSize
property reverts to its defined size.
The same happens if you attempt to make it too large or too small.
public void setInBufferSize(int inBufferSize) throws IPWorksException
InBufferSize
property 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 a new connection is attempted
the InBufferSize
property reverts to its defined size.
The same happens if you attempt to make it too large or too small.
public boolean isKeepAlive()
KeepAlive
enables the SO_KEEPALIVE option on the socket.
This option prevents long connections from timing out in case
of inactivity.
Please note that Winsock implementations are not required to support SO_KEEPALIVE.
public void setKeepAlive(boolean keepAlive) throws IPWorksException
KeepAlive
enables the SO_KEEPALIVE option on the socket.
This option prevents long connections from timing out in case
of inactivity.
Please note that Winsock implementations are not required to support SO_KEEPALIVE.
public boolean isLinger()
Linger
property controls how a connection is closed. The default is True.
In this case the connection is closed only after all the data is sent.
Setting it to False forces an abrupt (hard) disconnection. Any
data that were in the sending queue may be lost.
The default behavior (which is also the default mode for Winsock stream sockets) might result in an indefinite delay in closing the connection. Although the control returns control immediately, Winsock might indefinitely hold system resources until all pending data are sent (even after your application closes). This means that valuable system resources might be wasted.
Setting Linger
to False forces an immediate disconnection. If you
know that the other side has received all the data you had sent (by
a client acknowledgment, for example), setting Linger
to False might
be the appropriate course of action.
public void setLinger(boolean linger) throws IPWorksException
Linger
property controls how a connection is closed. The default is True.
In this case the connection is closed only after all the data is sent.
Setting it to False forces an abrupt (hard) disconnection. Any
data that were in the sending queue may be lost.
The default behavior (which is also the default mode for Winsock stream sockets) might result in an indefinite delay in closing the connection. Although the control returns control immediately, Winsock might indefinitely hold system resources until all pending data are sent (even after your application closes). This means that valuable system resources might be wasted.
Setting Linger
to False forces an immediate disconnection. If you
know that the other side has received all the data you had sent (by
a client acknowledgment, for example), setting Linger
to False might
be the appropriate course of action.
public java.lang.String getLocalHost()
LocalHost
property contains the name of the local host
as obtained by the gethostname() Winsock 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 control initiate connections (or accept in the case of server controls) only through that interface.
If the control 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.
public void setLocalHost(java.lang.String localHost) throws IPWorksException
LocalHost
property contains the name of the local host
as obtained by the gethostname() Winsock 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 control initiate connections (or accept in the case of server controls) only through that interface.
If the control 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.
public int getLocalPort()
LocalPort
property must be set before a connection is
attempted. It instructs the control to bind to a specific
port (or communication endpoint) in the local machine.
Setting it to 0 (default) enables Winsock to choose a port
at random. The chosen port will be shown by the LocalPort
property after the connection is established.
LocalPort
cannot be changed once a connection is made.
Any attempt to set the LocalPort
property when a connection
is active will generate an error.
The LocalPort
property 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.
public void setLocalPort(int localPort) throws IPWorksException
LocalPort
property must be set before a connection is
attempted. It instructs the control to bind to a specific
port (or communication endpoint) in the local machine.
Setting it to 0 (default) enables Winsock to choose a port
at random. The chosen port will be shown by the LocalPort
property after the connection is established.
LocalPort
cannot be changed once a connection is made.
Any attempt to set the LocalPort
property when a connection
is active will generate an error.
The LocalPort
property 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.
public int getMaxLineLength()
MaxLineLength
is the size of an internal buffer, which holds
received data while waiting for an EOL
string.
If an EOL
string is found in the input stream before MaxLineLength
characters are received, the DataIn
event is
fired with the EOL parameter set to True, and the buffer is reset.
If no EOL
is found, and MaxLineLength
characters are accumulated
in the buffer, the DataIn
event is fired with the EOL parameter
set to False, and the buffer is reset.
The minimum value for MaxLineLength
is 256.
public void setMaxLineLength(int maxLineLength) throws IPWorksException
MaxLineLength
is the size of an internal buffer, which holds
received data while waiting for an EOL
string.
If an EOL
string is found in the input stream before MaxLineLength
characters are received, the DataIn
event is
fired with the EOL parameter set to True, and the buffer is reset.
If no EOL
is found, and MaxLineLength
characters are accumulated
in the buffer, the DataIn
event is fired with the EOL parameter
set to False, and the buffer is reset.
The minimum value for MaxLineLength
is 256.
public int getOutBufferSize()
OutBufferSize
property 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 a new connection is attempted
the OutBufferSize
property reverts to its defined size.
The same happens if you attempt to make it too large or too small.
public void setOutBufferSize(int outBufferSize) throws IPWorksException
OutBufferSize
property 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 a new connection is attempted
the OutBufferSize
property reverts to its defined size.
The same happens if you attempt to make it too large or too small.
public java.lang.String getRemoteHost()
RemoteHost
property specifies the IP address (IP number in
dotted internet format) or Domain Name of the remote host.
It is set before a connection is attempted and cannot be changed
once a connection is established.
If the RemoteHost
property is set to a Domain Name, a DNS request
is initiated, and upon successful termination of the request, the RemoteHost
property is set to the corresponding address. If the
search is not successful, an error is returned.
public void setRemoteHost(java.lang.String remoteHost) throws IPWorksException
RemoteHost
property specifies the IP address (IP number in
dotted internet format) or Domain Name of the remote host.
It is set before a connection is attempted and cannot be changed
once a connection is established.
If the RemoteHost
property is set to a Domain Name, a DNS request
is initiated, and upon successful termination of the request, the RemoteHost
property is set to the corresponding address. If the
search is not successful, an error is returned.
public int getRemotePort()
RemotePort
property specifies a service port on the
remote host to connect to.
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 the RemotePort
while
connected will fail with an error.
public void setRemotePort(int remotePort) throws IPWorksException
RemotePort
property specifies a service port on the
remote host to connect to.
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 the RemotePort
while
connected will fail with an error.
public int getTimeout()
Timeout
property is set to 0 (default value), all
operations return immediately, potentially failing with an 'WOULDBLOCK' error if they can't be completed..
If Timeout
is set to a positive value, the control will
automatically retry each operation that would otherwise result in a 'WOULDBLOCK' error for a maximum of Timeout
seconds.
The control 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 the Timeout
expires, and the operation is not yet complete, a Timeout
error is fired.
public void setTimeout(int timeout) throws IPWorksException
Timeout
property is set to 0 (default value), all
operations return immediately, potentially failing with an 'WOULDBLOCK' error if they can't be completed..
If Timeout
is set to a positive value, the control will
automatically retry each operation that would otherwise result in a 'WOULDBLOCK' error for a maximum of Timeout
seconds.
The control 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 the Timeout
expires, and the operation is not yet complete, a Timeout
error is fired.
public void fireConnected(int statusCode, java.lang.String description)
IpportConnectedEvent
public void fireDataIn(byte[] text, boolean EOL)
IpportDataInEvent
public void fireDisconnected(int statusCode, java.lang.String description)
IpportDisconnectedEvent
public void fireError(int errorCode, java.lang.String description)
IpportErrorEvent
public void fireReadyToSend()
IpportReadyToSendEvent
public void connect(java.lang.String host, int port) throws IPWorksException
RemoteHost
property
to Host , setting RemotePort
to Port , and then setting
the Connected
property to True.
public void disconnect() throws IPWorksException
Connected
property
to False.
public void send(byte[] text) throws IPWorksException
DataToSend
property
to Text .
public void addIpportEventListener(IpportEventListener l) throws java.util.TooManyListenersException
public void removeIpportEventListener(IpportEventListener l)
|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |