IP*Works!

ipworks
Class Udpport

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

public class Udpport
extends java.lang.Object

The UDPPort control 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 control is similar to the interface of IPPort, only much simpler. The control 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 property is set to True, then a local association is created with the remote host. Otherwise, the control can receive datagrams (packets) from any host, and send datagrams to any host. Packets can be broadcasted on the local net by setting the destination ( RemoteHost ) to 255.255.255.255.

The operation of the control 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()
           
 
Method Summary
 void addUdpportEventListener(UdpportEventListener l)
           
 void fireDataIn(byte[] datagram, java.lang.String sourceAddress, int sourcePort)
          Fired when data is received.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireReadyToSend()
          Fired when the component is ready to send data.
 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 UDP port in the local host where UDPPort binds.
 int getMaxPacketSize()
          The maximum length of the packets that can be received.
 int getOutBufferSize()
          The size in bytes of the outgoing queue of the socket.
 int getQOSFlags()
          Flags determining Quality Of Service bits of packets sent by the socket.
 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, forces the socket to send data directly to interface (no routing).
 boolean isShareLocalPort()
          If set to True, allows more than one instance of the component to be Active on the same LocalPort .
 boolean isUseConnection()
          If set, the component connects to the RemoteHost .
 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, forces the socket to send data directly to interface (no routing).
 void setInBufferSize(int inBufferSize)
          The size in bytes of the incoming queue of the socket.
 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 setMaxPacketSize(int maxPacketSize)
          The maximum length of the packets that can be received.
 void setOutBufferSize(int outBufferSize)
          The size in bytes of the outgoing queue of the socket.
 void setQOSFlags(int QOSFlags)
          Flags determining Quality Of Service bits of packets sent by the socket.
 void setRemoteHost(java.lang.String remoteHost)
          The address of the remote host.
 void setRemotePort(int remotePort)
          The UDP port in the remote host.
 void setShareLocalPort(boolean shareLocalPort)
          If set to True, allows more than one instance of the component to be Active on the same LocalPort .
 void setTimeToLive(int timeToLive)
          The maximum number of subnets that a datagram can traverse.
 void setUseConnection(boolean useConnection)
          If set, the component connects to the RemoteHost .
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Udpport

public Udpport()
Method Detail

isAcceptData

public boolean isAcceptData()
Enables or disables data reception (the DataIn event). Setting the property to False, temporarily disables data reception (and the DataIn event). Setting the property to True, reenables data reception.


setAcceptData

public void setAcceptData(boolean acceptData)
                   throws IPWorksException
Enables or disables data reception (the DataIn event). Setting the property to False, temporarily disables data reception (and the DataIn event). Setting the property to True, reenables data reception.


isActive

public boolean isActive()
Enables or disables sending and receiving of data. Action property. Setting the Active property to True makes UDPPort 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 the UseConnection property is set to True, then a local association (connection) to the remote host and port is also created.


setActive

public void setActive(boolean active)
               throws IPWorksException
Enables or disables sending and receiving of data. Action property. Setting the Active property to True makes UDPPort 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 the UseConnection property is set to True, then a local association (connection) to the remote host and port is also created.


setDataToSend

public void setDataToSend(byte[] dataToSend)
                   throws IPWorksException
A string of data to be sent to the remote host. Write-only property. The DataToSend property is an action property. Assigning a string to this property makes the control send the string to the remote host .

Winsock attempts to send the string assigned to DataToSend as a complete message. If Winsock 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


isDontRoute

public boolean isDontRoute()
If set to True, 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 the DontRoute flag is set to True, then data will be delivered on the local subnet only.


setDontRoute

public void setDontRoute(boolean dontRoute)
                  throws IPWorksException
If set to True, 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 the DontRoute flag is set to True, then data will be delivered on the local subnet only.


getInBufferSize

public int getInBufferSize()
The size in bytes of the incoming queue of the socket. This is the size of an internal queue in the Winsock 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 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 UDPPort is activated the InBufferSize property reverts to its defined size. The same happens if you attempt to make it too large or too small.


setInBufferSize

public void setInBufferSize(int inBufferSize)
                     throws IPWorksException
The size in bytes of the incoming queue of the socket. This is the size of an internal queue in the Winsock 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 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 UDPPort is activated the InBufferSize property reverts to its defined size. The same happens if you attempt to make it too large or too small.


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() 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.


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() 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.


getLocalPort

public int getLocalPort()
The UDP port in the local host where UDPPort binds. The LocalPort property must be set before UDPPort is activated ( Active is set to True). 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 the control is Active . Any attempt to set the LocalPort property when the control 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.


setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksException
The UDP port in the local host where UDPPort binds. The LocalPort property must be set before UDPPort is activated ( Active is set to True). 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 the control is Active . Any attempt to set the LocalPort property when the control 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.


getMaxPacketSize

public int getMaxPacketSize()
The maximum length of the packets that can be received. The MaxPacketSize specifies the maximum size of the datagrams that the control will accept without truncation.

The control poses no restrictions on the packet (datagram) sizes, however, Winsock limits this to WinsockMaxDatagramSize .


setMaxPacketSize

public void setMaxPacketSize(int maxPacketSize)
                      throws IPWorksException
The maximum length of the packets that can be received. The MaxPacketSize specifies the maximum size of the datagrams that the control will accept without truncation.

