| 1 |
NAME |
| 2 |
IO::Socket::Multicast - Send and receive multicast messages |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use IO::Socket::Multicast; |
| 6 |
|
| 7 |
# create a new UDP socket ready to read datagrams on port 1100 |
| 8 |
my $s = IO::Socket::Multicast->new(LocalPort=>1100); |
| 9 |
|
| 10 |
# Add a multicast group |
| 11 |
$s->mcast_add('225.0.1.1'); |
| 12 |
|
| 13 |
# Add a multicast group to eth0 device |
| 14 |
$s->mcast_add('225.0.0.2','eth0'); |
| 15 |
|
| 16 |
# now receive some multicast data |
| 17 |
$s->recv($data,1024); |
| 18 |
|
| 19 |
# Drop a multicast group |
| 20 |
$s->mcast_drop('225.0.0.1'); |
| 21 |
|
| 22 |
# Set outgoing interface to eth0 |
| 23 |
$s->mcast_if('eth0'); |
| 24 |
|
| 25 |
# Set time to live on outgoing multicast packets |
| 26 |
$s->mcast_ttl(10); |
| 27 |
|
| 28 |
# Turn off loopbacking |
| 29 |
$s->mcast_loopback(0); |
| 30 |
|
| 31 |
# Multicast a message to group 225.0.0.1 |
| 32 |
$s->mcast_send('hello world!','225.0.0.1:1200'); |
| 33 |
$s->mcast_set('225.0.0.2:1200'); |
| 34 |
$s->mcast_send('hello again!'); |
| 35 |
|
| 36 |
DESCRIPTION |
| 37 |
The IO::Socket::Multicast module subclasses IO::Socket::INET to enable |
| 38 |
you to manipulate multicast groups. With this module (and an operating |
| 39 |
system that supports multicasting), you will be able to receive incoming |
| 40 |
multicast transmissions and generate your own outgoing multicast |
| 41 |
packets. |
| 42 |
|
| 43 |
This module requires IO::Interface version 0.94 or higher. |
| 44 |
|
| 45 |
INTRODUCTION |
| 46 |
Multicasting is designed for streaming multimedia applications and for |
| 47 |
conferencing systems in which one transmitting machines needs to |
| 48 |
distribute data to a large number of clients. |
| 49 |
|
| 50 |
IP addresses in the range 224.0.0.0 and 239.255.255.255 are reserved for |
| 51 |
multicasting. These addresses do not correspond to individual machines, |
| 52 |
but to multicast groups. Messages sent to these addresses will be |
| 53 |
delivered to a potentially large number of machines that have registered |
| 54 |
their interest in receiving transmissions on these groups. They work |
| 55 |
like TV channels. A program tunes in to a multicast group to receive |
| 56 |
transmissions to it, and tunes out when it no longer wishes to receive |
| 57 |
the transmissions. |
| 58 |
|
| 59 |
To receive transmissions from a multicast group, you will use |
| 60 |
IO::Socket::INET->new() to create a UDP socket and bind it to a local |
| 61 |
network port. You will then subscribe one or more multicast groups using |
| 62 |
the mcast_add() method. Subsequent calls to the standard recv() method |
| 63 |
will now receive messages incoming messages transmitted to the |
| 64 |
subscribed groups using the selected port number. |
| 65 |
|
| 66 |
To send transmissions to a multicast group, you can use the standard |
| 67 |
send() method to send messages to the multicast group and port of your |
| 68 |
choice. The mcast_set() and mcast_send() methods are provided as |
| 69 |
convenience functions. Mcast_set() will set a default multicast |
| 70 |
destination for messages which you then send with mcast_send(). |
| 71 |
|
| 72 |
To set the number of hops (routers) that outgoing multicast messages |
| 73 |
will cross, call mcast_ttl(). To activate or deactivate the looping back |
| 74 |
of multicast messages (in which a copy of the transmitted messages is |
| 75 |
received by the local machine), call mcast_loopback(). |
| 76 |
|
| 77 |
CONSTRUCTORS |
| 78 |
$socket = IO::Socket::Multicast->new([LocalPort=>$port,...]) |
| 79 |
The new() method is the constructor for the IO::Socket::Multicast |
| 80 |
class. It takes the same arguments as IO::Socket::INET, except that |
| 81 |
the Proto argument, rather than defaulting to "tcp", will default to |
| 82 |
"udp", which is more appropriate for multicasting. |
| 83 |
|
| 84 |
To create a UDP socket suitable for sending outgoing multicast |
| 85 |
messages, call new() without arguments (or with "Proto=>'udp'"). |
| 86 |
To create a UDP socket that can also receive incoming multicast |
| 87 |
transmissions on a specific port, call new() with the LocalPort |
| 88 |
argument. |
| 89 |
|
| 90 |
If you plan to run the client and server on the same machine, you |
| 91 |
may wish to set the IO::Socket ReuseAddr argument to a true value. |
| 92 |
This allows multiple multicast sockets to bind to the same address. |
| 93 |
|
| 94 |
METHODS |
| 95 |
$success = $socket->mcast_add($multicast_address [,$interface]) |
| 96 |
The mcast_add() method will add the provided multicast address to |
| 97 |
the list of subscribed multicast groups. The address may be provided |
| 98 |
either as a dotted-quad decimal, or as a packed IP address (such as |
| 99 |
produced by the inet_aton() function). On success, the method will |
| 100 |
return a true value. |
| 101 |
|
| 102 |
The optional $interface argument can be used to specify on which |
| 103 |
network interface to listen for incoming multicast messages. If the |
| 104 |
IO::Interface module is installed, you may use the device name for |
| 105 |
the interface (e.g. "tu0"). Otherwise, you must use the IP address |
| 106 |
of the desired network interface. Either dotted quad form or packed |
| 107 |
IP address is acceptable. If no interface is specified, then the |
| 108 |
multicast group is joined on INADDR_ANY, meaning that multicast |
| 109 |
transmissions received on any of the host's network interfaces will |
| 110 |
be forwarded to the socket. |
| 111 |
|
| 112 |
Note that mcast_add() operates on the underlying interface(s) and |
| 113 |
not on the socket. If you have multiple sockets listening on a port, |
| 114 |
and you mcast_add() a group to one of those sockets, subsequently |
| 115 |
all the sockets will receive mcast messages on this group. To filter |
| 116 |
messages that can be received by a socket so that only those sent to |
| 117 |
a particular multicast address are received, pass the LocalAddr |
| 118 |
option to the socket at the time you create it: |
| 119 |
|
| 120 |
my $socket = IO::Socket::Multicast->new(LocalPort=>2000, |
| 121 |
LocalAddr=>226.1.1.2', |
| 122 |
ReuseAddr=>1); |
| 123 |
$socket->mcast_add('226.1.1.2'); |
| 124 |
|
| 125 |
By combining this technique with IO::Select, you can write |
| 126 |
applications that listen to multiple multicast groups and |
| 127 |
distinguish which group a message was addressed to by identifying |
| 128 |
which socket it was received on. |
| 129 |
|
| 130 |
$success = $socket->mcast_drop($multicast_address) |
| 131 |
This reverses the action of mcast_add(), removing the indicated |
| 132 |
multicast address from the list of subscribed groups. |
| 133 |
|
| 134 |
$loopback = $socket->mcast_loopback |
| 135 |
$previous = $socket->mcast_loopback($new) |
| 136 |
The mcast_loopback() method controls whether the socket will receive |
| 137 |
its own multicast transmissions (default yes). Called without |
| 138 |
arguments, the method returns the current state of the loopback |
| 139 |
flag. Called with a boolean argument, the method will set the |
| 140 |
loopback flag, and return its previous value. |
| 141 |
|
| 142 |
$ttl = $socket->mcast_ttl |
| 143 |
$previous = $socket->mcast_ttl($new) |
| 144 |
The mcast_ttl() method examines or sets the time to live (TTL) for |
| 145 |
outgoing multicast messages. The TTL controls the numbers of routers |
| 146 |
the packet can cross before being expired. The default TTL is 1, |
| 147 |
meaning that the message is confined to the local area network. |
| 148 |
Values between 0 and 255 are valid. |
| 149 |
|
| 150 |
Called without arguments, this method returns the socket's current |
| 151 |
TTL. Called with a value, this method sets the TTL and returns its |
| 152 |
previous value. |
| 153 |
|
| 154 |
$interface = $socket->mcast_if |
| 155 |
$previous = $socket->mcast_if($new) |
| 156 |
By default, the OS will pick the network interface to use for |
| 157 |
outgoing multicasts automatically. You can control this process by |
| 158 |
using the mcast_if() method to set the outgoing network interface |
| 159 |
explicitly. Called without arguments, returns the current interface. |
| 160 |
Called with the name of an interface, sets the outgoing interface |
| 161 |
and returns its previous value. |
| 162 |
|
| 163 |
You can use the device name for the interface (e.g. "tu0") if the |
| 164 |
IO::Interface module is present. Otherwise, you must use the |
| 165 |
interface's dotted IP address. |
| 166 |
|
| 167 |
NOTE: To set the interface used for incoming multicasts, use the |
| 168 |
mcast_add() method. |
| 169 |
|
| 170 |
$dest = $socket->mcast_dest |
| 171 |
$previous = $socket->mcast_dest($new) |
| 172 |
The mcast_dest() method is a convenience function that allows you to |
| 173 |
set the default destination group for outgoing multicasts. Called |
| 174 |
without arguments, returns the current destination as a packed |
| 175 |
binary sockaddr_in data structure. Called with a new destination |
| 176 |
address, the method sets the default destination and returns the |
| 177 |
previous one, if any. |
| 178 |
|
| 179 |
Destination addresses may be provided as packed sockaddr_in |
| 180 |
structures, or in the form "XX.XX.XX.XX:YY" where the first part is |
| 181 |
the IP address, and the second the port number. |
| 182 |
|
| 183 |
$bytes = $socket->mcast_send($data [,$dest]) |
| 184 |
Mcast_send() is a convenience function that simplifies the sending |
| 185 |
of multicast messages. $data is the message contents, and $dest is |
| 186 |
an optional destination group. You can use either the dotted IP form |
| 187 |
of the destination address and its port number, or a packed |
| 188 |
sockaddr_in structure. If the destination is not supplied, it will |
| 189 |
default to the most recent value set in mcast_dest() or a previous |
| 190 |
call to mcast_send(). |
| 191 |
|
| 192 |
The method returns the number of bytes successfully queued for |
| 193 |
delivery. |
| 194 |
|
| 195 |
As a side-effect, the method will call mcast_dest() to remember the |
| 196 |
destination address. |
| 197 |
|
| 198 |
Example: |
| 199 |
|
| 200 |
$socket->mcast_send('Hi there group members!','225.0.1.1:1900') || die; |
| 201 |
$socket->mcast_send("How's the weather?") || die; |
| 202 |
|
| 203 |
Note that you may still call IO::Socket::INET->new() with a |
| 204 |
PeerAddr, and IO::Socket::INET will perform a connect(), creating a |
| 205 |
default destination for calls to send(). |
| 206 |
|
| 207 |
EXAMPLE |
| 208 |
The following is an example of a multicast server. Every 10 seconds it |
| 209 |
transmits the current time and the list of logged-in users to the local |
| 210 |
network using multicast group 226.1.1.2, port 2000 (these are chosen |
| 211 |
arbitrarily). |
| 212 |
|
| 213 |
#!/usr/bin/perl |
| 214 |
# server |
| 215 |
use strict; |
| 216 |
use IO::Socket::Multicast; |
| 217 |
|
| 218 |
use constant DESTINATION => '226.1.1.2:2000'; |
| 219 |
my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION); |
| 220 |
|
| 221 |
while (1) { |
| 222 |
my $message = localtime; |
| 223 |
$message .= "\n" . `who`; |
| 224 |
$sock->send($message) || die "Couldn't send: $!"; |
| 225 |
} continue { |
| 226 |
sleep 10; |
| 227 |
} |
| 228 |
|
| 229 |
This is the corresponding client. It listens for transmissions on group |
| 230 |
226.1.1.2, port 2000, and echoes the messages to standard output. |
| 231 |
|
| 232 |
#!/usr/bin/perl |
| 233 |
# client |
| 234 |
|
| 235 |
use strict; |
| 236 |
use IO::Socket::Multicast; |
| 237 |
|
| 238 |
use constant GROUP => '226.1.1.2'; |
| 239 |
use constant PORT => '2000'; |
| 240 |
|
| 241 |
my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT); |
| 242 |
$sock->mcast_add(GROUP) || die "Couldn't set group: $!\n"; |
| 243 |
|
| 244 |
while (1) { |
| 245 |
my $data; |
| 246 |
next unless $sock->recv($data,1024); |
| 247 |
print $data; |
| 248 |
} |
| 249 |
|
| 250 |
EXPORT |
| 251 |
None by default. However, if you wish to call mcast_add(), mcast_drop(), |
| 252 |
mcast_if(), mcast_loopback(), mcast_ttl, mcast_dest() and mcast_send() |
| 253 |
as functions you may import them explicitly on the use line or by |
| 254 |
importing the tag ":functions". |
| 255 |
|
| 256 |
BUGS |
| 257 |
The mcast_if(), mcast_ttl() and mcast_loopback() methods will cause a |
| 258 |
crash on versions of Linux earlier than 2.2.0 because of a kernel bug in |
| 259 |
the implementation of the multicast socket options. |
| 260 |
|
| 261 |
AUTHOR |
| 262 |
Lincoln Stein, [email protected]. |
| 263 |
|
| 264 |
This module is distributed under the same terms as Perl itself. |
| 265 |
|
| 266 |
SEE ALSO |
| 267 |
perl(1), IO::Socket(3), IO::Socket::INET(3). |
| 268 |
|