net.rim.device.api.io
Interface MulticastDatagramConnection

All Superinterfaces:
Connection, DatagramConnection, UDPDatagramConnection

public interface MulticastDatagramConnection
extends UDPDatagramConnection

This interface contains methods to handle multicast datagram operations.

A MutlicastDatagramConnection can join multicast groups to receive UDP packets that are sent to those groups. MulticastDatagramConnection is not required for sending multicast packets. However, it provides the capabilities of setting multicast scope, and loopback mode. Unlike some other multicast implementations, such as winsock, MulticastDatagramConnection enables/disables loopback mode for the senders. Window-based simulator may have different behaviors.

Multicast group address is a class D address. In Blackberry, one multicast group address only can be subscribed by one application. Valid multicast group address is in range 224.0.0.0 through 239.255.255.255. 224.0.0.0 is reserved, 224.0.0.1 means "all hosts", and 224.0.0.2 means "all routers" on the subnet. Joining these groups may cause IOExceptions.

Sample code:

   String url = "datagram://:45456;interface=wifi";
   MulticastDatagramConnection  conn = null;

   //Open a “datagram” connection, and cast to MulticastDatagramConnection.
   conn = (MulticastDatagramConnection)Connector.open(url);

   //Join multiple groups.
   conn.joinGroup("224.0.0.3");
   conn.joinGroup("225.1.2.3");

   Datagram dgram = conn.newDatagram( 1024 );

   //Receive a UDP packet. The destination IP of the packet could be
   //"224.0.0.3", "225.1.2.3", or the device's IP.
   conn.receive( dgram );

   //Get the sender’s address.           
   String remoteAddr = dgram.getAddress();
   String msg = "Hi";

   dgram = conn.newDatagram( msg.getBytes(), msg.length(), remoteAddr);

   //Send back responses.
   conn.send( dgram );

   //Leave the groups
   conn.leaveGroup("224.0.0.3");
   conn.leaveGroup("225.1.2.3");

Since:
BlackBerry API 7.0.0

Method Summary
 boolean getLoopbackMode()
          Get the local loopback mode of the connection.
 int getTimeToLive()
          Get the time-to-live value of the connection.
 void joinGroup(String group)
          Join a specific multicast group.
 void leaveGroup(String group)
          Leave a specific multicast group.
 void setLoopbackMode(boolean disable)
          Set the local loopback mode for the connection.
 void setTimeToLive(int ttl)
          Set time-to-live setting for the connection.
 
Methods inherited from interface javax.microedition.io.UDPDatagramConnection
getLocalAddress, getLocalPort
 
Methods inherited from interface javax.microedition.io.DatagramConnection
getMaximumLength, getNominalLength, newDatagram, newDatagram, newDatagram, newDatagram, receive, send
 
Methods inherited from interface javax.microedition.io.Connection
close
 



Method Detail

getLoopbackMode

boolean getLoopbackMode()
                        throws IOException
Get the local loopback mode of the connection.

Returns:
true if local loopback is disabled; false otherwise
Throws:
IOException - if an I/O error occurs
Since:
BlackBerry API 7.0.0

getTimeToLive

int getTimeToLive()
                  throws IOException
Get the time-to-live value of the connection.

Returns:
the time-to-live value
Throws:
IOException - if an IO error occurs
Since:
BlackBerry API 7.0.0

joinGroup

void joinGroup(String group)
               throws IOException
Join a specific multicast group. A MulticastDatagramConnection can join multiple multicast groups at the same time.

Parameters:
group - the multicast group address to join
Throws:
IOException - if an I/O error occurs, the group address is not a multicast address, the group is not supported, the group is subscribed by another MulticastDatagramConnection, or it is already a member of the group.
IllegalArgumentException - if group is not a valid IPv4 address
Since:
BlackBerry API 7.0.0

leaveGroup

void leaveGroup(String group)
                throws IOException
Leave a specific multicast group.

Parameters:
group - the multicast group to leave
Throws:
IOException - if an I/O error occurs, the group is not a multicast address, or the connection is not a member of the group.
IllegalArgumentException - if group is not a valid IPv4 address
Since:
BlackBerry API 7.0.0

setLoopbackMode

void setLoopbackMode(boolean disable)
                     throws IOException
Set the local loopback mode for the connection.

When loopback mode is disabled, the sender connection will not loop back the multicast to local sockets. Loopback mode is enabled by default.

Parameters:
disable - true to disable the loopback mode
Throws:
IOException - if an I/O error occurs
Since:
BlackBerry API 7.0.0

setTimeToLive

void setTimeToLive(int ttl)
                   throws IOException
Set time-to-live setting for the connection.

Multicast connection uses TTL to control the datagram's scope(or range).

The value of TTL must be between 1 and 255. The default TTL setting of the connection is 1, which means that the datagram it sends out is restricted to the same subnet.

Note: Addresses 224.0.0.0 - 224.0.0.255 are intended for the communications within the same network. Multicast rounters will not forward these packets regardless of the TTL value.

Parameters:
ttl - time-to-live value
Throws:
IOException - if an I/O error occurs, or ttl value is out of range
Since:
BlackBerry API 7.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal