This directory contiains communication libraries for scopevents. All 
communication is in XML format.  The xml parser receives XML commands, 
finds out which function is registered to handle the given xml command 
and passes on paramters and data to the registered function. Binary data 
is converted into ascii format using base-64 encoding. The output goes into 
libxmlparse.a/xmlparse.lib in the PRODUCTHOME/lib directory. All exported 
functions go into PRODUCTHOME/include/eventsxml.h

OVERVIEW.txt     - Overview of this project
base64.c 	 - Utilities to encode/decode  in base-64 format.
lexer.c          - lexical analyzer, exports the yylex() function used by the parser
parse.y          - grammar definition for xml we use
register.c       - defines mechanism  to register and execute functions which come as xml commands

makefile*        - gnu makefile
makefile.common* - gnu makefile
buildxml.bat*    - Batch file to build for windows
xml.dsp*         - VC project file
xml.dsw*         - VC project file


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/remove/modify  a communication protocol

4. Ability to save data and to replay it, or reproduce it.



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> // Note the attributes must be 
    <Param fileName=hello></Param>     // exact or it won't work !
    <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. See the example at the end.


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
    --------

. Fully re-entrant

V. Things to do
   ------------

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


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


VII. 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");
}


