3.4.1 General Functions
InfoNew ()
Prototype
extern tInfos *InfoNew (void);
Arguments none Description
Creates a new instance of type tInfos.
Return Value
Pointer (handle) to the newly created tInfos instance, or a NULL pointer on failure.
# Infofile read by the example code (taken from Data/Vehicle/DemoCar) Body.Mass = 1301
PowerTrain.Kind = Front
#include “infoc.h”
#include “InfoUtils.h”
#include “Environment.h” /* for SimEnv global variable */
int
Vhcl_NewInit (const struct tInfos *Inf /*vehicle parameters*/) {
int count = GetInfoErrorCount();
double vel, pos, mass;
char *ptkind;
mass = iGetDbl(Inf, "Body.mass");
ptkind = iGetStr(Inf, “PowerTrain.Kind”);
/* testrun parameters */
vel = iGetDblOpt(SimEnv.TestRun.Inf, "DrivMan.Velocityt0", 0.0);
pos = iGetDblOpt(SimEnv.TestRun.Inf, "Road.CarStartPos", 1.0);
if (GetInfoErrorCount() != count) return -1; /* Error */
return 0;
}
37 Infofile Module
C Function List
InfoDelete ()
Prototype
extern int InfoDelete (tInfos *inf);
Arguments
• inf - handle of the data type tInfos to be deleted Description
Deletes the specified tInfos data type.
Return Value (check with frank)
InfoRead ()
Prototype
extern int InfoRead (tErrorMsg **perrors, tInfos *inf, const char *filename);
Arguments
• perrors- pointer to an array that will contain any errors generated during the reading of the infofile
• inf - handle of type tInfos that will be used to store the information read
• filename - name of the infofile to be read Description
Reads from the file specified infilenameand writes to the tInfos buffer pointed to byinf.
Return Value
Returns the number of errors that were generated during the read and that are contained in the perrors list. If the value is (0) then no errors were generated, if the value is ( greater than 0 ) then there were syntax errors during the read, if the value is (less than 0) then there were access, i.e., hard errors during the read which caused the read to fail.
InfReadMem ()
Prototype
extern int InfoReadMem (tErrorMsg **perrors, tInfos *inf, char *bufStart, int bufSize);
Arguments
• perrors- pointer to an array that will contain any errors generated during the reading of the buffer
• inf - handle of type tInfos that specifies the memory location where the information read will be stored
• bufStart - pointer to the buffer to be read
• bufSize- length, in bytes, of the buffer to be read Description
Reads from the specified buffer and writes to the tInfos buffer pointed to byinf.
38 Infofile Module
C Function List
Return Value
Returns the number of errors that were generated during the read and that are contained in the perrors list. If the value is (0) then no errors were generated, if the value is ( greater than 0 ) then there were syntax errors during the read, if the value is (less than 0) then there were access, i.e., hard errors during the read which caused the read to fail.
InfoWrite ()
Prototype
extern int InfoWrite (tInfos *inf, const char *filename);
Arguments
• inf - tInfos handle to the infofile buffer
• filename - name of the file to be written to Description
Writes the information contained in the tInfos bufferinfto the file specified byfilename.
Return Value
Returns -1 on failure, and 0 otherwise.
InfoListKeys ()
Prototype
char **InfoListKeys (tInfos *inf, const char *prefix, tIterKind kind);
typedef enum {
• inf - tInfos handle to the infofile buffer
• prefix - specified the key prefix to be matched when searching for keys
• kind - the kind of key that will be included in the list. Must be one of the following enum types: Keys, Subkeys, Unread_Keys, or All_Keys.
Description
Used to get a list of the keys that match the specified search criteria. Searching is done using the two argumentsprefixandkind. Prefix specifies a character string to match.
Kind specifies the key search type to be used. The following kinds are possible:
• Keys - Once the all keys are identified with the specified prefix, will list the key seg-ments that have a unique top level key segment. For example, if the prefix = AA, kind = Keys and the following list of key is used in a search:
AA.XX.11 AA.XX.22 AA.YY.11 AA.YY.22
39 Infofile Module
C Function List
... then, the keys that would match the search criteria would be AA.XX, AA.YY, AA.ZZ. The third part of the key will play no role in this case and would be truncated from the key name when shown in the list. The list returned would be:
AA.XX, AA.YY, AA.ZZ
• Subkeys - The same as Keys except the list will be generated without the prefix part listed and only the matching subkey portion. The same search as described before would then return:
XX, YY, ZZ
• Unread_Keys - Only those keys with the matching prefix that have not been accessed (read or write) will be included in the list.
• All_Keys - All keys with the matching prefix will be returned. The whole key name will be listed. for example, using the same table and prefix as was used before, the returned list would be:
AA.XX.11, AA.XX.22, AA.YY.11, AA.YY.22, AA.ZZ.11, AA.ZZ.22
Return Value
Returns a NULL terminated list of keys, i.e. an array of char arrays.
InfoKeyKind ()
Prototype
tKeyKind InfoKeyKind (tInfos *inf, const char *key);
typedef enum {
• inf - tInfos handle to the infofile buffer
• key - name of the key Description
Returns the type of value assigned to the specified key.
Return Value
The return value is an enum type that can be one of the following:
• No_Key - There is no key with the name specified
• Empty_Key - The key is not assigned a value
• String_Key - The key contains a string of data (i.e. the value is on a single line)
• Text_Key - The key contains text or a table of data (i.e. the value spans more than one line)
• Prefix_Key - The specified key is a prefix and not a complete key.
AA.ZZ.11 AA.ZZ.22
40 Infofile Module
C Function List
InfoDelKey ()
Prototype
int InfoDelKey (tInfos *inf, const char *key);
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key Description
Deletes the keys from the infofile buffer specified withinf that have the exact name as key.
Return Value
Returns 0 on success, -1 on failure.
InfoDelTree
Prototype
int InfoDelTree (tInfos *inf, const char *key);
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key Description
Deletes the keys from the infofile buffer specified withinfthat have the same root as (i.e.
begin with) key.
Return Value
Returns 0 on success, -1 on failure.
3.4.2 Read Functions
InfoGetStr ()
Prototype
int InfoGetStr (char **pval ,tInfos *inf, const char *key);
Arguments
• pval- pointer to the string that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read Description
Gets the string value ofkeylocated in the infofile buffer that is specfied with the handleinf.
41 Infofile Module
C Function List
Return Value
Returns 0 on success, -1 on failure.
InfoGetLong ()
Prototype
int InfoGetLong (long *pval, tInfos *inf, const char *key);
Arguments
• pval- pointer to the value of type long int that is read from the infofile buffer. The mem-ory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read Description
Gets the long int value ofkeylocated in the infofile buffer that is specfied with the handle inf.
Return Value
Returns 0 on success, -1 on failure.
InfoGetDbl ()
Prototype
int InfoGetDbl (double *pval ,tInfos *inf, const char *key);
Arguments
• pval- pointer to the value of type double that is read from the infofile buffer. The mem-ory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
Description
Gets the double value ofkeylocated in the infofile buffer that is specfied with the handle inf.
Return Value
Returns 0 on success, -1 on failure.
InfoGetTxt ()
Prototype
int InfoGetTxt (char ***pval ,tInfos *inf, const char *key);
42 Infofile Module
C Function List
Arguments
• pval - pointer to the text string value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
Description
Gets the text string value ofkeylocated in the infofile buffer that is specfied with the handle inf. Used to read key values that span multiple lines.
Return Value
Returns 0 on success, -1 on failure.
InfoGetStrDef ()
Prototype
int InfoGetStrDef (char **pval , tInfos *inf, const char *key, const char *def);
Arguments
• pval- pointer to the string value that is read from the infofile buffer. The memory asso-ciated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
• def - default key value
Description
Gets the string value ofkeylocated in the infofile buffer that is specfied with the handleinf.
If there is no value assigned to it then the default value will be used.
Return Value
Returns 0 on success, 1 if the key doesn’t exist and -1 on failure.
InfoGetLongDef ()
Prototype
int InfoGetLongDef(long *pval, tInfos *inf, const char *key, long def);
Arguments
• pval - pointer to the long int value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
• def - default key value
43 Infofile Module
C Function List
Description
Gets the long int value ofkeylocated in the infofile buffer that is specfied with the handle inf. If there is no value assigned to it then the default value will be used.
Return Value
Returns 0 on success, 1 if the key doesn’t exist and -1 on failure.
InfoGetDblDef ()
Prototype
int InfoGetDblDef (double *pval ,tInfos *inf, const char *key, double def);
Arguments
• pval - pointer to the double value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
• def - default key value
Description
Gets the double value ofkeylocated in the infofile buffer that is specfied with the handle inf. If there is no value assigned to it then the default value will be used.
Return Value
Returns 0 on success, 1 if the key doesn’t exist and -1 on failure.
InfoGetStrDef ()
Prototype
int InfoGetTxtDef (char ***pval, tInfos *inf, const char *key, char **def);
Arguments
• pval - pointer to the text string value that is read from the infofile buffer. The memory associated with this variable should NOT be freed by the user.
• inf - tInfos handle to the infofile buffer
• key - name of the key to read
• def - default key value
Description
Gets the text string value ofkeylocated in the infofile buffer that is specfied with the handle inf. Used to read key values that span multiple lines. If there is no value assigned to it then the default value will be used.
44 Infofile Module
C Function List
Return Value
Returns 0 on success, 1 if the key doesn’t exist and -1 on failure.
3.4.3 Write Functions
InfoSetStr ()
Prototype
int InfoSetStr(tInfos *inf, const char *key, const char *val);
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key to be set
• val - new string value to be written to the key
Description
Sets the value of the key. If the specified key does not exist then one will be created.
Return Value
Returns 0 on success, and -1 on failure.
InfoSetLong ()
Prototype
int InfoSetLong(tInfos *inf, const char *key, long val);
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key to be set
• val - new long int value to be written to the key
Description
Sets the value of the key. If the specified key does not exist then one will be created.
Return Value
Returns 0 on success, and -1 on failure.
InfoSetDbl ()
Prototype
int InfoSetDbl(tInfos *inf, const char *key, double val);
45 Infofile Module
C Function List
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key to be set
• val - new double value to be written to the key
Description
Sets the value of the key. If the specified key does not exist then one will be created.
Return Value
Returns 0 on success, and -1 on failure.
InfoSetTxt ()
Prototype
int InfoSetTxt(tInfos *inf, const char *key, char **val);
Arguments
• inf - tInfos handle to the infofile buffer
• key - name of the key to be set
• val - new text string value to be written to the key
Description
Sets the value of the key. If the specified key does not exist then one will be created.
Return Value
Returns 0 on success, and -1 on failure.
3.4.4 Add/Move Functions
InfoMoveKeyBefore ()
Prototype
int InfoMoveKeyBefore (tInfos *inf, const char *destkey, const char *key);
Arguments
• inf - tInfos handle to the infofile buffer
• destkey - name of the destination key used as a reference for the move
• key - name of the key to be moved
Description
Moves the key specified bykey directly before the key specified bydestkey.
46 Infofile Module
C Function List
Return Value
Returns 0 on success, and -1 on failure.
InfoMoveKeyBehind ()
Prototype
int InfoMoveKeyBehind (tInfos *inf, const char *destkey, const char *key);
Arguments
• inf - tInfos handle to the infofile buffer
• destkey - name of the destination key used as a reference for the move
• key - name of the key to be moved
Description
Moves the key specified bykey behind the key specified bydestkey.
Return Value
Returns 0 on success, and -1 on failure.
InfoAddLineBefore ()
Prototype
int InfoAddLineBefore (tInfos *inf, const char *destkey, const char *val);
Arguments
• inf - tInfos handle to the infofile buffer
• destkey - name of the destination key used as a reference for the line insertion
• val - character string to be inserted
Description
Used to insert a comment or a blank line before the key specified bydestkey.
Return Value
Returns 0 on success, and -1 on failure.
InfoAddLineBehind ()
Prototype
int InfoAddLineBehind (tInfos *inf, const char *destkey, const char *val);
Arguments
• inf - tInfos handle to the infofile buffer
47 Infofile Module
C Function List
• destkey - name of the destination key used as a reference for the line insertion
• val - character string to be inserted
Description
Used to insert a comment or a blank line behind the key specified bydestkey.
Return Value
Returns 0 on success, and -1 on failure.
3.4.5 Help Functions
InfoMakeKey ()
Prototype
char *InfoMakeKey (char **subKeys);
Arguments
• subKeys - list of keys to be concatinated
Description
Concatinates a list of subkeys into a single key. The subkeys will be seperated with dot oper-ators (i.e. a period).
Return Value
Returns the newly formed key, or a NULL pointer on failure. The value is static and therefore only valid until the next call to this function.
InfoSplitKey ()
Prototype
char **InfoSplitKey (const char *key);
Arguments
• key - key to be split
Description
Splits a key into it subkeys, deliniated with the dot operator (i.e. with a period).
Return Value
Returns the list of subkeys, or a NULL pointer on failure. The value is static and therefore only valid until the next call to this function.
48 Infofile Module
Tcl/Tk Procedure List
3.4.6 Additional Functions
InfoStrError ()
Prototype
const char *InfoStrError (void);
Arguments None
Description
Used to get the list of errors.
Return Value
Returns the list of errors