This is the function reference for andbna's RS232 extension package and DLL.

--------------------------------------------------------------------------

Things to do:

-Startup the DLL (not needed for extension package users)

-Open a port

-Set read/write timeout values and set other port attributes (optional)

-Perform read or write operations on the port

-Close a Port

-Shut down the DLL (not needed for extension package users)


--------------------------------------------------------------------------

Starting the DLL:

Call: RS232_Startup() at the beginning of the game
Takes no arguments and has no return. (not necessary for extension package users)


Opening a Port:

Use function: RS232_CreatePort

	real RS232_CreatePort (string name, real ID)

	This function creates a port. If a port is already open on the ID specified, it closes that one first.

	Arguments: 
 		-name : A string of the name of the port you whish to open, typically a value such as: "COM1" or "LPT3"note that capitals are important
	
		-ID this is a number of your choice from 0 to 19. This keeps track of the port for the DLL, so you can later perform operations on it.

	Return Value: Returns 1 on success, a negative value on failure


Closing a port:
	
	real RS232_ClosePort(real ID)
	
	Arguments:
		ID: The ID of the port to close
	
	Return Values: Always 0.
	

--------------------------------------------------------------------------

Reading values from a port:

There are 2 function you can use: GM_RS232_ReadByte which reads a single byte, and RS232_ReadString which reads a string

	
real RS232_ReadByte( real ID)

	Arguments:

 	-ID : The ID of the port, the same number you specified in RS232_CreatePort.

	Return Value: Returns a positive integer from 0 to 255 (inclusive) signifying the byte read. If it failed, a negative 	value is returned.


	string RS232_ReadString( real length, real ID)
	
	Reads a string from the port

	Arguments:
		-length : The maximum length of string to be read
		-ID : the ID of the port you want to read from

	Return Value: Returns the string that was read. It's length may be shorter than the specified if the read times out (because there is nothing else to be read) It returns an empty string on failure (however if there was nothing to read in the first place, the string will also be empty)

--------------------------------------------------------------------------

Writing Values to the port:

3 Functions: RS232_WriteByte, to write a single byte. RS232_WriteReal, to write an 8 byte real value, and RS232_WriteString, to write a string

real RS232_WriteByte( real number, real ID)

	Arguments:
		-number : The byte you want to write
		-ID : the ID of the port to write to.

	Return values: Returns 1 on success, negative value on error.

real RS232_WriteReal(real number, real id)

	Arguments:
		-number : The number you want to write
		-ID : the ID of the port to write to.

	Return values: Returns the number of bytes written on success (should be 8), negative value on error.

real RS232_WriteString(string str, real length, real ID)
	
	Arguments:
		-str: The string to write
		-length : the length of the string ( string_length(str) )
		-ID : Id of the port to write to
	
	Return Values: Returns the number of bytes written on success (should be length) returns negative on failure.

--------------------------------------------------------------------------

Misc Functions:

