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 );
Constants
RPLIB_OVERWRITE = 0
RPLIB_APPEND = 1
RPLIB_NO_TRANSLATE = 0
RPLIB_TRANSLATE = 1
RPLIB_NO_COMPRESS = 0
RPLIB_COMPRESS = 1
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 );
RpUtils Module
This module provides an interface to the Rappture Utils Module
Static Methods
int rpUtilsProgress( percent, message );
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:
1) char* path - non-null c style string providing the path to an xml file.
Return Value:
1) Pointer to a Rappture library (RpLibrary) object.
Notes:
1) On success the return value will be a non-null RpLibrary pointer.
2) path must be a non-null c-style string.
int rpFreeLibrary (RpLibrary lib)
Purpose:
Free the Rappture Library object.
Input Arguments:
1) RpLibrary lib - Pointer to a Rappture library (RpLibrary) object.
Return Value:
1) Integer error flag, 0 on success, 1 on error.
Notes:
1) On success the RpLibrary pointer will be deleted and set to NULL.
/*
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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) const char* value - returned data.
4) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) 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 concatenation 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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:
1) RpLibrary* lib - user reference to the Rappture library.
2) const char* path - xml DOM object path.
3) 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 library, lib
After a successful function call, retCStr will point to the
returned data.
Input Arguments:
1) RpLibrary* lib - user reference to the Rappture library.
2) 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:
1) const char* fromVal - String representing the numeric value and units you want to convert from.
2) const char* toUnitsName - String representing the name of the units you want to convert to.
3) 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:
1) const char* fromVal - String representing the numeric value and units you want ot convert from.
2) const char* toUnitsName - String representing the name of the units you want to convert to.
3) int showUnits - String representing the name of the units you want to convert to.
4) 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
*/
