README.AuxData-ADtrace 12-22-94 A Brief Introduction to CU-SeeMe's "Auxiliary Data Transport" Facility ----------------------------------------------------------------- By Larry Chace This facility serves to transmit and receive items of data that are sent in parallel with the normal CU-SeeMe video and audio. Aux Data transmission is available for use by other facilities that are built into CU-SeeMe, such as the SlideWindow, or that are constructed as plug-in modules, using the Function Module Interface designed and coded by Aaron Giles of the Cornell University Medical College. Auxiliary data consists of "items" of data, each one of an arbitrary length, subject to memory availability on the sender and receiver machines. Each item is identified by a "type", a 32-bit number, and sending and receiving application programs must "register" to use a given type. Applications using AuxData can send single items or streams of data, broken into items, but they need to allow for the differing amounts of time (needed for recovery from packet loss) it may take different participants to receive a particular item. As an example, consider the "Talk" facility. It consists of a module designed to use the plug-in interface and it is started when CU-SeeMe starts executing. The Talk program registers that it will be using an Aux Data type of "CUtk" (as 4 characters). When a user types a line into the Talk input area, the Talk program sends it as an item of type "CUtk". At each receiving machine, the Aux Data Transport routines receive items of this type and send them to the Talk module's input routine, which then formats the lines and writes them to the Talk window's output area. Like CU-SeeMe's video and audio, Aux Data items can be sent to multiple recipients. Unlike video and audio, however, the Aux Data Transport routines will make an effort to correct transmission errors such as dropped packets. The error-recovery process is inivisble to the Aux Data application programs, except that some recipients may get their data later than others, or some participants may not realistically have enough bandwidth to receive large items within the context of a real-time conference. Not opening the the SlideWindow if you use a modem to connect will prevent anyone sending slides to you. An important point about AuxData is that, although it can be used for many things, by comparison to audio and video sending, it trades timeliness for reliability, and an someone designing an application with a tight requirement for timeliness should, perhaps, not think of using AuxData. A Brief Introduction to CU-SeeMe's "Aux Data Trace" Plug-In ------------------------------------------------------ Aux Data Trace is a simple plug-in addition to CU-SeeMe, beginning with the 0.80a1 version, that will display some information about CU-SeeMe's Auxiliary Data Transport facility. This program may be considered a "wire-tapping" trace tool in that it can display information about various Aux Data items currently being sent or received. Aux Data Trace itself is a plug-in routine and is controlled by a menu bar item. To begin tracing, you must select "Start Aux Data Trace" from the AD Trace menu item. The trace window consists of an input area and an output area. At present, the only supported input is a RETURN, which signals the Aux Data Transporter to drop the next Aux Data input packet, no matter what it is. This is meant for debugging and will force the receiving Aux Data Transporter to re-try the dropped packet. The output area can contain several different type of of information: 1. DATA=123.456.789.01: abcd, ..12, 345, 678 DONE This output line shows that the Aux Data Transporter has received an Aux Data data packet from the machine at IP address 123.456.789.01. The data is of Aux Data type "abcd". Its sequential item number is something that ends in 12 (the actual number is very large and uninteresting). The data is 345 bytes in length and it begins at offset 678 within the item. The word "DONE" means that this packet completes the item (or the item was already complete some packets ago). Unprintable bytes in the type field are displayed as dots. 2. rept=123.456.789.01: abcd, ..12, 345, 678 DONE This output line shows the same information as the "DATA" line, except that this packet was a repeat packet. That is, some (small) items are sent a small number of times in an attempt to ensure that at least one packet from the item is received correctly. (At present, any item less than 1401 bytes gets sent out as 5 repeats of a single data packet.) 3. rtry=123.456.789.01: abcd, ..12, 345, 678 DONE This output line shows the same information as the "DATA" line, except that this packet was a retry for a failed packet. As the receiver notices that a packet got dropped, it sends a retry request back to the original sender, which will later re-transmit the appropriate packets. It is possible for some receivers to request a retry a retry that will then be seen by all receivers, even the ones that had already received all of the packets. 4. drop=123.456.789.01: abcd, ..12, 345, 678 DONE This output line shows the same information as the "DATA" line, except that this packet was purposefully ignored by the Aux Data Transporter. This happens only when the receiving user types a RETURN into the input area of the Aux Data Trace window, thereby requesting that the next packet get dropped. (This is just for testing.) 5. SUPR=123.456.789.01: Item List: ..12 ..34 ..56 This is an Aux Data supervisory message that shows that a sender (whose IP address is given) has some Aux Data items available for re-transmission if necessary. The item numbers are given (and, once again, only the bottom portion of the number is shown). This "available item list" is sent out periodically to help receivers know what items can be retried. All retries are handled by the Aux Data Transport routines without any help from the application programs (except that the application program can "cancel" an item, making it no longer available for retries.) 6. SUPR=123.456.789.01: Ack for item ..12 This is an Aux Data supervisory message that shows that a receiver has sent back a positive acknowledgment for item number ..12. This is a special case, in that the sender has sent this item only to a specific receiver; in such a case, the Aux Data Transporter uses a positive acknowledgment to indicate the correct transmittal of the item. An Aux Data application has to be specially designed to send an item to only one recipient. 7. Discarding output item ..12 This message shows that the sending Aux Data application has cancelled the item, making it no longer available for retries. 8. Processing hole list for item ..12 This message shows that the sending Aux Data Transporter has begun to process any reports it has received about packets that failed to arrive at their recipients. The transporter routines save up all of the reports until all current activity for the item is complete; they then merge all of the hole reports into a new master list, from which they then start sending retries. The next line or lines will display the holes in the format: origin, length, end. A length of "-1" means "the entire item". General Comments about Aux Data Trace This facility is very crude (but ugly) and was intended just for use during development. However, we are making it available in case some real-life Aux Data applications suffer from problems that could be better diagnosed with the aid of some sort of trace facility. In order for the Aux Data pruning algorithms to work, you must have an active Aux Data application (for that type of Aux Data) before Aux Data items will be sent to you. This applies to the Aux Data Trace facility as well; you cannot trace Aux Data types for which you do not have a receiver but cause no one will send you that type of data without a receiver. At present, there is a special ugliness that appears when the trace buffer gets larger than 32K bytes; the trace output area turns to gibberish (but it does not crash!). You can clean it up by closing the trace window and then re-opening it. That will discard all previous contents and will give you another 32k bytes for tracing additional events. If you like, you can Copy (cmd-C) from the trace window's output area, but there is no direct support for printing or for selectively clearing the window. We will probably be improving the trace facility, and so we welcome your comments and constructive criticism.