@(#)README	1.5  97/12/23

                                 MPoll
                           Version Beta 1.*
                                                   
             Andrew Patrick, Communications Research Centre
                      <andrew@calvin.dgbt.doc.ca>
                  http://debra.dgbt.doc.ca/mbone/mpoll
                              
Introduction
------------

"MPoll" is a real-time opinion polling and rating collection tool
that uses multicasting to distribute questions and responses to all
multicast session participants. 

MPoll was developed by Andrew Patrick at the Communications
Research Centre (CRC) in Ottawa, Canada, as part of the MERCI project
on Collaborative Work Tools.

MPoll was developed with the following uses in mind:

   - collecting quality ratings during multicast sessions
   
   - collecting opinions and votes during multicast collaborative
      work sessions
   
   - collecting opinions on general topics or current events


Using MPoll
-----------

   Usage: mpoll [-D] [-V] [-l] [-t ttl] [-C "title"] address/port
   
    OPTIONS:
      -D  : use default address and port (224.2.2.200/6666; for debugging)
      -s  : simulate results (useful for demos)
      -V  : print version number and exit
      -l  : print logging information (for debugging)
      -C "title" :  the theme title for the questions
      -t ttl : the multicast TTL (default = 15)

MPoll normally requires specifying a multicast address and port.  
MPoll can be used by itself, or with other multicast tools such as
VAT and VIC in an MBONE session. MPoll can be started from SDR once
an appropriate "plugin" is installed (see below), or from the command
line.  Command options that MPoll accepts include the multicast TTL
(-t), which defaults to 15, and a session title (-C), which defaults
to "Unknown Theme".  These are the same command options used by other
multicast tools.

Once MPoll is started, there is built-in help for each of the windows
that explains the features and functions.


How MPoll Works
---------------

MPoll works by sending question and response packets to the multicast
address, and listening for packets from other hosts.  The users can
create a new question and this will become available to all the
users who have joined that multicast session.  As users answer the
question the responses are distributed to all the participants,
where they are tallied and displayed.  MPoll packets are
redistributed periodically as long as the program is running so that
all current users will see all the results.

   Normally, MPoll will be left running continuously during a polling
   period or multicast session.

MPoll uses a simple plain-text protocol for constructing multicast
packets that is similar to the Session Description Protocol (SDP)
used in SDR.  There are currently 4 types of packets generated by
MPoll: questions, remove question instructions, user responses, and 
membership information.

MPoll creates a cache file in your home directory ("~/.mpoll_cache")
for storing the questions and your responses from your last MPoll
session.  This allows you to quit and restart MPoll and have the
questions and your responses for the last session reloaded.


Installing MPoll
----------------

   Binary Distribution
   -------------------
   
   The MPoll binary file is a stand-alone C program that does not
   require any extra libraries in order to run.  Simply copy the
   MPoll program to a directory that is in your path.

   Currently, binary distributions of MPoll are available for:

      - Solaris 2.5
      - SunOS 4.1.4
      - Win32 (Windows 95 & NT)
      - SGI IRIX 6.4

   Anyone who can help to compile MPoll for other platforms is asked
   to contact the author.


   Source Distribution
   -------------------
   
   MPoll is written in C and Tcl/Tk.  The development environment is:

      UNIX:
      - SPARC Solaris 2.5
      - gcc version 2.7.2
      - Tcl 7.6 / Tk 4.2
      
      WIN32:
      - Microsoft Visual C++ 5.0 on Windows95
      - Tcl/Tk 8.0 on Windows95

   In addition, MPoll uses the Embedded Tk (ET) toolkit by Richard
   Hipp (http://users.vnet.net/drh/ET.html) for integrating C and
   Tcl/Tk programming.  Version 1.7.1 of ET is included as part of the
   MPoll sources and will be built during the make process.
   
   No configuration procedure is available yet for MPoll.  There are
   some configuration options at the beginning of "Makefile" that you
   will probably have to set.  MPoll has been developed under Solaris
   2.5, so that is the default platform.  For other platforms you
   should edit the Makefile and select the configuration variables
   that are appropriate for your system.  Configurations are
   currently provided for: 
   
   Solaris 2.5
   SunOS 4.1.x
   IRIX (use "pmake")  
   FreeBSD 2.2.1    
   Windows95 (use "nmake -f Makefile.vc")
      
   I would love to hear about any problems in building and running
   the program.  Also, if you port MPoll to another platform, please
   contact me with any information about changes necessary, and if
   you can supply a binary for my archive site.


   The SDR Plugin
   --------------
   
   Since MPoll is a new program, and polling is a new MBONE
   application, an appropriate media has not been defined in SDR. 
   So, in order to use MPoll from SDR you must install a "plugin".  
   The plugin provided in the distribution is
   
      sdr2.plugin.S53.control.udp.mpoll.mpoll
   
   and you should copy this to a "~/.sdr/plugins" directory on your
   system.  See the SDR documentation for more information about
   plugins.

   
Limitations
-----------

- MPoll currently has no unicast support

- MPoll is currently limited to 100 questions per session, and up to
   10 possible answers per multiple-choice question.  The question limit
   should be configurable be editing the MAX_TOPICS parameter in
   "mpoll.h", but changes to the MAX_RESPONSES parameter will probably
   not work.

- MPoll should someday read the ~/.RTPdefaults file, and perhaps some
   other X resources

- a function to remind users to update their responses should be
   added

- we may need a function to edit an existing question


Known Problems
--------------

- this program is in an Beta stage of development.  There are
   probably some features missing and some bugs.

- MPoll was developed on Sun systems and has been tested on a few
   other platforms.  More work on portability is required.

- no attempt is made to do robust font selection so MPoll will
   probably fail if the fonts I use are not on your system.  See
   "mpoll.h" for the font definitions.

- the command line args "-h or -help" dump core, use "--help" instead

- MPoll should probably be ported to Tcl/Tk 8.0.  There are changes
   in that version concerning file handles that will have to be
   accomodated.
  
- the cache routines will not work properly if multiple copies of 
   MPoll are run at the same time.  The cache will only record the
   data for the copy that was used the most recently.


Acknowledgements
----------------

The protocol used in MPoll is fashioned after the SDP protocol used
in SDR, and I thank Mark Handley, Van Jacobson, and other
contributors for their work on SDP and SDR.

I also used the SDR source code as an example while working on MPoll
and that code was useful for techniques like multicast socket
management and periodic redistribution of packets.  I learned a lot
from viewing other people's code and I am sure that I made lots of
mistakes, for which I am wholely responsible.  Although I don't
believe that I have used any of their code directly, to be safe I
include their acknowledgement:

   This product includes software developed by the Computer Science
   Department at University College London

Portions of the code used to support the WIN32 platform were copied
from the SDR program, and they were borrowed by Lawrence Berkeley
National Laboratory.  In accordance with the copyright notice, I
hereby state:

   This product includes software developed by the Network Research
   Group at Lawrence Berkeley National Laboratory.
   
  



Licence Terms
-------------

   Copyright (c) Communications Research Centre, Government of Canada
   1997.  All rights reserved.
   
   License is granted to copy and use this software, for research and
   evaluation purposes, provided that the Communications Research
   Centre is acknowledged in all documentation pertaining to any such
   copy or use. The Communications Research Centre grants no other
   licenses expressed or implied. Title, ownership rights, and
   intellectual property rights in the software shall remain with the
   Communications Research Centre.  The Centre's name and the
   Government of Canada should not be used in any advertising without
   written permission.
   
   THE COMMUNICATIONS RESEARCH CENTRE MAKES NO REPRESENTATIONS
   CONCERNING EITHER THE MERCHANTABILITY OF THIS SOFTWARE OR THE
   SUITABILITY OF THIS SOFTWARE FOR ANY PARTICULAR PURPOSE.  The
   software is provided "as is" without express or implied warranty
   of any kind.
   
   These notices must be retained in any copies of any part of this
   software.
   
  
Author
------

      Dr. Andrew Patrick
      Network Services & Interface Design Laboratory
      Communications Research Centre
      Industry Canada
      3701 Carling Ave.
      P.O. Box 11490, Station 'H'
      Ottawa, ON CANADA
      K2H 8S2

      Phone: (613) 990-4675
      FAX:   (613) 998-9648
      E-Mail: andrew@calvin.dgbt.doc.ca
      WWW: http://debra.dgbt.doc.ca/~andrew
      
