| Version 7 (modified by dkearney, 17 years ago) (diff) |
|---|
Rappture C API
Summary:
#include "rappture.h";
RpLibrary? Class
This module provides an interface to Rappture I/O (RpLibrary) library.
Constructor
RpLibrary?* lib = rpLibrary( path );
Destructor
rpFreeLibrary( lib );
Methods
int err = rpGetDouble( lib, path, retDVal );
int err = rpGetString( lib, path, retCStr );
int err = rpGetData( lib, path, retData );
int err = rpPutString( lib, path, value, append );
int err = rpPutDouble( lib, path, value, append );
int err = rpPutData( lib, path, data, nbytes, append );
int err = rpPutFile( lib, path, fileName, compress, append );
int err = rpResult( lib );
int err = rpElementAsType( lib, path, retCStr );
int err = rpElementAsComp( lib, path, retCStr );
int err = rpElementAsId( lib, path, retCStr );
RpLibrary?* ele = rpElement( lib, path );
RpLibrary?* ele = rpElementAsObject( lib, path );
RpLibrary?* ele = rpChildren( lib, path, childEle );
RpLibrary?* ele = rpChildrenByType( lib, path, childEle, type );
const char* retCstr = rpXml( lib );
RpUnits Class
This module provides an interface to Rappture Units (RpUnits) library.
Static Methods
const char* tmpStr = rpConvertStr( fromVal, toUnitsName, showUnits, result );
double retDval = rpConvertDbl( fromVal, toUnitsName, result );
Code Synopsis & Examples:
RpLibrary?* rpLibrary (char* path)
Purpose:
Retrieve an object reference to the file pointed to by path for accessing member functions of Rappture
Input Arguments:
- char* path - non-null c style string providing the path to an xml file
Return Value:
Pointer to a Rappture library (RpLibrary?) object
Notes:
- On success the return value will be a non-null RpLibrary? pointer
- path must be a non-null c-style string
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main() {
RpLibrary* lib
const char* comp = NULL;
int retVal = 0;
lib = rpLibrary("driver.xml")
if (lib != NULL) {
printf("creation of library successful\n");
}
else {
printf("creation of library failed\n");
}
printf ("lib = %x\n",(unsigned int)(lib));
rpFreeLibrary(lib);
return 0;
}
/*
Result:
creation of library successful
lib = 80502d0
*/
int rpGetString (RpLibrary?* lib, const char* path, const char retCStr)
Purpose:
This function retrieves the data held at location path in the rappture object lib.
After the function has been invoked, the contents of retCStr
will point to the returned value and an integer will be returned
by the function.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- const char* retCStr - returned data.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
1) retCStr points to a temporary string containing the result.
2) The returned string should not be changed or free'd.
3) The value stored at the returned address is only guaranteed until the next call to this function
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
const char* retCStr = NULL;
const char* path = "input.number(temperature).current";
int err = 0;
lib = rpLibrary("driver.xml");
err = rpGetString(lib,path,&retCStr);
if (retCStr != NULL) {
printf("rpGetString successful\n");
printf("retCStr = %s\n", retCStr);
}
else {
printf("rpGetString failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
rpGetString successful
retCStr = 300K
*/
int rpGetDouble (RpLibrary?* lib, const char* path, double* retDVal)
Purpose:
This function retrieves the data held at location path in the rappture object lib.
After the function has been invoked, the contents of retDVal
will point to the returned value and an integer will be returned
by the function.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- double* retDVal - returned data.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
double retDVal = 0.00;
const char* path = "input.number(temperature).current";
int err = 0;
lib = rpLibrary("driver.xml");
err = rpGetDouble(lib,path,&retDVal);
if (err == 0) {
printf("rpGetDouble successful\n");
printf("retDVal = %s\n", retDVal);
}
else {
printf("rpGetDouble failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
rpGetDouble successful
retStr = 300
*/
int rpPutString (RpLibrary?* lib, const char* path, const char* value, int append)
Purpose:
This function places the data from value into the location path
in the rappture object lib and returns an integer representing success.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object. If the
append flag is set to 0, then any data existing at path will be overwritten.
If the append flag, is set to 1, then data from value will be appended to existing
data at path.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- const char* value - returned data.
- int append - tells if data in value should be appended to existing data at path
Return Value:
1) 0 on success, all other values represent failure.
Notes:
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
const char* retCStr = NULL;
const char* path = "input.number(temperature).min";
int err = 0;
lib = rpLibrary("driver.xml");
err = rpPutString(lib,path,"10K",0);
if (err == 0) {
printf("rpPutString successful\n");
rpXml(lib, &retCStr);
if (retCStr != NULL) {
printf("%s\n",retCStr);
}
}
else {
printf("rpPutString failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
rpPutString successful
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
<min>10K</min>
</number>
</input>
</run>
*/
int rpPutDouble (RpLibrary?* lib, const char* path, double value, int append)
Purpose:
This function places the data from value into the location path
in the rappture object lib and returns an integer representing success.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object. If the
append flag is set to 0, then any data existing at path will be overwritten.
If the append flag, is set to 1, then data from value will be appended to existing
data at path.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- double value - data to place into xml node.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
double value = 10.004;
const char* retCStr = NULL;
const char* path = "input.number(temperature).min";
int err = 0;
lib = rpLibrary("driver.xml")
err = rpPutDouble(lib,path,value,0);
if (err == 0) {
printf("rpPutDouble successful\n");
rpXml(lib, &retCStr);
if (retCStr != NULL) {
printf("%s\n",retCStr);
}
}
else {
printf("rpPutDouble failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
rpPutDouble successful
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
<min>10.0004</min>
</number>
</input>
</run>
*/
int rpResult (RpLibrary?* lib)
Purpose:
This function writes the xml of the rappture library lib
to a unique run.xml file on disk, and a signal is sent to the
rappture graphical user interface.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char retCStr - xml DOM object path.
Return Value:
1) 0 on success, all other values represent failure. 2) A unique run.xml file is generated on disk.
Notes:
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
int err = 0;
lib = rpLibrary("driver.xml");
err = rpResult(lib,&retCStr);
if (err == 0) {
printf("rpResult was successful\n");
}
else {
printf("rpResult failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
rpResult was successful
a unique run.xml file is created on disk.
signal sent to gui stating processing has completed.
*/
int rpElementAsComp (RpLibrary?* lib, const char* path, const char retCStr)
Purpose:
This method searches the Rappture Library Object lib for the
node at the location described by path and returns its
component name, a concatination of the type, id, and index.
After the function has been invoked, the contents of retCStr
will point to the returned value and an integer will be returned
by the function.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- const char* retCStr - node component name.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
1) retCStr points to a temporary string containing the result.
2) The returned string should not be changed or free'd.
3) The value stored at the returned address is only guaranteed until the next call to this function
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main() {
RpLibrary* lib
const char* comp = NULL;
int retVal = 0;
lib = rpLibrary("driver.xml")
path = "input.number(temperature)"
retVal = rpElementAsComp(lib,path,&comp);
printf("comp = %s\n",comp);
rpFreeLibrary(lib);
return 0;
}
/*
Result:
comp = number(temperature)
*/
int rpElementAsType (RpLibrary?* lib, const char* path, const char retCStr)
Purpose:
This method searches the Rappture Library Object lib for the
node at the location described by path and returns its
type name. After the function has been invoked, the contents of retCStr
will point to the returned value and an integer will be returned
by the function.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- const char* retCStr - node type.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
1) retCStr points to a temporary string containing the result.
2) The returned string should not be changed or free'd.
3) The value stored at the returned address is only guaranteed until the next call to this function
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib
const char* typeName = NULL;
int retVal = 0;
lib = rpLibrary("driver.xml")
path = "input.number(temperature)"
retVal = rpElementAsType(lib,path,&typeName);
printf("type = %s\n",typeName);
rpFreeLibrary(lib);
return 0;
}
/*
Result:
type = number
*/
int rpElementAsId (RpLibrary?* lib, const char* path, const char retCStr)
Purpose:
This method searches the Rappture Library Object lib for the
node at the location described by path and returns its
id name. After the function has been invoked, the contents of retCStr
will point to the returned value and an integer will be returned
by the function.
If path is an empty string, the root of the node is used. lib
is a pointer representing the instance of the RpLibrary? object.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char* path - xml DOM object path.
- const char* retCStr - node id.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
1) retCStr points to a temporary string containing the result.
2) The returned string should not be changed or free'd.
3) The value stored at the returned address is only guaranteed until the next call to this function
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib
const char* id = NULL;
int retVal = 0;
lib = rpLibrary("driver.xml");
path = "input.number(temperature)";
retVal = rpElementAsId(lib,path,&id);
printf("id = %s\n",id);
rpFreeLibrary(lib);
return 0;
}
/*
Result:
id = temperature
*/
int rpXml (RpLibrary?* lib, const char retCStr)
Purpose:
This function returns the xml of the provided libraryi, lib
After a successfun function call, retCStr will point to the
returned data.
Input Arguments:
- RpLibrary?* lib - user reference to the Rappture library.
- const char retCStr - xml DOM object path.
Return Value:
1) 0 on success, all other values represent failure.
Notes:
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
const char* retCStr = NULL;
int err = 0;
lib = rpLibrary("driver.xml");
err = rpXml(lib,&retCStr);
if ((err == 0) && (retCStr != NULL)) {
printf("%s\n",retCStr);
}
else {
printf("rpXml failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
double rpConvertDbl (const char* fromVal, const char* toUnitsName, int* result)
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. A double precision value is returned. An error code is placed into result. A value of 0 represents success, any other value is failure.
Input Arguments:
- const char* fromVal - String representing the numeric value and units you want to convert from.
- const char* toUnitsName - String representing the name of the units you want to convert to.
- int* result - Error flag to tell if conversion was successful or not.
Return Value:
The converted value is provided as the return value of the function. An error code is returned via the result variable. An error code of 0 represents success, any other value represents failure.
Notes:
For this function, units are not displayed in the resultant converted value returned by the function.
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
const char* data = NULL;
double T = 0.0;
int err = 0;
lib = rpLibrary("driver.xml");
rpGetString(lib,"input.(temperature).current",&data);
T = rpConvertDbl(data, "F", &err);
if (err == 0) {
printf("T = %g\n", T);
}
else {
printf("rpConvertDbl failed\n");
}
T = rpConvertDbl("78F", "K", &err);
if (err == 0) {
printf("T = %g\n", T);
}
else {
printf("rpConvertDbl failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
T = 80.33
T = 298.706
*/
const char* rpConvertStr (const char* fromVal, const char* toUnitsName, int showUnits, int* result)
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. The showUnits flag tells whether to attach units onto the returned const char* value. An error code is placed into result. A value of 0 represents success, any other value is failure.
Input Arguments:
- const char* fromVal - String representing the numeric value and units you want ot convert from.
- const char* toUnitsName - String representing the name of the units you want to convert to.
- int showUnits - String representing the name of the units you want to convert to.
- int* result - Error flag to tell if conversion was successful or not.
Return Value:
A const char* pointer is returned on function exit. The pointer does not belong to the user, it is static and temporary. If the user wants to keep the string, they are responsible for copying the contents of the pointer to their allocated memory. The user should not modify or delete the contents of the returned pointer.
Notes:
Units are always displayed in the return value retText
/*
Example contents of driver.xml file
<run>
<input>
<number id="temperature">
<units>K</units>
<default>300K</default>
<current>300K</current>
</number>
</input>
</run>
*/
#include <stdio.h>
#include "rappture.h"
int main () {
RpLibrary* lib = NULL;
const char* data = NULL;
const char* T = NULL;
int err = 0;
lib = rpLibrary("driver.xml");
rpGetString(lib,"input.(temperature).current",&data);
T = rpConvertStr(data, "F", RPUNITS_UNITS_OFF, &err);
if (err == 0) {
printf("T = %s\n", T);
}
else {
printf("rpConvertDbl failed\n");
}
T = rpConvertStr("78F", "K", RPUNITS_UNITS_ON, &err);
if (err == 0) {
printf("T = %s\n", T);
}
else {
printf("rpConvertDbl failed\n");
}
rpFreeLibrary(lib);
return 0;
}
/*
Result:
T = 80.33
T = 298.706K
*/
