Copyright (C) 2001-2002 Keith Leinenbach
One Man And A Cat
Software
onecatweb.com
Parametrized Strings
All data is handled as a parametrized string of name=value pairs, delimited by the | character. | is a good delimiter since it is rarely used and makes a good visual separator during debugging as well. $|$ should be used in the rare instance that | is found in the value content.
Example:
Temperature=450|Pressure=1200|
Boolean
Since data is provided in a string format, "True" and
"False" capitalized as you see it will represent true and false
boolean values.
Lists
If values come in multiple parts (such as
vectors or capability lists), they should be formatted as follows:
delimiter value1 delimiter value2 delimiter ...
Examples:
}Temperature}Pressure}Time}
#45#89#72#
In the first example, } is used as the delimiter and Temperature, Pressure, and Time are the values in the list. The second example uses # as the delimiter. Providing the delimiter as the first character in a list does not substantially increase parsing complexity, but provides flexibility for the content. Note that | can not be used as a delimiter.
| int OMGetData(LPCTSTR DataList, LPTSTR Values,OMCallback Callback=NULL) | ||||||||||
|
Description: Retrieve the data provided in the DataList parameter. If no Callback is provided this function should block until the data has been successfully retrieved otherwise it should return immediately and provide the data as it is available through the provided Callback function. Parameters: DataList - is a name=command| delimited list of names for data that is needed.
Values - returns a parametrized list of values to be returned in the name=value| delimited format. Returns: Error value as integer and a brief description in named value string called Error. | ||||||||||
|
Examples EXAMPLE OF DataList sent: EXAMPLES OF Values returned: |
Using a blocking function for getting data can slow down the application considerably in cases where live data display is involved. Using a standard windows callback provides the easy way to feed data as it is available. Streaming data can be specified with the command "stream" and "stop" in the DataList parameter. The interval setting provides the data at the requested interval. This will be given based on the minimum interval setting given in the capabilities string.
Format:
void OMCallback(CString &Values,int
Error);
OMGetData would then return immediately.
| int OMGetCaps(LPTSTR Capabilities) |
|
Description: Retrieve a list of capabilities given the current context. Parameters: Capabilities is returned in a | delimited format with } delimited lists for values containing 0 or more of the commands
Returns: Error value as integer and a brief description in named value string called Error. |
|
Examples This would mean the MIL can be set or get, and RPM can be retrieved either as a snapshot or in a stream of minimum interval 200 ms. NOTE: Keeping with the specification for listed values, the } is given as the first character in each value list to denote a list is being used and to specify the delimiter. |
| int OMGetVersion() |
|
Description: Gets the version number for the DLL. Returns: Returns the DLL version with the last 2 digits reserved for the digits to the right of the decimal. |
|
Example 101 - would mean version 1.01 etc. |
The API was designed with simplicity in mind. It has only 3 functions. All data is converted to and from strings. By using LPCTSTR for constant strings and LPTSTR for modified strings the TCHAR value type can be taken advantage of, making portability between ANSI and UNICODE environments easy to do. For those using MFC, CStrings work well with this type of system as well.
Parametrized name=value pairs were chosen over the simpler value delimited to provide support for callback environments where the data sent back to the host process must be specified.
Questions should be addressed to keithml@onemanandacat.com.