	Multicast extensions for the WATTCP TCP/IP libraries
        ----------------------------------------------------

Introduction
------------
	IP Multicasting is a mechanism to send and receive data from
a group of hosts rather than via the more traditional one on one
interaction. This technology is being heavily used for experimentation
into Audio/Video Conferencing over IP, but has the potential to be
used in a much more far-reaching manner. In fact, one school of
thought says that multicasting (1->n) is the general case, and that
unicasts (1->1) are simply a special case.

	This package contains the pieces necessary to extend the
WATTCP libraries to support IP multicasting as defined by RFC-1112[1]
(Deering). Three new user-level routines have been created to achieve
this goal. The routines join_mcast_group and leave_mcast_group allow a
process to join and leave a specified multicast group, and udp_SetTTL
allows the outgoing ttl on udp packets to be set. Additionally, there
are two trivial example/test programs. Lister is a simple program that
watches a specified address/port pair and decodes vat[2] style control
packets, thus producing a continuous listing of the IDs of the
participants. Blather is the flip side of lister. It produces a vat
style control packet and sends it to the specified address and port,
thus adding a new participant to your vat display.


Installation
------------

	The installation of this package consists of three basic
steps. The package must first be unzipped, the source files then need
to be patched, and finally everything needs to be rebuilt.
	Before you begin, you will need to have the WATTCP source
distribution installed, built, and working. WATTCP is available
from ftp-ns.rutgers.edu in /pub/msdos/wattcp. The September 30, 1993
distribution was used as a basis for these extensions. Additionally, a
connection to the MBone[3], the Internet Multicast Backbone, is a
great advantage and the default operation of the example programs
assumes that it is present.
	
1. In the same directory that you unzipped the WATTCP distribution,
   unzip the mcast.zip file using version 2.04c or greater of
   pkunzip. Make sure that the "-d" flag is specified so
   that the files end up in the proper subdirectories rather than all
   being dumped at the top level. This will create the following files:

	mcast.txt	This file
	mcast.dif	The patch file
	apps\lister.c	The receive example
	apps\blather.c	The send example
	src\pcigmp.c	code to support IGMP
	src\ipmulti.c	generic additional multicast source

2. You now need to patch the source files to add the extensions. To do
   this, you will need the "patch" program by Larry Wall. It can be found
   on wuarchive.wustl.edu in /mirrors/msdos/filutl as patch12.zip. Now,
   again in that same top level directory, type "patch -p0 < mcast.dif".
   There should be lots of "Hunk Succeeded" messages, and all your code 
   will be patched.



3. The final step is to rebuild the entire set of libraries and example
   applications. Begin by removing all of the .obj and .exe files in src,
   apps, and elib plus all of the libraries in lib (effectively doing a 
   "make clean"). Then just do a make in the top level directory and
   everything will rebuild.

Use
___
	Network programming for multicasting isn't very different from
the network programming that you're already used to. The two basic
differences are that you need to join and leave a multicast group and
that you need to specify the outgoing ttl on most multicast packets.
	To join a group you simply need to use the "join_mcast_group"
call after you've done the udp_open. This registers the use of the
group with the low level routines that need to interact with the
multicast router to keep the packets flowing. After you're done,
you'll then need to leave the multicast group immediately prior to
issuing the close call by using the "leave_mcast_group" routine.
	The default ttl whenever you open a udp connection with a
multicast address is set to 1. That way, your multicasts won't leave
your local net. To expand the scope, you'll need to up the ttl by
using the "udp_SetTTL" call. This call should be used after the udp_connect
is done, but before anything is sent, and is persistent for the life of
the connection.
	Beyond those two points, most things are straightforward. You
do a udp_open, a join_mcast_group, set the ttl, read and write a few
things, leave_mcast_group, and close. That's all there is to it. The
only other thing you need to remember is to define MULTICAST whenever
you use this code so that you get all of the multicasting prototypes
from the tcp.h header file.



Reference
---------

join_mcast_group - joins a multicast group

	int join_mcast_group( longword ina )

	Where:
		ina	IP address of the group to be joined

	Behavior:
		join_mcast_group registers the use of the multicast
		address with the internals of the tcp stack that 
		deal with responding to IGMP queries from the 
		multicast router.	

	Returns:
		1	if the group was joined successfully
		0	if attempt failed


leave_mcast_group - leaves a multicast group

	int leave_mcast_group( longword ina )

	Where:
		ina	IP address of the group to be joined

	Behavior:
		leave_mcast_group deregisters the use of a 
		particular multicast address so that no
		IGMP Reports will be sent for that address.

	Returns:
		1	if the group was left successfully
		0	if attempt failed

udp_SetTTL -  Set the TTL on an outgoing UDP datagram.

	int udp_SetTTL(udp_Socket *s, byte ttl)

	Where:
 		s	the socket of the UDP connection (?!?) in question
		ttl	the desired ttl for the outgoing datagrams

	Behavior:
		udp_SetTTL allows the ttl for a particular UDP connection
		to be changed from the default value of 1. As the ttl is 
		increased, the scope of the packets will expand until it 
		reaches worldwide scope at around 192.

	Returns:
		1	always (there is no error return)




Notes
-----

[1] RFC-1112, "Host Extensions for IP Multicasting", is a description
    and specification of IP Multicasting by Steve Deering 
    (deering@parc.xerox.com) of Xerox PARC. It is available via 
    anonymous FTP on ds.internic.net in the /rfc directory as 
    "rfc1112.txt".

[2] vat, the Visual Audio Tool, is an audioconferencing application
    for the X-Windowing system written by Van Jacobson (van@ee.lbl.gov)
    of Lawrence Berkeley Labs. It is the de-facto standard for audio on 
    the MBone, and can be found via anonymous FTP on ftp.ee.lbl.gov.

[3] The MBone or the Internet Multicast Backbone is an outgrowth of the
    first two IETF "audiocasts". It is a virtual network, layered upon
    parts of the physical Internet to facilitate worldwide routing of
    IP multicasts. More information about the MBone can be found in the
    Frequently Asked Questions document available on venera.isi.edu in 
    /mbone as "faq.txt".



Author
------

	Jim Martin
	Rutgers University
	jim@noc.rutgers.edu
	11/10/93