real RS232_SetTimeouts(real ReadIntervalTimeout,real ReadTotalTimeout,real ReadMultiplier,real WriteTimeout,real WriteMultiplier, real ID)

	This is an important function. When you call a read or write function, the DLL will NOT return until it is complete. Hence, the game will freeze while it is waiting.
	While the functions themselves are fast enough for this not to be a problem, there are  2 things to consider:
 
	First, If you call a read function and there is nothing to read, the function will hang. So, we set the Read timeouts to tell the DLL to stop reading after a number of miliseconds if nothing is recieved.

	Second, If the port is not connected to anything, write functions will also hang. So, we can set the Write Timeouts to tell it to return if the DLL cannot write after x milliseconds.

	Arguments: 
		-ReadIntervalTimeout: The maximum time in milliseconds to wait in between recieving data (0 means that this type of timeout is unused.)

		-ReadTotalTimeout and ReadMultiplier: The maximum total time in milliseconds to spend reading. The value of ReadTotalTimeout is added to the product of ReadMultiplier and the requested number of bytes to be read. (Timeout = ReatTotalTimeout+[ReadMultiplier * numberofbytes] )
		NOTE: Setting those 2 to 0, and setting ReadIntervalTimeout to -1 will cause the function to return immediatly whatever there is to be read (ie, it won't wait for data to come through.) If you are unsure what to set the values to, those make a good default.

		-WriteTimeout and WriteMultiplier: They work the same as ReadTotalTimeout and ReadMultiplier respectivly, except they work with the write functions. If you are unsure what to put, a WriteTimout of 10 and WriteMultiplier of 1 are a good default.

		-ID: The ID of the port to set the values.

	Return Values: Returns 1 on success, negative on error.


real RS232_SetPortProperties(real BaudRate,real ByteSize, real Parity,real StopBits,real ID)

	This is a function you don't need to call, but some user may want to specify some of these attributes.
	
	Arguments:   Passing a negative value means 'no change'
		-BaudRate: Sets the Baudrate
		-ByteSize: Sets the bytesize
		-Parity: Sets the parity, the following are values you can use: 
			0 : EVENPARITY 
			1 : MARKPARITY
			2 : NOPARITY
			3 : ODDPARITY
			4 : SPACEPARITY
		-StopBits: Sets the stopbits, The following value may be used:
			0 : ONESTOPBIT 
			1 : ONE5STOPBITS
			2 : TWOSTOPBITS

	Return Values: 1 on success, negative on error.

	NOTE: If anyone needs to modify any port properties not in the above function, contact andbna on the GMC and I will add additional parameters.

real RS232_SetFlowControl(real fOutxCtsFlow ,real fOutxDsrFlow,real fDsrSensitivity,real fTXContinueOnXoff,real fOutX, real fInX,real fDtrControl,real fRtsControl,real XonLim,real XoffLim, real XonChar,real XoffChar,real ID)
	
	This function is similar to SetPortProperties; it specificaly sets Flow Control properties.
	!!!!GM6 users see note below!!!!

	Arguments:  Passing a negative value means 'no change'

The following arguments can be set to True or False (0 or a positive number) (negatives still denote 'no change')
	
		-fOutxCtsFlow 
If this member is TRUE, the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.

		-fOutxDsrFlow 
If this member is TRUE, the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is turned off, output is suspended until DSR is sent again.

		-fDsrSensitivity 
If this member is TRUE, the communications driver is sensitive to the state of the DSR signal. The driver ignores any bytes received, unless the DSR modem input line is high.

		-fTXContinueOnXoff 
If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.

		-fOutX 
Indicates whether XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.

		-fInX 
Indicates whether XON/XOFF flow control is used during reception. If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.

	The rest of these arguments take varying values (negatives still denot 'no change')

		-fDtrControl:  The DTR (data-terminal-ready) flow control. This member can be one of the following values:
			0 : DTR_CONTROL_DISABLE-Disables the DTR line when the device is opened and leaves it disabled.
 			1 : DTR_CONTROL_ENABLE-Enables the DTR line when the device is opened and leaves it on.
 			2 : DTR_CONTROL_HANDSHAKE-Enables DTR handshaking.

		-fRtsControl:  The RTS (request-to-send) flow control. This member can be one of the following values.
			0 : RTS_CONTROL_DISABLE-Disables the RTS line when the device is opened and leaves it disabled.
			1 : RTS_CONTROL_ENABLE-Enables the RTS line when the device is opened and leaves it on.
			2 : RTS_CONTROL_HANDSHAKE-Enables RTS handshaking. The driver raises the RTS line when the "type-ahead" (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full.
			4 : RTS_CONTROL_TOGGLE-Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.

		-XonLim:

The maximum number of bytes allowed in the input buffer before flow control is activated to allow transmission by the sender. This assumes that either XON/XOFF, RTS, or DTR input flow control is specified in fInX, fRtsControl, or fDtrControl. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.

		-XoffLim:
The minimum number of bytes allowed to be left in the input buffer before flow control is activated to inhibit the sender. Note that the sender may transmit characters after the flow control signal has been activated, so this value should never be zero. This assumes that either XON/XOFF, RTS, or DTR input flow control is specified in fInX, fRtsControl, or fDtrControl. 

		-XonChar: The value (0 to 255) of the XON character for both transmission and reception.

		-XoffChar: The value (0 to 255) of the XOFF character for both transmission and reception.


	Return Values: 1 on success, negative on error.

	NOTE: These argument descriptions come straight from the MSDN page following, which contains relevant information on both SetFlowControl and SetPortProperties functions; http://msdn2.microsoft.com/en-us/library/aa363214(VS.85).aspx

!!!2nd NOTE: FOR Gm6 users!!!!!, the 11 argument cap means XonChar and XoffChar have their own function. They are omitteded in the above function, and instead use:
	RS232_SetXChar(ty_real XonChar,ty_real XoffChar,ty_real ID)	
	

real RS232_GetLastError()

	This function can be used if a negative value is returned form a function to get additional error information.
	
	Return Values: Returns 0 if the previous call was successful, otherwise it returns an error code you will have to look up on Microsoft's site. :p


RS232_CleanUp()
	For DLL users, call this at the end of the game to properly shut down the DLL. The Extension Library automatically does this for GM7 users.
		
	Return Value: Always 0.

--------------------------------------------------------------------------

Error Codes:

	Here is a list of error codes the functions may return:
	
	-1 (negative one) : the ID is invalid. Either you used an ID outside the range of 0 to 19, or you tried to used a port that has not been created.

	-2 (negative two) : A WinAPI function failed within the DLL, Call RS232_GetLastError() for more info.

	For RS232_ReadString, a NULL string can mean either of the above, or that there was simply nothing to be read.
	You can call RS232_GetLastError to see if it was an API error, if it returns 0, it was not.
