emcast: Generic multicast utility and library.
David Helder
Copyright (C) 2001 Regents of the University of Michigan
========================================================

Emcast is a multicast toolkit for distributed/peer-to-peer
applications that require multicast communication.  It includes the
program "emcast", a generic multicast utility (like netcat), and the
library "libemcast", a generic multicast library.  Emcast supports
IPv4 multicast (IM) and can easily support almost any end-host
multicast (EM) protocol.  The EM protocols supported are STAR
(centralized TCP), Banana Tree Protocol (BTP), and Internet Chat Relay
(IRC).  Emcast is pronounced "em-cast".

Libemcast is a library that provides a simple interface between the
programmer and multicast services.  The libemcast API includes the
functions join, leave, send, recv, and others.

The program "emcast" provides an interface between the user (or
programmer) and multicast.  When invoked, emcast
 joins the multicast group specified by the URL passed on the command
line.  Data written to stdin is sent to the multicast group and data
sent to the multicast group is written to stdout.  The program is
useful for scripts.

IP Multicast support is built into Emcast.  EM support is provided by
interfacing with processes using the Emcast protocol.  For example, to
use Banana Tree Protocol (BTP), Emcast launches and communicates with
the program "btp-emcast".  Emcast can use any EM protocol that
provides a process that understands the Emcast protocol.  We intend to
add support for daemons and dynamically loaded libraries in the
future.

Emcast is part of a research project at the EECS Department of the
University of Michigan. The lead developer is David Helder, a PhD
student at U of M.

Parts of Emcast are released under the GNU General Public License or
the GNU Lesser General Public License.  This means it's free, you can
share it with your friends, but it's not our fault if it breaks your
computer.  See COPYING for more information.

Emcast lives at: http://www.junglemonkey.net/emcast



install
=======

Run:

  ./configure
  make
  make install

Then, if you have perl, run:

  cd perl
  perl Makefile.PL
  make
  make install



supported emcast multicast protocols
====================================

emcast comes with the following protocols:

IP multicast			built-in
Star				centralized EM
Banana Tree Protocol (BTP)	tree-based EM [1]
IRC				static tree-based EM [2]


[1] BTP is only built if GLib (www.gtk.org) and GNet
(www.gnetlibrary.org) are installed.

[2] IRC is only built if perl and the Net::IRC perl module are
installed.  You must then install the perl modules in the perl
directory.



applications
============

These applications use Emcast:

Jungle Monkey
Distributed file sharing application
http://www.junglemonkey.net
Uses the BTP module via libbtp

IDMaps
Internet Distance Measurement
http://www.idmaps.com/
Uses the BTP module via libemcast



emcast (the program)
====================

emcast is a simple, command-line utility that joins a multicast group,
sends data to the group read from stdin, and writes data received from
the group to stdout.  emcast can easily be used in scripts (use
libemcast for compiled multicast programs).  It's also helpful for
debugging handlers and multicast applications.

Usage: ./emcast [OPTION]... <URL>
	-b <size>   		buffer size
	-h          		display help
	-l <0 or 1> 		turn loopback on or off
	-o<name> <value>  	set option <name> to <value>
	-O<name> <value>  	set option <name> to <value> before joining
	-q	    		quiet mode (no input/output)
	-t <ttl>    		time-to-live

Example:

  emcast 234.43.13.42:8765
    -> emcast joins a IPv4 multicast group

  emcast "btp://junglemonkey.net/Monkey Central"
    -> emcast joins "Monkey Central" on junglemonkey.net using BTP

  emcast "irc://emcast@irc.openprojects.net/mesh"
    -> emcast joins #mesh on irc.openprojects.net with nickname emcast

IP multicast is used when the URL is in the form <address>:<port>.



emcast (the library)
====================

To use Emcast in a program, use libemcast.  See doc/libemcast-apt.txt
for API details.  It is easy to translate IP multicast calls to
libemcast calls.

Example:

  Emcast* emcast;
  int fd, loopback, len;
  char buf[1024];
  
  /* Join my group.  emcast_join returns a descriptor. */
  fd = emcast_join (&emcast, "btp://junglemonkey.net/Monkey Central");
  
  /* Turn on loopback */
  loopback = 1;
  emcast_setopt (emcast, "loopback", &loopback, sizeof(loopback));
  
  while (1)
  {
    /* Wait for packet - select on descriptor fd */
    /* ... */
  
    /* Read packet */
    len = emcast_recv (emcast, buf, sizeof(buf));
  } 


To use a new EM protocol with emcast, you must write an Emcast handler
for it.  An Emcast handler is a program that speaks the Emcast
protocol.  See doc/emcast-handler.txt for information on how to write
an Emcast handler.  See doc/emcast-protocol.txt for details on the
Emcast protocol.