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