Debian Codegraph @

README

raw
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