The control poses no restrictions on the packet (datagram) sizes, however, Winsock limits this to WinsockMaxDatagramSize .


getOutBufferSize

public int getOutBufferSize()
The size in bytes of the outgoing queue of the socket. This is the size of an internal queue in the Winsock 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 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 UDPPort is activated the OutBufferSize property reverts to its defined size. The same happens if you attempt to make it too large or too small.


setOutBufferSize

public void setOutBufferSize(int outBufferSize)
                      throws IPWorksException
The size in bytes of the outgoing queue of the socket. This is the size of an internal queue in the Winsock 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 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 UDPPort is activated the OutBufferSize property reverts to its defined size. The same happens if you attempt to make it too large or too small.


getQOSFlags

public int getQOSFlags()
Flags determining Quality Of Service bits of packets sent by the socket. The default value for QOSFlags is 0, which tells the control to use the default QOS value of the underlying TCP/IP subsystem.

You may specify other values by OR-ing a precedence value consisting of one of the following:

0
Routine
32
Priority
64
Immediate
96
Flash
128
Flash Override
160
Critical
192
Internetwork Control
224
Network Control
with one or more of the following type of service flags:
4
(R) Maximize Reliability
8
(T) Maximize Throughput
16
(D) Minimize Delay
This property is useful for applications with special performance requirements such as real time audio, video, etc..

NOTE: some versions of Winsock may ignore the QOS values altogether unless you set UseConnection to True first.


setQOSFlags

public void setQOSFlags(int QOSFlags)
                 throws IPWorksException
Flags determining Quality Of Service bits of packets sent by the socket. The default value for QOSFlags is 0, which tells the control to use the default QOS value of the underlying TCP/IP subsystem.

You may specify other values by OR-ing a precedence value consisting of one of the following:

0
Routine
32
Priority
64
Immediate
96
Flash
128
Flash Override
160
Critical
192
Internetwork Control
224
Network Control
with one or more of the following type of service flags:
4
(R) Maximize Reliability
8
(T) Maximize Throughput
16
(D) Minimize Delay
This property is useful for applications with special performance requirements such as real time audio, video, etc..

NOTE: some versions of Winsock may ignore the QOS values altogether unless you set UseConnection to True first.


getRemoteHost

public java.lang.String getRemoteHost()
The address of the remote host. Domain names are resolved to IP addresses. 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 control 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 specified, the RemoteHost must be set before the control is activated ( Active is set to True).


setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws IPWorksException
The address of the remote host. Domain names are resolved to IP addresses. 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 control 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 specified, the RemoteHost must be set before the control is activated ( Active is set to True).


getRemotePort

public int getRemotePort()
The UDP port in the remote host. The RemotePort is the UDP port on the RemoteHost where to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

If UseConnection is specified, the RemotePort must be set before the control is activated ( Active is set to True).


setRemotePort

public void setRemotePort(int remotePort)
                   throws IPWorksException
The UDP port in the remote host. The RemotePort is the UDP port on the RemoteHost where to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

If UseConnection is specified, the RemotePort must be set before the control is activated ( Active is set to True).


isShareLocalPort

public boolean isShareLocalPort()
If set to True, allows more than one instance of the component to be Active on the same LocalPort . This option must be set before the control is activated through the Active property or it will have no effect.


setShareLocalPort

public void setShareLocalPort(boolean shareLocalPort)
                       throws IPWorksException
If set to True, allows more than one instance of the component to be Active on the same LocalPort . This option must be set before the control is activated through the Active property or it will have no effect.


getTimeToLive

public int getTimeToLive()
The maximum number of subnets that a datagram can traverse. The default value for this property is 0, which tells the control 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.


setTimeToLive

public void setTimeToLive(int timeToLive)
                   throws IPWorksException
The maximum number of subnets that a datagram can traverse. The default value for this property is 0, which tells the control 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.


isUseConnection

public boolean isUseConnection()
If set, the component connects to the RemoteHost . The UseConnection property specifies whether the control should use a connected socket or not. The connection is defined as an association in between the local address and port and the remote address and port. As such, this is not a connection in the traditional TCP sense. What it means is only that the control will send and receive data only to and from the specified destination.


setUseConnection

public void setUseConnection(boolean useConnection)
                      throws IPWorksException
If set, the component connects to the RemoteHost . The UseConnection property specifies whether the control should use a connected socket or not. The connection is defined as an association in between the local address and port and the remote address and port. As such, this is not a connection in the traditional TCP sense. What it means is only that the control will send and receive data only to and from the specified destination.


fireDataIn

public void fireDataIn(byte[] datagram,
                       java.lang.String sourceAddress,
                       int sourcePort)
Fired when data is received. (Called internally to dispatch the event.)
See Also:
UdpportDataInEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
UdpportErrorEvent

fireReadyToSend

public void fireReadyToSend()
Fired when the component is ready to send data. (Called internally to dispatch the event.)
See Also:
UdpportReadyToSendEvent

send

public void send(byte[] text)
          throws IPWorksException
Send data to the remote host. Calling this method is equivalent to setting the DataToSend property to Text .


addUdpportEventListener

public void addUdpportEventListener(UdpportEventListener l)
                             throws java.util.TooManyListenersException

removeUdpportEventListener

public void removeUdpportEventListener(UdpportEventListener l)

IP*Works!

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