Design
-----

I. Introduction
   ------------

Ideas behind the design

1. To have a text based XML like protocol, which in its own way makes
   the protocol easier to understand. 
   
   Have good recovery mechanisms for lost data, and to be able to easily 
   resynchronize with the target.

2. Not much overhead with using XML

3. Should be simple to add and remove to a communication protocol



II. Current design
    --------------

The host and target communicate with XML like commands.  A Sample command
would have a format like 
  <Command name=createFile numParam=3>
    <Param fileName=hello></Param>
    <Param owner=saket></Param>
    <Param permission=755></Param>
  </Command>


The receiving end would receive data over the network and keep passing it
on to the parser.  The receiving side would pre-register handler functions
for different Commands that it would receive on the  communication link. 
The parser keeps calling the registered functions as it processes data 
received on the communication link. The handler function can then extract 
the parameters and take appropriate action.

void handlerCreateFile(void* xmlHandle){
	char* fileName=parseParamString("fileName",xmlHandle);
        char* owner=parseParamString("owner",xmlHandle);
  	char* permission=atoi(parseParamString("permission",xmlHandle));

	touch filename;
	chown owner filename;
	chmod permission filename;

}

This makes chaging the protocol and the parameters very simple for the 
host/target. 


IIa. Data Structures

 +-----------------------+
 | Number of functions   |
 +-----------------------+
 | Max num of functions  |
 +=======================+
 |Function name          |
 |Function pointer       |
 |Default parameters     |
 +-----------------------+
 |        ....           |
 |        ....           |
 |_______________________|


IIb. Default parameters

a) from the other communication end  you receive
       i) function to call
      ii) parameters (remote)

   There might be cases when you would like to pass local parameters
   to this function, for example passing the object pointer to all 
   handler functions.


IIc. Sending binary data

Binary data is sent over the XML protcol after base-64 encoding the data.
This adds a 33% overhead to the amount of data being sent.

III. API
     ---

1. To use the API you first call XMLInit(int) which returns a memory pointer.
   This pointer is the handle to the XML library
2. Now you can register handler functions using the registerFunction call
3. Once you have registered all  your handlers you just need to keep calling the
   passing on the data you get over the network to the parser.


IV. Features
    --------

1. Fully re-entrant
2. Passing local parameters

V.  Implementation notes
    -------------------- 
    The code in this folder serves several purposes.  When used in wtx
    mode, the "CoverageLink" is a thread on the host side and uses wtx
    calls to get the arrays from the target.  In TCP/IP mode the
    "CoverageLink" is a task on the target that will read and send out
    data to the host via TCP.  Through coveragewtx.cxx, this code is
    also used for host side wtx calls to the target, such as for
    finding symbols or starting the TCP/IP link.

    As the link code is different depending on whether it is target or
    host side, the code is liberally sprinkled with "#ifdef COVERAGE_WTX" 
    statements.


VI. AE Changes
    ----------

    The major change that was needed for the AE port is dealing with
    multiple PDs.  It was decided that CoverageScope should just add
    together the results from multiple pds. This means that it needs
    to look for the arrays in every pd. So at the beginning of each
    polling cycle, CoverageScope checks to see if any pds are
    added. The host keeps a list of all the pds found and a list of
    all the array names, so the array names + pd can be added to the
    list of all arrays + pd when a new pd is found. The list of array
    names and list of pds is kept host side, in TCPDataLinkAE.java for
    tcp mode and in the CoverageDaemonInfo struct (coveragedata.c) in
    wtx mode.

VII. Things to do
   ------------

1. Add verbosity 
2. Rename functions..
3. More error checking/reporting for robustness
4. Automated test suites


VIII. Other uses
    ----------
  (?) Automated test suite generator 


IX. Example of a basic link code
     ----------------------------

The basic code for writing a link piece based on the XML parser 
is pretty simple. Here is an example framework.

link.c
------
....

Link(){

xmlhandle=XMLInit(10)
sprintf(xmlParam,"<Param pCoverage=%u ></Param>",(unsigned int) pCoverage);
registerFunction("CONNECT_CONFIRM",CoverageConnectConfirm,xmlParam,xmlHandle);

while (true){
	 if there is no connection
	 	wait for connection()
	else
		read(readbuff);
		commandParse(readbuff);
		
	sleep(short duration);
}


handler.c
---------
void CoverageConnectConfirm(void* xmlHandle){
        CoverageDaemonInfo* pCoverage= (CoverageDaemonInfo*)(atoi(parseParamStri
ng\
                                ("pCoverage",xmlHandle)));
        pCoverage->connectionUp=RTI_TRUE;
        if (pCoverage->debugLevel>0)
                RtiMessage("Connection Confirmed from host side\n");
}


