NAME
IO::Socket::Multicast - Send and receive multicast messages
SYNOPSIS
use IO::Socket::Multicast;
# create a new UDP socket ready to read datagrams on port 1100
my $s = IO::Socket::Multicast->new(LocalPort=>1100);
# Add a multicast group
$s->mcast_add('225.0.1.1');
# Add a multicast group to eth0 device
$s->mcast_add('225.0.0.2','eth0');
# now receive some multicast data
$s->recv($data,1024);
# Drop a multicast group
$s->mcast_drop('225.0.0.1');
# Set outgoing interface to eth0
$s->mcast_if('eth0');
# Set time to live on outgoing multicast packets
$s->mcast_ttl(10);
# Turn off loopbacking
$s->mcast_loopback(0);
# Multicast a message to group 225.0.0.1
$s->mcast_send('hello world!','225.0.0.1:1200');
$s->mcast_set('225.0.0.2:1200');
$s->mcast_send('hello again!');
DESCRIPTION
The IO::Socket::Multicast module subclasses IO::Socket::INET to enable
you to manipulate multicast groups. With this module (and an operating
system that supports multicasting), you will be able to receive incoming
multicast transmissions and generate your own outgoing multicast
packets.
This module requires IO::Interface version 0.94 or higher.
INTRODUCTION
Multicasting is designed for streaming multimedia applications and for
conferencing systems in which one transmitting machines needs to
distribute data to a large number of clients.
IP addresses in the range 224.0.0.0 and 239.255.255.255 are reserved for
multicasting. These addresses do not correspond to individual machines,
but to multicast groups. Messages sent to these addresses will be
delivered to a potentially large number of machines that have registered
their interest in receiving transmissions on these groups. They work
like TV channels. A program tunes in to a multicast group to receive
transmissions to it, and tunes out when it no longer wishes to receive
the transmissions.
To receive transmissions from a multicast group, you will use
IO::Socket::INET->new() to create a UDP socket and bind it to a local
network port. You will then subscribe one or more multicast groups using
the mcast_add() method. Subsequent calls to the standard recv() method
will now receive messages incoming messages transmitted to the
subscribed groups using the selected port number.
To send transmissions to a multicast group, you can use the standard
send() method to send messages to the multicast group and port of your
choice. The mcast_set() and mcast_send() methods are provided as
convenience functions. Mcast_set() will set a default multicast
destination for messages which you then send with mcast_send().
To set the number of hops (routers) that outgoing multicast messages
will cross, call mcast_ttl(). To activate or deactivate the looping back
of multicast messages (in which a copy of the transmitted messages is
received by the local machine), call mcast_loopback().
CONSTRUCTORS
$socket = IO::Socket::Multicast->new([LocalPort=>$port,...])
The new() method is the constructor for the IO::Socket::Multicast
class. It takes the same arguments as IO::Socket::INET, except that
the Proto argument, rather than defaulting to "tcp", will default to
"udp", which is more appropriate for multicasting.
To create a UDP socket suitable for sending outgoing multicast
messages, call new() without arguments (or with "Proto=>'udp'").
To create a UDP socket that can also receive incoming multicast
transmissions on a specific port, call new() with the LocalPort
argument.
If you plan to run the client and server on the same machine, you
may wish to set the IO::Socket ReuseAddr argument to a true value.
This allows multiple multicast sockets to bind to the same address.
METHODS
$success = $socket->mcast_add($multicast_address [,$interface])
The mcast_add() method will add the provided multicast address to
the list of subscribed multicast groups. The address may be provided
either as a dotted-quad decimal, or as a packed IP address (such as
produced by the inet_aton() function). On success, the method will
return a true value.
The optional $interface argument can be used to specify on which
network interface to listen for incoming multicast messages. If the
IO::Interface module is installed, you may use the device name for
the interface (e.g. "tu0"). Otherwise, you must use the IP address
of the desired network interface. Either dotted quad form or packed
IP address is acceptable. If no interface is specified, then the
multicast group is joined on INADDR_ANY, meaning that multicast
transmissions received on any of the host's network interfaces will
be forwarded to the socket.
Note that mcast_add() operates on the underlying interface(s) and
not on the socket. If you have multiple sockets listening on a port,
and you mcast_add() a group to one of those sockets, subsequently
all the sockets will receive mcast messages on this group. To filter
messages that can be received by a socket so that only those sent to
a particular multicast address are received, pass the LocalAddr
option to the socket at the time you create it:
my $socket = IO::Socket::Multicast->new(LocalPort=>2000,
LocalAddr=>226.1.1.2',
ReuseAddr=>1);
$socket->mcast_add('226.1.1.2');
By combining this technique with IO::Select, you can write
applications that listen to multiple multicast groups and
distinguish which group a message was addressed to by identifying
which socket it was received on.
$success = $socket->mcast_drop($multicast_address)
This reverses the action of mcast_add(), removing the indicated
multicast address from the list of subscribed groups.
$loopback = $socket->mcast_loopback
$previous = $socket->mcast_loopback($new)
The mcast_loopback() method controls whether the socket will receive
its own multicast transmissions (default yes). Called without
arguments, the method returns the current state of the loopback
flag. Called with a boolean argument, the method will set the
loopback flag, and return its previous value.
$ttl = $socket->mcast_ttl
$previous = $socket->mcast_ttl($new)
The mcast_ttl() method examines or sets the time to live (TTL) for
outgoing multicast messages. The TTL controls the numbers of routers
the packet can cross before being expired. The default TTL is 1,
meaning that the message is confined to the local area network.
Values between 0 and 255 are valid.
Called without arguments, this method returns the socket's current
TTL. Called with a value, this method sets the TTL and returns its
previous value.
$interface = $socket->mcast_if
$previous = $socket->mcast_if($new)
By default, the OS will pick the network interface to use for
outgoing multicasts automatically. You can control this process by
using the mcast_if() method to set the outgoing network interface
explicitly. Called without arguments, returns the current interface.
Called with the name of an interface, sets the outgoing interface
and returns its previous value.
You can use the device name for the interface (e.g. "tu0") if the
IO::Interface module is present. Otherwise, you must use the
interface's dotted IP address.
NOTE: To set the interface used for incoming multicasts, use the
mcast_add() method.
$dest = $socket->mcast_dest
$previous = $socket->mcast_dest($new)
The mcast_dest() method is a convenience function that allows you to
set the default destination group for outgoing multicasts. Called
without arguments, returns the current destination as a packed
binary sockaddr_in data structure. Called with a new destination
address, the method sets the default destination and returns the
previous one, if any.
Destination addresses may be provided as packed sockaddr_in
structures, or in the form "XX.XX.XX.XX:YY" where the first part is
the IP address, and the second the port number.
$bytes = $socket->mcast_send($data [,$dest])
Mcast_send() is a convenience function that simplifies the sending
of multicast messages. $data is the message contents, and $dest is
an optional destination group. You can use either the dotted IP form
of the destination address and its port number, or a packed
sockaddr_in structure. If the destination is not supplied, it will
default to the most recent value set in mcast_dest() or a previous
call to mcast_send().
The method returns the number of bytes successfully queued for
delivery.
As a side-effect, the method will call mcast_dest() to remember the
destination address.
Example:
$socket->mcast_send('Hi there group members!','225.0.1.1:1900') || die;
$socket->mcast_send("How's the weather?") || die;
Note that you may still call IO::Socket::INET->new() with a
PeerAddr, and IO::Socket::INET will perform a connect(), creating a
default destination for calls to send().
EXAMPLE
The following is an example of a multicast server. Every 10 seconds it
transmits the current time and the list of logged-in users to the local
network using multicast group 226.1.1.2, port 2000 (these are chosen
arbitrarily).
#!/usr/bin/perl
# server
use strict;
use IO::Socket::Multicast;
use constant DESTINATION => '226.1.1.2:2000';
my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION);
while (1) {
my $message = localtime;
$message .= "\n" . `who`;
$sock->send($message) || die "Couldn't send: $!";
} continue {
sleep 10;
}
This is the corresponding client. It listens for transmissions on group
226.1.1.2, port 2000, and echoes the messages to standard output.
#!/usr/bin/perl
# client
use strict;
use IO::Socket::Multicast;
use constant GROUP => '226.1.1.2';
use constant PORT => '2000';
my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT);
$sock->mcast_add(GROUP) || die "Couldn't set group: $!\n";
while (1) {
my $data;
next unless $sock->recv($data,1024);
print $data;
}
EXPORT
None by default. However, if you wish to call mcast_add(), mcast_drop(),
mcast_if(), mcast_loopback(), mcast_ttl, mcast_dest() and mcast_send()
as functions you may import them explicitly on the use line or by
importing the tag ":functions".
BUGS
The mcast_if(), mcast_ttl() and mcast_loopback() methods will cause a
crash on versions of Linux earlier than 2.2.0 because of a kernel bug in
the implementation of the multicast socket options.
AUTHOR
Lincoln Stein, lstein@cshl.org.
This module is distributed under the same terms as Perl itself.
SEE ALSO
perl(1), IO::Socket(3), IO::Socket::INET(3).