IP*Works!

ipworks
Class Mcast

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

public class Mcast
extends java.lang.Object

The MCast control is used to multicast UDP datagrams to multicast capable hosts in multicast capable subnets. 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 MCast control is very similar to UDPPort, except for some additional properties that provide support for multicast datagrams. To send datagrams to a multicast group, simply assign the address of the group to RemoteHost . To receive datagrams from one or more groups, assign the group addresses to MulticastGroup one by one (after the control is activated. TimeToLive allows to specify how many subnets a packet should be allowed to receive. ReceiveInterface and SendInterface allow you to select the network interface for multicast operations.

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 UDPPort, by calling the Send method with a Text parameter or via the DataToSend property. The destination is specified using the RemoteHost and RemotePort properties. Inbound data is received through the DataIn event.


Constructor Summary
Mcast()
           
 
Method Summary
 void addMcastEventListener(McastEventListener 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 MCast binds.
 int getMaxPacketSize()
          The maximum length of the packets that can be received.
 java.lang.String getMulticastGroup()
          Multicast group to join or leave.
 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 getReceiveInterface()
          The interface where to receive multicast packets into.
 java.lang.String getRemoteHost()
          The address of the remote host (multicast group).
 int getRemotePort()
          The UDP port in the remote host.
 java.lang.String getSendInterface()
          The interface where to send multicast packets from.
 int getTimeToLive()
          The maximum number of subnets that a multicast datagram can traverse.
 boolean isAcceptData()
          Enables or disables data reception (the DataIn event).
 boolean isActive()
          Enables or disables sending and receiving of data.
 boolean isLoopback()
          Enables or disables loopback of data sent to the multicast group.
 boolean isShareLocalPort()
          If set to True, allows more than one instance of the component to be Active on the same LocalPort .
 void removeMcastEventListener(McastEventListener 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 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 MCast binds.
 void setLoopback(boolean loopback)
          Enables or disables loopback of data sent to the multicast group.
 void setMaxPacketSize(int maxPacketSize)
          The maximum length of the packets that can be received.
 void setMulticastGroup(java.lang.String multicastGroup)
          Multicast group to join or leave.
 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 setReceiveInterface(java.lang.String receiveInterface)
          The interface where to receive multicast packets into.
 void setRemoteHost(java.lang.String remoteHost)
          The address of the remote host (multicast group).
 void setRemotePort(int remotePort)
          The UDP port in the remote host.
 void setSendInterface(java.lang.String sendInterface)
          The interface where to send multicast packets from.
 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 multicast datagram can traverse.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Mcast

public Mcast()
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 MCast 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.


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


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 .


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 MCast 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 MCast 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 MCast binds. The LocalPort property must be set before MCast 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 send data 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 MCast binds. The LocalPort property must be set before MCast 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 send data to services that require a trusted port in the client side.


isLoopback

public boolean isLoopback()
Enables or disables loopback of data sent to the multicast group. Setting the property to False, disables loopback of data sent through the control (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.


setLoopback

public void setLoopback(boolean loopback)
                 throws IPWorksException
Enables or disables loopback of data sent to the multicast group. Setting the property to False, disables loopback of data sent through the control (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.


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 .


getMulticastGroup

public java.lang.String getMulticastGroup()
Multicast group to join or leave. Multicast groups are joined by assigning values to this property after the control is activated. More than one group may be joined at the same time. To define which interface to use, the ReceiveInterface property is used.

If the first letter of MulticastGroup is "-" or "+" it determines whether the groups should be joined or left respectively. The default operation is join.

To remove the control from a multicast group once it is joined, simply assign this groupname (address) to MulticastGroup prefixed by a minus sign "-".


setMulticastGroup

public void setMulticastGroup(java.lang.String multicastGroup)
                       throws IPWorksException
Multicast group to join or leave. Multicast groups are joined by assigning values to this property after the control is activated. More than one group may be joined at the same time. To define which interface to use, the ReceiveInterface property is used.

If the first letter of MulticastGroup is "-" or "+" it determines whether the groups should be joined or left respectively. The default operation is join.

To remove the control from a multicast group once it is joined, simply assign this groupname (address) to MulticastGroup prefixed by a minus sign "-".


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


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


getReceiveInterface

public java.lang.String getReceiveInterface()
The interface where to receive multicast packets into. If empty, default is used. This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default.

The ReceiveInterface property is used together with the MulticastGroup property to join one or more multicast groups. The joining is done after the control is active by assigning proper values to MulticastGroup .


setReceiveInterface

public void setReceiveInterface(java.lang.String receiveInterface)
                         throws IPWorksException
The interface where to receive multicast packets into. If empty, default is used. This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default.

The ReceiveInterface property is used together with the MulticastGroup property to join one or more multicast groups. The joining is done after the control is active by assigning proper values to MulticastGroup .


getRemoteHost

public java.lang.String getRemoteHost()
The address of the remote host (multicast group). To send a multicast datagram, specify a RemoteHost value in the range of 224.0.0.0 to 239.255.255.255. These addresses are reserved as multicast addresses by IP.


setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws IPWorksException
The address of the remote host (multicast group). To send a multicast datagram, specify a RemoteHost value in the range of 224.0.0.0 to 239.255.255.255. These addresses are reserved as multicast addresses by IP.


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.


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.


getSendInterface

public java.lang.String getSendInterface()
The interface where to send multicast packets from. If empty, default is used. This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default.


setSendInterface

public void setSendInterface(java.lang.String sendInterface)
                      throws IPWorksException
The interface where to send multicast packets from. If empty, default is used. This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default.


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 multicast datagram can traverse. The default value for this property is 7. This is an arbitrary value. You need to specify a value suitable for your application.

Multicast datagrams with a TimeToLive of 0 are not transmitted on any subnetwork. Multicast datagrams with a TimeToLive of 1 are delivered only on the local network. Multicast datagrams with a TimeToLive of greater than 1 may be delivered to more than one subnetwork if there are one or more multicast routers attached to the first-hop subnetwork.

A multicast router does not forward multicast datagrams with destination addresses between 224.0.0.0 and 224.0.0.255, inclusive, regardless of their TimeToLive . This particular range of addresses is reserved for the use of routing protocols and other low-level topology discovery or maintenance protocols, such as gateway discovery and group membership reporting.


setTimeToLive

public void setTimeToLive(int timeToLive)
                   throws IPWorksException
The maximum number of subnets that a multicast datagram can traverse. The default value for this property is 7. This is an arbitrary value. You need to specify a value suitable for your application.

Multicast datagrams with a TimeToLive of 0 are not transmitted on any subnetwork. Multicast datagrams with a TimeToLive of 1 are delivered only on the local network. Multicast datagrams with a TimeToLive of greater than 1 may be delivered to more than one subnetwork if there are one or more multicast routers attached to the first-hop subnetwork.

A multicast router does not forward multicast datagrams with destination addresses between 224.0.0.0 and 224.0.0.255, inclusive, regardless of their TimeToLive . This particular range of addresses is reserved for the use of routing protocols and other low-level topology discovery or maintenance protocols, such as gateway discovery and group membership reporting.


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:
McastDataInEvent

fireError

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

fireReadyToSend

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

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 .


addMcastEventListener

public void addMcastEventListener(McastEventListener l)
                           throws java.util.TooManyListenersException

removeMcastEventListener

public void removeMcastEventListener(McastEventListener l)

IP*Works!

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