Filewatcher File Search File Search
Catalog
Content Search
» » » » » libio-socket-multicast-perl_1.12-1+b2_ia64.deb » Content »
pkg://libio-socket-multicast-perl_1.12-1+b2_ia64.deb:22880/usr/share/man/man3/  info  control  downloads

libio-socket-multicast-perl - module for sending and receiving multicast messages…  more info»

IO::Socket::Multicast.3pm.gz

IO::Socket::MultiUser(Contributed Perl DocIO::Socket::Multicast(3pm)



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::Multicast->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::Multicast->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).



perl v5.14.2                 2010-04-28   IO::Socket::Multicast(3pm)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com