---------------------------------------------------
 MULTITST.EXE: multicast and ping test application
---------------------------------------------------

This application is referenced in Chapter 16, "Optional Features,"
of _Windows Sockets Network Programming_  by Bob Quinn and Dave Shute,
published by Addison-Wesley, Reading, MA  ISBN: 0-201-63372-8

What it does: The MULTITST application allows sending and receiving of 
 multicast datagrams RFC 1112 and RFC 1122), and experimentation with
 the multicast APIs. MULTITST also sends and receives Internet
 Control Message Protocol RFC 791 "echo request" and "echo reply" 
 datagrams, typically known as "ping" packets. and uses the IP_TTL 
 socket option to set the IP time-to-live field for traceroute.

What it illustrates: It shows how to use the multicast,
 and SOCK_RAW sockets for ICMP (with IP_TTL).

How to Use it: The two parts to this program--multicast
 UDP and ICMP Ping--have seperate interfaces. We'll describe the
 steps involved with using each seperately. To play with multicast,
 you need to get a socket by selecting the "Socket" menu
 item. Once you have a socket, you can send to multicast addresses,
 or any other IP address with the Sendto menu item at any point.
 However, receiving multicast packets requires additional steps.

 The steps required to receive multicast datagrams, sometimes differ
 between different multicast implementations. For Microsoft's,
 for example, you must call call bind() (with the Bind menu item)
 next. For bind() you can select any class D address, and any port
 number (or use 0 to let the TCP/IP stack assign an arbitrary port).
 Next step involves socket options, which you can access with the
 "SockOpts" menu selection. The most important option
 is IP_ADD_MEMBERSHIP, which joins the multicast group to allow
 you to receive datagrams destined for that address. You should
 specify the same class D address for the multicast group that
 you used in the call to bind(). In some cases, you may also have
 to use the IP_MULTICAST_IF option to specify the default interface.
 Here is a short description of these and other multicast-related
 options; for more information, see Chapter 16: "Optional
 Features"

  - IP_ADD_MULTICAST: join multicast group to receive multicast
     datagrams
  - IP_DROP_MULTICAST: leave a multicast group
  - IP_MULTICAST_LOOP: disable or enable multicast loopback (enabled
     by default)
  - IP_MULTICAST_TTL: set the IP "Time to Live" for
     multicast (it is only one by default, which means multicast don't
     go beyond the first router)
  - IP_MULTICAST_IF: set the multicast interface

*Important Note* The "BSD option values" is set by default
 to use the BSD-compatible values for the option name macro values.
 You will need to disable this setting for multicast implementations
 --like Microsoft's--that use the Steve Deering values for each
 multicast option.

 To send and receive ICMP "ping" datagrams, select the
 "Ping" menu item, and the ping interface will be displayed.
 First, press the "socket()" button to get raw socket
 to use for ICMP. Next, enter an IP address or hostname as the
 "Destination host." At this point you can press "sendto()"
 to send an ICMP echo request packet, and MULTITST will display
 a message box when the response arrives. You could change the
 ICMP ID and sequence numbers if you wish; these change the values
 of the ICMP fields as described in RFC791.  You can also try 
 changing the time to live value in the IP header RFC 791), 
 although very few WinSock implementations support the BSD-compatible 
 IP_TTL socket option that the MULTITST application uses.

Known Problems: MULTITST notifies the user of each multicast
 datagram and ping echo response arrival by displaying a message 
 box. This is less than ideal, especially when receiving ping responses
 sent to broadcast addresses, or when using the traceroute option
 (by setting IP TTL).

File List: 
 MULTITST\MULTITST.DEF 
 MULTITST\MULTITST.ICO 
 MULTITST\ICMPPING.H 
 MULTITST\RESOURCE.H 
 MULTITST\MULTITST.MAK Makefile for 16-bit multitst.exe 
 MULTITST\MULTI_32.MAK Makefile for 32-bit multi_32.exe 
 MULTITST\MULTITST.H 
 MULTITST\ICMPPING.C 
 MULTITST\MULTITST.RC 
 MULTITST\MULTITST.C

--------
 NOTES:
--------

We used Microsoft Visual C++ enviroments (versions 1.52 for 16-bit,
and version 2.1 for 32-bit) to create most of the makefiles.
Unfortunately, because the paths are hard-coded in the file, you will
have to bring the project files (.mak) into the respective MS C++
environments to readjust things to the new directory, and even then
you will have to manually alter the project to access the library
files (the are in the root of the directory where you install the
samples).

All samples--including the sample DLL and static library--have a
number of other things in common:

  - They all have 32-bit versions, and all 32-bit version names
     end with "32" (16-bit versions don't have a number).
  - They use the WSAperror() function from #WINSOCKX">WINSOCKX.LIB
    to display error values and short descriptions when an unexpected
    error occurs.
  - They display error messages on any suspicious error condition.
     They don't hide errors, but report them whenever they occur. As
     we describe n a_c.htm">Appendix C: WinSock Error Reference,
     these error messages should appear only when a "user fixable
     error" occurs. If you get an error message from a sample
     application for a non user-fixable error, then this may
     indicate an anomoly in the WinSock implementation that your applications
     may need to deal with. We show you the errors on purpose, to make
     you aware of unexpected conditions.
  - They have a minimal user interface, and do not have help (.HLP)
     files available.
  - They are meant to be played with. They are for exploration
     and experimentation as well as to illustrate how to write WinSock
     applications.

The icons used for each sample don't mean much, but they meet
the following three criteria:

    - They each contain the socket from the official WinSock icon.
    - Each one is colorful in its own unique and wonderful way.
    - Each took under 10 minutes to create.