IO-Socket-Multicast6-0.03/0000755000175000017500000000000011276572317013355 5ustar njhnjhIO-Socket-Multicast6-0.03/META.yml0000444000175000017500000000134111276572317014623 0ustar njhnjh--- name: IO-Socket-Multicast6 version: 0.03 author: - 'Based on L by Lincoln Stein, lstein@cshl.org.' - 'IO::Socket::Multicast6 by Nicholas J Humfrey, Enjh@cpan.orgE.' abstract: Send and receive IPv4 and IPv6 multicast messages license: perl resources: license: http://dev.perl.org/licenses/ requires: IO::Interface: 1.01 IO::Socket::INET6: 2.51 Socket: 0 Socket6: 0.19 Socket::Multicast6: 0.01 Test::More: 0 perl: 5.6.1 build_requires: Module::Build: 0.20 provides: IO::Socket::Multicast6: file: lib/IO/Socket/Multicast6.pm version: 0.03 generated_by: Module::Build version 0.280801 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.2.html version: 1.2 IO-Socket-Multicast6-0.03/t/0000755000175000017500000000000011276572317013620 5ustar njhnjhIO-Socket-Multicast6-0.03/t/10loopback.t0000444000175000017500000000165411276572317015744 0ustar njhnjh# # Tests the mcast_loopback() method for both IPv4 and IPv6 # use strict; use Test::More tests => 9; # load IO::Socket::Multicast6 BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( Domain => AF_INET ); ok( $sock4, "Create IPv4 multicast socket" ); ok( defined $sock4->mcast_loopback(), "Get loopback state of IPv4 socket" ); ok( defined $sock4->mcast_loopback( 1 ), "Set loopback state of IPv4 socket" ); ok( $sock4->mcast_loopback() == 1, "Verify loopback state of IPv4 socket" ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( Domain => AF_INET6 ); ok( $sock6, "Create IPv6 multicast socket" ); ok( defined $sock6->mcast_loopback(), "Get loopback state of IPv6 socket" ); ok( defined $sock6->mcast_loopback( 1 ), "Set loopback state of IPv6 socket" ); ok( $sock6->mcast_loopback() == 1, "Verify loopback state of IPv6 socket" ); IO-Socket-Multicast6-0.03/t/35mcastsend.t0000444000175000017500000000303311276572317016133 0ustar njhnjh# # Try and send some multicast packets on IPv4 and IPv6, multicast API style # use strict; use Socket6 qw/ inet_pton pack_sockaddr_in6/; use Socket qw/ pack_sockaddr_in /; use Test::More tests => 11; # load IO::Socket::Multicast6 BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( Domain => AF_INET ); ok( $sock4, "Create IPv4 multicast socket" ); $sock4->mcast_dest( '239.255.30.29:2000' ); ok( defined $sock4->mcast_dest(), "Combined IPv4 destination address and port" ); $sock4->mcast_dest( '239.255.30.29', 2000 ); ok( defined $sock4->mcast_dest(), "Separate IPv4 destination address and port" ); $sock4->mcast_dest( pack_sockaddr_in(2000,inet_pton(AF_INET, '239.255.30.29')) ); ok( defined $sock4->mcast_dest(), "Packed IPv4 destination address and port" ); is($sock4->mcast_send( 'Hello World!' ), 12, "Sent 12 bytes on IPv4 socket." ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( Domain => AF_INET6 ); ok( $sock6, "Create IPv6 multicast socket" ); $sock6->mcast_dest( '[ff15::5042]:2000' ); ok( defined $sock6->mcast_dest(), "Combined IPv6 destination address and port" ); $sock6->mcast_dest( 'ff15::5042', 2000 ); ok( defined $sock6->mcast_dest(), "Separate IPv6 destination address and port" ); $sock6->mcast_dest( pack_sockaddr_in6(2000,inet_pton(AF_INET6, 'ff15::5042')) ); ok( defined $sock6->mcast_dest(), "Packed IPv6 destination address and port" ); is($sock6->mcast_send( 'Hello World!' ), 12, "Sent 12 bytes on IPv6 socket." ); IO-Socket-Multicast6-0.03/t/20add-drop.t0000444000175000017500000000135111276572317015637 0ustar njhnjh# # Try join/leaving IPv4 and IPv6 muticast groups # use strict; use Test::More tests => 7; # load IO::Socket::Multicast6 BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( Domain => AF_INET ); ok( $sock4, "Create IPv4 multicast socket" ); is( $sock4->mcast_add('239.255.1.1'), 1, "Join IPv4 multicast group" ); is( $sock4->mcast_drop('239.255.1.1'), 1, "Drop IPv4 multicast group" ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( Domain => AF_INET6 ); ok( $sock6, "Create IPv6 multicast socket" ); is( $sock6->mcast_add('FF11::11'), 1, "Join IPv6 multicast group" ); is( $sock6->mcast_drop('FF11::11'), 1, "Drop IPv6 multicast group" ); IO-Socket-Multicast6-0.03/t/00use.t0000444000175000017500000000052011276572317014734 0ustar njhnjhuse strict; use Test::More tests => 3; # Check that the module loads ok BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Now try creating a new IO::Socket::Multicast6 socket my $sock = new IO::Socket::Multicast6(); ok( $sock, "Creating IO::Socket::Multicast6 object" ); # Close the socket $sock->close(); pass( "Closing socket" ); IO-Socket-Multicast6-0.03/t/30send.t0000444000175000017500000000141311276572317015076 0ustar njhnjh# # Try and send some multicast packets on IPv4 and IPv6 # use strict; use Test::More tests => 5; # load IO::Socket::Multicast6 BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( PeerAddr => '239.255.30.29', PeerPort => 2000, Domain => AF_INET, ReuseAddr=>1); ok( $sock4, "Create IPv4 multicast socket" ); is($sock4->send( 'Hello World!'), 12, "Sent 12 bytes on IPv4 socket." ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( PeerAddr => 'ff15::5042', PeerPort => 2000, Domain => AF_INET6, ReuseAddr=>1); ok( $sock6, "Create IPv6 multicast socket" ); is($sock6->send( 'Hello World!'), 12, "Sent 12 bytes on IPv6 socket." ); IO-Socket-Multicast6-0.03/t/05interface.t0000444000175000017500000000250311276572317016110 0ustar njhnjh# # Try attaching to a multicast interface # use strict; use Test::More tests => 10; # load IO::Socket::Multicast6 and IO::Interface BEGIN { use_ok( 'IO::Interface::Simple' ); use_ok( 'IO::Socket::Multicast6' ); } # Find first multicast enabled interface my $iface = undef; my @interfaces = IO::Interface::Simple->interfaces; foreach my $if (@interfaces) { next unless ($if->is_running); next unless ($if->is_multicast); # Found multicast enabled interface $iface = $if->name(); last; } unless (defined $iface) { die( "Failed to find multicast enabled interface." ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( Domain => AF_INET ); ok( $sock4, "Create IPv4 multicast socket" ); ok( defined $sock4->mcast_if(), "Get outgoing interface of IPv4 socket" ); ok( defined $sock4->mcast_if($iface), "Set outgoing interface of IPv4 socket" ); ok( $sock4->mcast_if() eq $iface, "Verify outgoing interface of IPv4 socket" ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( Domain => AF_INET6 ); ok( $sock6, "Create IPv6 multicast socket" ); ok( defined $sock6->mcast_if(), "Get outgoing interface of IPv6 socket" ); ok( defined $sock6->mcast_if($iface), "Set outgoing interface of IPv6 socket" ); ok( $sock6->mcast_if() eq $iface, "Verify outgoing interface of IPv6 socket" ); IO-Socket-Multicast6-0.03/t/10ttl.t0000444000175000017500000000145311276572317014752 0ustar njhnjh# # Tests the mcast_ttl() method for both IPv4 and IPv6 # use Test::More tests => 9; use strict; # load IO::Socket::Multicast6 BEGIN { use_ok( 'IO::Socket::Multicast6' ); } # Create an IPv4 multicast socket my $sock4 = new IO::Socket::Multicast6( Domain => AF_INET ); ok( $sock4, "Create IPv4 multicast socket" ); ok( $sock4->mcast_ttl(), "Get TTL value of IPv4 socket" ); ok( $sock4->mcast_ttl( 6 ), "Set TTL value of IPv4 socket" ); ok( $sock4->mcast_ttl() == 6, "Verify TTL value of IPv4 socket" ); # Create an IPv6 multicast socket my $sock6 = new IO::Socket::Multicast6( Domain => AF_INET6 ); ok( $sock6 ); ok( $sock6->mcast_ttl(), "Get TTL value of IPv6 socket" ); ok( $sock6->mcast_ttl( 6 ), "Set TTL value of IPv6 socket" ); ok( $sock6->mcast_ttl() == 6, "Verify TTL value of IPv6 socket" ); IO-Socket-Multicast6-0.03/Changes0000444000175000017500000000074311276572317014652 0ustar njhnjhRevision history for Perl extension IO::Socket::Multicast6 0.03 Wed Nov 11 17:06:22 GMT 2009 - Minor changes to documentation - Changed to import all symbols from Socket and Socket6 - Added missing files to the manifest 0.02 Tue Sep 19 14:25:15 BST 2006 - added support for mcast_send and mcast_dest - added send tests - Resuse_Addr is now enabled by default 0.01 Tue Aug 15 15:40:30 BST 2006 - original version based on IO::Socket::Multicast v1.04 IO-Socket-Multicast6-0.03/README0000444000175000017500000003164711276572317014246 0ustar njhnjhNAME IO::Socket::Multicast6 - Send and receive IPv4 and IPv6 multicast messages SYNOPSIS use IO::Socket::Multicast6; # create a new IPv6 UDP socket ready to read datagrams on port 1100 my $s = IO::Socket::Multicast6->new( Domain=>AF_INET6, LocalPort=>1100); # Add an IPv6 multicast group $s->mcast_add('FF15::0561'); # now receive some multicast data $s->recv($data,1024); # Drop a multicast group $s->mcast_drop('FF15::0561'); # create a new IPv4 UDP socket ready to send datagrams to port 1100 my $s = IO::Socket::Multicast6->new( Domain=>AF_INET, PeerDest=>'225.0.0.1', PeerPort=>1100); # 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 $s->send( 'hello world!' ); DESCRIPTION The IO::Socket::Multicast6 module subclasses IO::Socket::INET6 to enable you to manipulate multicast groups. With this module you will be able to receive incoming multicast transmissions and generate your own outgoing multicast packets. This module uses the same API as IO::Socket::Multicast, but with added support for IPv6 (IPv4 is still supported). Unlike IO::Socket::Multicast, this is a pure-perl module. DEPENDENCIES This module depends on a number of other modules: Socket6 version 0.19 or higher. IO::Socket::INET6 version 2.51 or higher. IO::Interface version 1.01 or higher. Socket::Multicast6 0.01 or higher. Your operating system must have IPv6 and Multicast support. 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. IPv4 addresses in the range 224.0.0.0 and 239.255.255.255 are reserved for multicasting. IPv6 multicast addresses start with the prefix FF. 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. 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::Multicast6->new([LocalPort=>$port,...]) The new() method is the constructor for the IO::Socket::Multicast6 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 no 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::Multicast6->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_add_source($multicast_add, $source_addr [,$interface]) Same as mcast_add() but for Source Specific Multicast (SSM). $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($address [, $port]) 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/sockaddr_in6 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/sockaddr_in6 structures, or address and port as strings. For IPv4 the address can be supplied in the form "XX.XX.XX.XX:YY" where the first part is the IPv4 address, and the second the port number. For IPv6 the address can be supplied in the form "[FFXX:XXXX::XXXX]:YY" where the first part is the IPv6 address, and the second the port number. Alternatively the port can be supplied as an additional parameter, separate to the address. $bytes = $socket->mcast_send($data [,$address [,$port]]) 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/sockaddr_in6 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::INET6->new() with a PeerAddr, and IO::Socket::INET6 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 FF15::0561, port 2000 (these are chosen arbitrarily, the FF15:: is a Transient, Site Local prefix). #!/usr/bin/perl # server (transmitter) use strict; use IO::Socket::Multicast6; use constant GROUP => 'FF15::0561'; use constant PORT => '2000'; my $sock = IO::Socket::Multicast6->new( Proto=>'udp', Domain=>AF_INET6, PeerAddr=>GROUP, PeerPort=>PORT); while (1) { my $message = localtime(); $sock->send($message) || die "Couldn't send: $!"; } continue { sleep 4; } This is the corresponding client. It listens for transmissions on group FF15::0561, port 2000, and echoes the messages to standard output. #!/usr/bin/perl # client (receiver) use strict; use IO::Socket::Multicast6; use constant GROUP => 'FF15::0561'; use constant PORT => '2000'; my $sock = IO::Socket::Multicast6->new( Proto=>'udp', Domain=>AF_INET6, LocalAddr=>GROUP, LocalPort=>PORT); $sock->mcast_add(GROUP) || die "Couldn't set group: $!\n"; while (1) { my $data; next unless $sock->recv($data,1024); print "$data\n"; } 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. SEE ALSO perl(1), IO::Socket(3), Socket::Multicast6(3), IO::Socket::INET6(3). AUTHOR Based on IO::Socket::Multicast by Lincoln Stein, lstein@cshl.org. IO::Socket::Multicast6 by Nicholas J Humfrey, . COPYRIGHT AND LICENSE Copyright (C) 2006-2009 Nicholas J Humfrey Copyright (C) 2000-2005 Lincoln Stein This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available. IO-Socket-Multicast6-0.03/Build.PL0000444000175000017500000000131211276572317014644 0ustar njhnjhuse Module::Build; my $class = Module::Build->subclass(code => <<'EOF'); sub ACTION_dist { my $self = shift; eval { use Pod::Text; print "Creating the README file.\n"; my $parser = Pod::Text->new(); $parser->parse_from_file('lib/IO/Socket/Multicast6.pm', 'README'); }; $self->SUPER::ACTION_dist(@_); } EOF my $build = $class->new ( module_name => 'IO::Socket::Multicast6', license => 'perl', build_requires => { 'Module::Build' => '0.20' }, requires => { 'perl' => '5.6.1', 'Socket' => 0, 'Test::More' => 0, 'Socket6' => 0.19, 'IO::Interface' => 1.01, 'Socket::Multicast6' => '0.01', 'IO::Socket::INET6' => '2.51', }, ); $build->create_build_script; IO-Socket-Multicast6-0.03/MANIFEST0000444000175000017500000000042111276572317014501 0ustar njhnjhBuild.PL Changes examples/multicast-recieve.pl examples/multicast-send.pl examples/unicast-recieve.pl examples/unicast-send.pl lib/IO/Socket/Multicast6.pm MANIFEST META.yml README t/00use.t t/05interface.t t/10loopback.t t/10ttl.t t/20add-drop.t t/30send.t t/35mcastsend.t IO-Socket-Multicast6-0.03/examples/0000755000175000017500000000000011276572317015173 5ustar njhnjhIO-Socket-Multicast6-0.03/examples/multicast-recieve.pl0000555000175000017500000000076111276572317021162 0ustar njhnjh#!/usr/bin/perl use strict; use lib '../blib/lib','../blib/arch'; use IO::Socket::Multicast6; #use constant GROUP => 'ff15::9023'; use constant GROUP => '239.255.30.29'; use constant PORT => '2000'; my $sock = new IO::Socket::Multicast6( LocalAddr=>GROUP, LocalPort=>PORT, ReuseAddr=>1) || die "Failed to create multicast socket: $!"; $sock->mcast_add(GROUP) || die "Couldn't join group: $!\n"; while (1) { my $data; next unless $sock->recv($data,1024); print "$data\n"; } IO-Socket-Multicast6-0.03/examples/multicast-send.pl0000555000175000017500000000120211276572317020460 0ustar njhnjh#!/usr/bin/perl use strict; use lib '../blib/lib','../blib/arch'; use IO::Socket::Multicast6; #use constant GROUP => 'ff15::9023'; use constant GROUP => '239.255.30.29'; use constant PORT => '2000'; my $sock = new IO::Socket::Multicast6( LocalAddr=>GROUP, LocalPort=>PORT, ) || die "Failed to create multicast socket: $!"; $sock->mcast_ttl(5) || die "Failed to set TTL: $!"; $sock->mcast_loopback(1) || die "Failed to enable loopback: $!"; $sock->mcast_dest(GROUP, PORT); while (1) { my $message = localtime(); $sock->mcast_send($message) || die "Couldn't send: $!"; print "Sent: $message\n"; } continue { sleep 4; } IO-Socket-Multicast6-0.03/examples/unicast-send.pl0000555000175000017500000000063711276572317020134 0ustar njhnjh#!/usr/bin/perl use strict; use lib '../blib/lib','../blib/arch'; use IO::Socket::Multicast6; use constant DESTINATION => '127.0.0.1:2000'; my $sock = new IO::Socket::Multicast6( Domain=>AF_INET, ReuseAddr=>1); print "Socket's domain: ".$sock->sockdomain()."\n"; while (1) { my $message = localtime(); $sock->mcast_send($message,DESTINATION) || die "Couldn't send: $!"; } continue { sleep 5; } IO-Socket-Multicast6-0.03/examples/unicast-recieve.pl0000555000175000017500000000052611276572317020622 0ustar njhnjh#!/usr/bin/perl use strict; use lib '../blib/lib','../blib/arch'; use IO::Socket::Multicast6; use constant PORT => '2000'; my $sock = new IO::Socket::Multicast6( # Domain=>AF_INET, LocalPort=>PORT, ReuseAddr=>1); while (1) { my $data; next unless $sock->recv($data,1024); print "Got ".length($data)." bytes: $data\n"; } IO-Socket-Multicast6-0.03/lib/0000755000175000017500000000000011276572317014123 5ustar njhnjhIO-Socket-Multicast6-0.03/lib/IO/0000755000175000017500000000000011276572317014432 5ustar njhnjhIO-Socket-Multicast6-0.03/lib/IO/Socket/0000755000175000017500000000000011276572317015662 5ustar njhnjhIO-Socket-Multicast6-0.03/lib/IO/Socket/Multicast6.pm0000444000175000017500000005030411276572317020253 0ustar njhnjhpackage IO::Socket::Multicast6; use strict; use vars qw(@ISA $VERSION); use IO::Socket::INET6; use IO::Interface::Simple; use Socket::Multicast6 qw/ :all /; use Socket; use Socket6; use Carp 'croak'; @ISA = qw(IO::Socket::INET6); $VERSION = '0.03'; # Regular expressions to match IP addresses my $IPv4 = '\d+\.\d+\.\d+\.\d+'; my $IPv6 = '[\da-fA-F:]+'; sub new { my $class = shift; unshift @_,(Proto => 'udp') unless @_; $class->SUPER::new(@_); } sub configure { my($self,$arg) = @_; $arg->{Proto} ||= 'udp'; $arg->{ReuseAddr} ||= 1; $self->SUPER::configure($arg); } sub mcast_add { my $sock = shift; my $group = shift || croak 'usage: $sock->mcast_add($mcast_addr [,$interface])'; my $interface = shift; if ($sock->sockdomain() == AF_INET) { my $if_addr = _get_if_ipv4addr($interface); my $ip_mreq = pack_ip_mreq( inet_pton( AF_INET, $group ), inet_pton( AF_INET, $if_addr ) ); setsockopt($sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, $ip_mreq ) or croak "Could not set IP_ADD_MEMBERSHIP socket option: $!"; } elsif ($sock->sockdomain() == AF_INET6) { my $if_index = _get_if_index($interface); my $ipv6_mreq = pack_ipv6_mreq( inet_pton( AF_INET6, $group ), $if_index ); setsockopt($sock, IPPROTO_IPV6, IPV6_JOIN_GROUP, $ipv6_mreq ) or croak "Could not set IPV6_JOIN_GROUP socket option: $!"; } else { croak("mcast_add failed, unsupported socket family." ); } # Success return 1; } sub mcast_add_source { my $sock = shift; my $group = shift || croak 'usage: $sock->mcast_add_source($mcast_addr, $source_addr [,$interface])'; my $source = shift || croak 'usage: $sock->mcast_add_source($mcast_addr, $source_addr [,$interface])'; my $interface = shift; if ($sock->sockdomain() == AF_INET) { my $if_addr = _get_if_ipv4addr($interface); my $ip_mreq = pack_ip_mreq_source( inet_pton( AF_INET, $group ), inet_pton( AF_INET, $source ), inet_pton( AF_INET, $if_addr ) ); setsockopt($sock, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, $ip_mreq ) or croak "Could not set IP_ADD_SOURCE_MEMBERSHIP socket option: $!"; } elsif ($sock->sockdomain() == AF_INET6) { croak("mcast_add_source failed, IPv6 is currently unsupported." ); } else { croak("mcast_add_source failed, unsupported socket family." ); } # Success return 1; } sub mcast_drop { my $sock = shift; my $group = shift || croak 'usage: $sock->mcast_drop($mcast_addr [,$interface])'; my $interface = shift; if ($sock->sockdomain() == AF_INET) { my $if_addr = _get_if_ipv4addr($interface); my $ip_mreq = pack_ip_mreq( inet_pton( AF_INET, $group ), inet_pton( AF_INET, $if_addr ) ); setsockopt($sock, IPPROTO_IP, IP_DROP_MEMBERSHIP, $ip_mreq ) or croak "Could not set IP_ADD_MEMBERSHIP socket option: $!"; } elsif ($sock->sockdomain() == AF_INET6) { my $if_index = _get_if_index($interface); my $ipv6_mreq = pack_ipv6_mreq( inet_pton( AF_INET6, $group ), $if_index ); setsockopt($sock, IPPROTO_IPV6, IPV6_LEAVE_GROUP, $ipv6_mreq ) or croak "Could not set IPV6_LEAVE_GROUP socket option: $!"; } else { croak("mcast_add failed, unsupported socket family." ); } # Success return 1; } sub mcast_ttl { my $sock = shift; my $prev = undef; if ($sock->sockdomain() == AF_INET) { my $packed = getsockopt($sock, IPPROTO_IP, IP_MULTICAST_TTL) or croak "Could not get IP_MULTICAST_TTL socket option: $!"; $prev=unpack("I", $packed); if (my $ttl = shift) { setsockopt($sock, IPPROTO_IP, IP_MULTICAST_TTL, pack("I", $ttl ) ) or croak "Could not set IP_MULTICAST_TTL socket option: $!"; } } elsif ($sock->sockdomain() == AF_INET6) { my $packed = getsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_HOPS) or croak "Could not get IPV6_MULTICAST_HOPS socket option: $!"; $prev=unpack("I", $packed); if (my $ttl = shift) { setsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, pack("I", $ttl ) ) or croak "Could not set IPV6_MULTICAST_HOPS socket option: $!"; } } else { croak("mcast_ttl failed, unsupported socket family." ); } return $prev; } sub mcast_loopback { my $sock = shift; my $prev = undef; if ($sock->sockdomain() == AF_INET) { my $packed = getsockopt($sock, IPPROTO_IP, IP_MULTICAST_LOOP) or croak "Could not get IP_MULTICAST_LOOP socket option: $!"; $prev=unpack("I", $packed); if (my $loopback = shift) { setsockopt($sock, IPPROTO_IP, IP_MULTICAST_LOOP, pack("I", $loopback ) ) or croak "Could not set IP_MULTICAST_LOOP socket option: $!"; } } elsif ($sock->sockdomain() == AF_INET6) { my $packed = getsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_LOOP) or croak "Could not get IPV6_MULTICAST_LOOP socket option: $!"; $prev=unpack("I", $packed); if (my $loopback = shift) { setsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, pack("I", $loopback ) ) or croak "Could not set IPV6_MULTICAST_LOOP socket option: $!"; } } else { croak("mcast_loopback failed, unsupported socket family." ); } return $prev; } sub mcast_if { my $sock = shift; my $prev = undef; if ($sock->sockdomain() == AF_INET) { my $packed = getsockopt($sock, IPPROTO_IP, IP_MULTICAST_IF) or croak "Could not get IP_MULTICAST_IF socket option: $!"; $prev=$sock->addr_to_interface( inet_ntop( AF_INET, $packed ) ); if (my $interface = shift) { my $if_addr = _get_if_ipv4addr($interface); setsockopt($sock, IPPROTO_IP, IP_MULTICAST_IF, inet_pton( AF_INET, $if_addr ) ) or croak "Could not set IP_MULTICAST_IF socket option: $!"; } } elsif ($sock->sockdomain() == AF_INET6) { my $packed = getsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_IF) or croak "Could not get IPV6_MULTICAST_IF socket option: $!"; $prev = unpack("I", $packed); if ($prev==0) { $prev='any'; } else { $prev = $sock->if_indextoname($prev); } if (my $interface = shift) { my $if_index = _get_if_index($interface); setsockopt($sock, IPPROTO_IPV6, IPV6_MULTICAST_IF, pack("I", $if_index ) ) or croak "Could not set IPV6_MULTICAST_IF socket option: $!"; } } else { croak("mcast_if failed, unsupported socket family." ); } return $prev; } sub mcast_dest { my $sock = shift; my ($addr, $port) = @_; my $prev = ${*$sock}{'io_socket_mcast_dest'}; if (defined $addr) { if ($sock->sockdomain() == AF_INET) { if (!defined $port and $addr =~ /^($IPv4):(\d+)$/) { $addr = $1; $port = $2; } $addr = pack_sockaddr_in($port,inet_pton(AF_INET, $addr)) if (defined $port); croak "Invalid destination address" if (!defined $addr or length($addr)==0); croak "Destination isn't an IPv4 address" unless (sockaddr_family($addr)==AF_INET); } elsif ($sock->sockdomain() == AF_INET6) { if (!defined $port and $addr =~ /^\[($IPv6)\]:(\d+)$/) { $addr = $1; $port = $2; } $addr = pack_sockaddr_in6($port,inet_pton(AF_INET6, $addr)) if (defined $port); croak "Invalid destination address" if (!defined $addr or length($addr)==0); croak "Destination isn't an IPv6 address" unless (sockaddr_family($addr)==AF_INET6); } else { croak("mcast_dest failed, unsupported socket family." ); } ${*$sock}{'io_socket_mcast_dest'} = $addr; } return $prev; } sub mcast_send { my $sock = shift; my $data = shift || croak 'usage: $sock->mcast_send($data [,$address[,$port]])'; $sock->mcast_dest(@_) if @_; my $dest = $sock->mcast_dest || croak "no destination specified with mcast_send() or mcast_dest()"; return send($sock,$data,0,$dest); } ## Returns the IPv4 address of an interface # sub _get_if_ipv4addr { my ($interface) = @_; return '0.0.0.0' unless (defined $interface); return '0.0.0.0' if ($interface eq 'any'); return $interface if ($interface =~ /^$IPv4$/); my $if = new IO::Interface::Simple( $interface ); croak "Unknown interface $interface" unless (defined $if); croak "Interface '$interface' is not multicast capable" unless ($if->is_multicast()); my $address = $if->address(); croak "Interface '$interface' does not have an IPv4 address" unless (defined $address); return $address; } ## Returns the index of an interface # sub _get_if_index { my ($interface) = @_; return 0 unless defined $interface; return $interface if ($interface =~ /^\d+$/); return 0 if ($interface =~ /^any$/i); my $if = new IO::Interface::Simple( $interface ); croak "Unknown interface $interface" unless (defined $if); croak "Interface '$interface' is not multicast capable" unless ($if->is_multicast()); my $index = $if->index(); croak "Can't get index of interface '$interface'." unless (defined $index); return $index; } 1; __END__ =head1 NAME IO::Socket::Multicast6 - Send and receive IPv4 and IPv6 multicast messages =head1 SYNOPSIS use IO::Socket::Multicast6; # create a new IPv6 UDP socket ready to read datagrams on port 1100 my $s = IO::Socket::Multicast6->new( Domain=>AF_INET6, LocalPort=>1100); # Add an IPv6 multicast group $s->mcast_add('FF15::0561'); # now receive some multicast data $s->recv($data,1024); # Drop a multicast group $s->mcast_drop('FF15::0561'); # create a new IPv4 UDP socket ready to send datagrams to port 1100 my $s = IO::Socket::Multicast6->new( Domain=>AF_INET, PeerDest=>'225.0.0.1', PeerPort=>1100); # 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 $s->send( 'hello world!' ); =head1 DESCRIPTION The IO::Socket::Multicast6 module subclasses IO::Socket::INET6 to enable you to manipulate multicast groups. With this module you will be able to receive incoming multicast transmissions and generate your own outgoing multicast packets. This module uses the same API as IO::Socket::Multicast, but with added support for IPv6 (IPv4 is still supported). Unlike IO::Socket::Multicast, this is a pure-perl module. =head2 DEPENDENCIES This module depends on a number of other modules: Socket6 version 0.19 or higher. IO::Socket::INET6 version 2.51 or higher. IO::Interface version 1.01 or higher. Socket::Multicast6 0.01 or higher. Your operating system must have IPv6 and Multicast support. =head2 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. IPv4 addresses in the range 224.0.0.0 and 239.255.255.255 are reserved for multicasting. IPv6 multicast addresses start with the prefix FF. 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 B 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 B a multicast group, you can use the standard send() method to send messages to the multicast group and port of your choice. 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(). =head2 CONSTRUCTORS =over 4 =item $socket = IO::Socket::Multicast6->new([LocalPort=>$port,...]) The new() method is the constructor for the IO::Socket::Multicast6 class. It takes the same arguments as IO::Socket::INET, except that the B 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 no arguments (or with C'udp'>). To create a UDP socket that can also receive incoming multicast transmissions on a specific port, call new() with the B argument. If you plan to run the client and server on the same machine, you may wish to set the IO::Socket B argument to a true value. This allows multiple multicast sockets to bind to the same address. =back =head2 METHODS =over 4 =item $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 B 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 B 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 B option to the socket at the time you create it: my $socket = IO::Socket::Multicast6->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. =item $success = $socket->mcast_add_source($multicast_add, $source_addr [,$interface]) Same as mcast_add() but for Source Specific Multicast (SSM). =item $success = $socket->mcast_drop($multicast_address) This reverses the action of mcast_add(), removing the indicated multicast address from the list of subscribed groups. =item $loopback = $socket->mcast_loopback =item $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. =item $ttl = $socket->mcast_ttl =item $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. =item $interface = $socket->mcast_if =item $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. B: To set the interface used for B multicasts, use the mcast_add() method. =item $dest = $socket->mcast_dest =item $previous = $socket->mcast_dest($address [, $port]) 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/sockaddr_in6 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/sockaddr_in6 structures, or address and port as strings. For IPv4 the address can be supplied in the form "XX.XX.XX.XX:YY" where the first part is the IPv4 address, and the second the port number. For IPv6 the address can be supplied in the form "[FFXX:XXXX::XXXX]:YY" where the first part is the IPv6 address, and the second the port number. Alternatively the port can be supplied as an additional parameter, separate to the address. =item $bytes = $socket->mcast_send($data [,$address [,$port]]) mcast_send() is a convenience function that simplifies the sending of multicast messages. C<$data> is the message contents, and C<$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/sockaddr_in6 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::INET6->new() with a B, and IO::Socket::INET6 will perform a connect(), creating a default destination for calls to send(). =back =head1 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 FF15::0561, port 2000 (these are chosen arbitrarily, the FF15:: is a Transient, Site Local prefix). #!/usr/bin/perl # server (transmitter) use strict; use IO::Socket::Multicast6; use constant GROUP => 'FF15::0561'; use constant PORT => '2000'; my $sock = IO::Socket::Multicast6->new( Proto=>'udp', Domain=>AF_INET6, PeerAddr=>GROUP, PeerPort=>PORT); while (1) { my $message = localtime(); $sock->send($message) || die "Couldn't send: $!"; } continue { sleep 4; } This is the corresponding client. It listens for transmissions on group FF15::0561, port 2000, and echoes the messages to standard output. #!/usr/bin/perl # client (receiver) use strict; use IO::Socket::Multicast6; use constant GROUP => 'FF15::0561'; use constant PORT => '2000'; my $sock = IO::Socket::Multicast6->new( Proto=>'udp', Domain=>AF_INET6, LocalAddr=>GROUP, LocalPort=>PORT); $sock->mcast_add(GROUP) || die "Couldn't set group: $!\n"; while (1) { my $data; next unless $sock->recv($data,1024); print "$data\n"; } =head2 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. =head1 SEE ALSO L perl(1), IO::Socket(3), Socket::Multicast6(3), IO::Socket::INET6(3). =head1 AUTHOR Based on L by Lincoln Stein, lstein@cshl.org. IO::Socket::Multicast6 by Nicholas J Humfrey, Enjh@cpan.orgE. =head1 COPYRIGHT AND LICENSE Copyright (C) 2006-2009 Nicholas J Humfrey Copyright (C) 2000-2005 Lincoln Stein This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available. =cut