|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Udpport
public class Udpport
The UDPPort bean is used to facilitate UDP (datagram) communications. It can act both as a client and a server and communicate with any number of hosts simultaneously, as well as generate and receive broadcast packets.
The interface of the bean is similar to the interface of IPPort,
only much simpler. The bean is activated/deactivated through the Active
property. This property enables or disables sends or receives.
The data can be sent in the same way as IPPort, using the Send
method
and specifying the text to send. This is identical to assigning data to
the DataToSend
property. The destination is specified using the RemoteHost
and RemotePort
properties. Inbound data
is received through the DataIn
event.
If the UseConnection
config setting is set to True, then a local association is
created with the remote host. Otherwise, the bean can receive datagrams
(packets) from any host, and send datagrams to any host. Packets can be
broadcast on the local net by setting the destination ( RemoteHost
)
to 255.255.255.255.
The operation of the bean is almost completely asynchronous. All 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.
Constructor Summary | |
---|---|
Udpport()
Creates an instance of Udpport Bean. |
|
Udpport(java.lang.String runtimeLicense)
Creates an instance of Udpport Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addUdpportEventListener(UdpportEventListener l)
|
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a configuration setting. |
void |
doEvents()
Processes events from the internal message queue. |
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 UDP port in the local host where UDPPort binds. |
java.lang.String |
getRemoteHost()
The address of the remote host. |
int |
getRemotePort()
The UDP port in the remote host. |
int |
getTimeToLive()
The maximum number of subnets that a datagram can traverse. |
boolean |
isAcceptData()
Enables or disables data reception (the DataIn event). |
boolean |
isActive()
Enables or disables sending and receiving of data. |
boolean |
isDontRoute()
If set to True, it forces the socket to send data directly to interface (no routing). |
void |
removeUdpportEventListener(UdpportEventListener l)
|
void |
send(byte[] text)
Send data to the remote host. |
void |
setAcceptData(boolean acceptData)
Enables or disables data reception (the DataIn event). |
void |
setActive(boolean active)
Enables or disables sending and receiving of data. |
void |
setDataToSend(byte[] dataToSend)
A string of data to be sent to the remote host. |
void |
setDontRoute(boolean dontRoute)
If set to True, it forces the socket to send data directly to interface (no routing). |
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 UDP port in the local host where UDPPort binds. |
void |
setRemoteHost(java.lang.String remoteHost)
The address of the remote host. |
void |
setRemotePort(int remotePort)
The UDP port in the remote host. |
void |
setTimeToLive(int timeToLive)
The maximum number of subnets that a datagram can traverse. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Udpport()
public Udpport(java.lang.String runtimeLicense)
Method Detail |
---|
public boolean isAcceptData()
DataIn
event).
This property enables or disables data reception (the DataIn event). Setting this property to False, temporarily disables data reception
(and the DataIn
event). Setting this property to True, re-enables
data reception.
public void setAcceptData(boolean acceptData) throws IPWorksException
DataIn
event).
This property enables or disables data reception (the DataIn event). Setting this property to False, temporarily disables data reception
(and the DataIn
event). Setting this property to True, re-enables
data reception.
IPWorksException
public boolean isActive()
Setting the Active
property to True makes the bean create a
communication endpoint (socket) which can be used for sending
and receiving UDP datagrams. Setting it to False destroys
the socket and disables data communications.
If UseConnection
is set to True, then a local
association (connection) to the remote host and port is also
created.
public void setActive(boolean active) throws IPWorksException
Setting the Active
property to True makes the bean create a
communication endpoint (socket) which can be used for sending
and receiving UDP datagrams. Setting it to False destroys
the socket and disables data communications.
If UseConnection
is set to True, then a local
association (connection) to the remote host and port is also
created.
IPWorksException
public void setDataToSend(byte[] dataToSend) throws IPWorksException
Assigning a string to the DataToSend
property makes the bean send
the string to the remote host. The Send
method provides similar functionality.
Attempts to send the string assigned to DataToSend
as a complete message.
If system buffers are full, or the message cannot be delivered
for any other reason, an error is fired, and no portion of the
message is sent. This is different from TCP where portions of
the messages can be sent. UDP sends either a complete message or
nothing at all.
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
fails with exception 10035: "[10035] Operation would block" (WSAEWOULDBLOCK).
You can check this error, and then try to send the data again.
Example (Send Data)
UDPPortControl.LocalPort = 8765
UDPPortControl.RemotePort = 8765
UDPPortControl.RemoteHost = "HostNameOrIPAddress"
UDPPortControl.Active = True
UDPPortControl.DataToSend = "Hello!"
IPWorksException
public boolean isDontRoute()
If this property is set to True, it forces the socket to send data directly to interface (no routing). Normally IP sockets send packets of data through routers and gateways until they reach the final destination. If this property is set to True, then data will be delivered on the local subnet only.
public void setDontRoute(boolean dontRoute) throws IPWorksException
If this property is set to True, it forces the socket to send data directly to interface (no routing). Normally IP sockets send packets of data through routers and gateways until they reach the final destination. If this property is set to True, then data will be delivered on the local subnet only.
IPWorksException
public java.lang.String getLocalHost()
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.
public void setLocalHost(java.lang.String localHost) throws IPWorksException
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.
IPWorksException
public int getLocalPort()
The LocalPort
property must be set before UDPPort is
activated ( Active
is set to True). It instructs the
bean to bind to a specific port (or communication
endpoint) in the local machine.
Setting it to 0 (default) enables the TCP/IP stack 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 the bean is Active
.
Any attempt to set the LocalPort
property when the bean
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.
public void setLocalPort(int localPort) throws IPWorksException
The LocalPort
property must be set before UDPPort is
activated ( Active
is set to True). It instructs the
bean to bind to a specific port (or communication
endpoint) in the local machine.
Setting it to 0 (default) enables the TCP/IP stack 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 the bean is Active
.
Any attempt to set the LocalPort
property when the bean
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.
IPWorksException
public java.lang.String getRemoteHost()
The RemoteHost
property specifies the IP address (IP number in
dotted internet format) or Domain Name of the remote host.
If RemoteHost
is set to 255.255.255.255, the bean broadcasts
data on the local subnet.
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.
If UseConnection
is set to True, the RemoteHost
must
be set before the bean is activated ( Active
is set to True).
public void setRemoteHost(java.lang.String remoteHost) throws IPWorksException
The RemoteHost
property specifies the IP address (IP number in
dotted internet format) or Domain Name of the remote host.
If RemoteHost
is set to 255.255.255.255, the bean broadcasts
data on the local subnet.
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.
If UseConnection
is set to True, the RemoteHost
must
be set before the bean is activated ( Active
is set to True).
IPWorksException
public int getRemotePort()
The RemotePort
is the UDP port on the RemoteHost
to
send UDP datagrams to.
A valid port number (a value between 1 and 65535) is required.
If UseConnection
is set to True, the RemotePort
must
be set before the bean is activated ( Active
is set to True).
public void setRemotePort(int remotePort) throws IPWorksException
The RemotePort
is the UDP port on the RemoteHost
to
send UDP datagrams to.
A valid port number (a value between 1 and 65535) is required.
If UseConnection
is set to True, the RemotePort
must
be set before the bean is activated ( Active
is set to True).
IPWorksException
public int getTimeToLive()
The default value for this property is 0, which tells the bean to use the default TTL value of the underlying TCP/IP subsystem. Depending on the application, you can specify a value between 1 and 255.
public void setTimeToLive(int timeToLive) throws IPWorksException
The default value for this property is 0, which tells the bean to use the default TTL value of the underlying TCP/IP subsystem. Depending on the application, you can specify a value between 1 and 255.
IPWorksException
public java.lang.String config(java.lang.String configurationString) throws IPWorksException
Config
is a generic method available in every bean.
It is used to set and retrieve configuration settings
for the
bean.
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.
The bean accepts one or more of the following configuration settings .
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
Note: This setting is only available in Windows.
CaptureIPPacketInfo
is set to true, then this will be populated with the packet's destination address when a packet is received.
This information will be accessible in the DataIn event.Note: This setting is only available in Windows.
LocalHost
setting contains the name of the local host
as obtained by the gethostname() system call, or if the
user has assigned an IP address, the value of that address.In multi-homed hosts (machines with more than one IP interface)
setting LocalHost to the value of an interface will make the
bean initiate connections (or accept in the case of server
beans) only through that interface.
If the bean is connected, the LocalHost
setting shows
the IP address of the interface through which the connection
is made in internet dotted format (aaa.bbb.ccc.ddd). In most
cases, this is the address of the local host, except for multi-homed
hosts (machines with more than one IP interface).
LocalPort
after the connection is established.
LocalPort
cannot be changed once a connection is made.
Any attempt to set this when a connection is active will
generate an error.
This; setting is useful when trying to connect to services that require a trusted port in the client side. An example is the remote shell (rsh) service in UNIX systems.
Active
property or it will have no effect.The default value for this setting is False.
UseConnection
specifies whether the bean
should use a connected socket or not. The connection is
defined as an association in between the local address/port
and the remote address/port. As such, this
is not a connection in the traditional TCP sense. What it
means is only that the bean will send and receive data
only to and from the specified destination.The default value for this setting is False.
UseConnection
must be True to use this setting. This option allows you to specify an arbitrary DSCP value
between 0 and 63. The default is 0. When set to the default value the component will not set a DSCP value.Note: This setting uses the qWAVE API is only available on Windows 7, Windows Server 2008 R2, and later.
UseConnection
must be True to use this setting.
You may specify either the text or integer values: BestEffort (0), Background (1), ExcellentEffort (2), AudioVideo (3), Voice (4), and Control (5).Note: This setting uses the qWAVE API which is only available on Windows Vista and Windows Server 2008 or above.
Note: QOSTrafficType must be set before setting Active
to true.
IPWorksException
public void doEvents() throws IPWorksException
When DoEvents
is called, the bean processes any
available events. If no events are available, it waits for a
preset period of time, and then returns.
IPWorksException
public void send(byte[] text) throws IPWorksException
Calling this method is equivalent to setting the DataToSend
property
to Text .
Example (Send Data)
UDPPortControl.LocalPort = 8765
UDPPortControl.RemotePort = 8765
UDPPortControl.RemoteHost = "HostNameOrIPAddress"
UDPPortControl.Active = True
UDPPortControl.Send("Hello!")
IPWorksException
public void addUdpportEventListener(UdpportEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeUdpportEventListener(UdpportEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |