|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Mcast
public class Mcast
The MCast bean 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 bean 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 bean 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 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 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()
Creates an instance of Mcast Bean. |
|
Mcast(java.lang.String runtimeLicense)
Creates an instance of Mcast Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addMcastEventListener(McastEventListener 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 MCast binds. |
java.lang.String |
getMulticastGroup()
Multicast group to join or leave. |
java.lang.String |
getReceiveInterface()
The interface with which to receive multicast packets. |
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 from which multicast packets are sent. |
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 data. |
boolean |
isLoopback()
Enables or disables loopback of data sent to the multicast group. |
void |
removeMcastEventListener(McastEventListener l)
|
void |
send(byte[] text)
Sends 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 data. |
void |
setDataToSend(byte[] dataToSend)
A string of data to be sent to the remote host. |
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 |
setMulticastGroup(java.lang.String multicastGroup)
Multicast group to join or leave. |
void |
setReceiveInterface(java.lang.String receiveInterface)
The interface with which to receive multicast packets. |
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 from which multicast packets are sent. |
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 |
---|
public Mcast()
public Mcast(java.lang.String runtimeLicense)
Method Detail |
---|
public boolean isAcceptData()
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
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()
This property enables or disables sending and receiving data. Setting this property to True makes MCast create a communication endpoint (socket) which can be used for sending and receiving UDP datagrams. Setting this property to False destroys the socket and disables data communications.
public void setActive(boolean active) throws IPWorksException
This property enables or disables sending and receiving data. Setting this property to True makes MCast create a communication endpoint (socket) which can be used for sending and receiving UDP datagrams. Setting this property to False destroys the socket and disables data communications.
IPWorksException
public void setDataToSend(byte[] dataToSend) throws IPWorksException
This write-only property contains a string of data to be sent to the remote host. Assigning a string to this property makes the bean send
the string to the remote host. The Send
method provides similar functionality.
The TCP/IP subsystem attempts to send the string assigned to this property as a complete message. If socket buffers are full, or the message cannot be delivered for any 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. The bean 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, this property fails with exception 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. .
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()
This property must be set before MCast 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 system to choose a port at random. The chosen port will be shown by this property after the connection is established.
This property cannot be changed once the bean is Active
.
Any attempt to set this property when the bean
is Active
will generate an error.
This property is useful when trying to send data to services that require a trusted port in the client side.
public void setLocalPort(int localPort) throws IPWorksException
This property must be set before MCast 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 system to choose a port at random. The chosen port will be shown by this property after the connection is established.
This property cannot be changed once the bean is Active
.
Any attempt to set this property when the bean
is Active
will generate an error.
This property is useful when trying to send data to services that require a trusted port in the client side.
IPWorksException
public boolean isLoopback()
This property enables or disables loopback of data sent to the multicast group. Setting this property to False disables loopback of data sent through the bean (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.
public void setLoopback(boolean loopback) throws IPWorksException
This property enables or disables loopback of data sent to the multicast group. Setting this property to False disables loopback of data sent through the bean (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.
IPWorksException
public java.lang.String getMulticastGroup()
This property contains the multicast group to join or leave. Multicast groups are joined by assigning values
to this property after the bean is activated. More
than one group may be joined at the same time. To define
which interface to use, the ReceiveInterface
property is
used.
Determining whether a group is left or joined is done by setting the first letter of MulticastGroup
is "-" or "+". The default operation is join.
To remove the
bean from a multicast group once it is joined, simply assign
this groupname (address) to MulticastGroup
prefixed by a
minus sign "-".
Example (Joining/Leaving Groups)
MCastControl.Active = true
MCastControl.MulticastGroup = "+231.31.31.31"
MCastControl.MulticastGroup = "+232.32.32.32"
MCastControl.MulticastGroup = "-232.32.32.32"
MCastControl.MulticastGroup = "-231.31.31.31"
public void setMulticastGroup(java.lang.String multicastGroup) throws IPWorksException
This property contains the multicast group to join or leave. Multicast groups are joined by assigning values
to this property after the bean is activated. More
than one group may be joined at the same time. To define
which interface to use, the ReceiveInterface
property is
used.
Determining whether a group is left or joined is done by setting the first letter of MulticastGroup
is "-" or "+". The default operation is join.
To remove the
bean from a multicast group once it is joined, simply assign
this groupname (address) to MulticastGroup
prefixed by a
minus sign "-".
Example (Joining/Leaving Groups)
MCastControl.Active = true
MCastControl.MulticastGroup = "+231.31.31.31"
MCastControl.MulticastGroup = "+232.32.32.32"
MCastControl.MulticastGroup = "-232.32.32.32"
MCastControl.MulticastGroup = "-231.31.31.31"
IPWorksException
public java.lang.String getReceiveInterface()
This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.
This property is used together with the MulticastGroup
property to join one or more multicast groups. The joining is done after
the bean is activated by assigning proper values to MulticastGroup
.
public void setReceiveInterface(java.lang.String receiveInterface) throws IPWorksException
This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.
This property is used together with the MulticastGroup
property to join one or more multicast groups. The joining is done after
the bean is activated by assigning proper values to MulticastGroup
.
IPWorksException
public java.lang.String getRemoteHost()
This property contains 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.
public void setRemoteHost(java.lang.String remoteHost) throws IPWorksException
This property contains 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.
IPWorksException
public int getRemotePort()
This property contains the UDP port on the RemoteHost
to
send UDP datagrams to.
A valid port number (a value between 1 and 65535) is required.
public void setRemotePort(int remotePort) throws IPWorksException
This property contains the UDP port on the RemoteHost
to
send UDP datagrams to.
A valid port number (a value between 1 and 65535) is required.
IPWorksException
public java.lang.String getSendInterface()
This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.
public void setSendInterface(java.lang.String sendInterface) throws IPWorksException
This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.
IPWorksException
public int getTimeToLive()
This property contains 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 this property set to 0 are not transmitted on any subnetwork. Multicast datagrams with this property set to 1 are delivered only on the local network. Multicast datagrams with this property set to 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.
public void setTimeToLive(int timeToLive) throws IPWorksException
This property contains 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 this property set to 0 are not transmitted on any subnetwork. Multicast datagrams with this property set to 1 are delivered only on the local network. Multicast datagrams with this property set to 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.
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
This method sends data to the remote host. Calling this method is equivalent to setting the DataToSend
property
to Text .
IPWorksException
public void addMcastEventListener(McastEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeMcastEventListener(McastEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |