= Rappture C API =
== Summary: ==
{{{
#include "rappture.h";
}}}
'''!RpLibrary''' Class
This module provides an interface to Rappture I/O (!RpLibrary) library.
__'''Constructor'''__ [[BR]]
!RpLibrary* ''lib'' = '''rpLibrary(''' ''path'' ''')'''; [[BR]]
__'''Destructor'''__ [[BR]]
'''rpFreeLibrary(''' ''&lib'' ''')'''; [[BR]]
__'''Methods'''__ [[BR]]
int ''err'' = '''rpGetDouble(''' ''lib'', ''path'', ''retDVal'' ''')'''; [[BR]]
int ''err'' = '''rpGetString(''' ''lib'', ''path'', ''retCStr'' ''')'''; [[BR]]
int ''err'' = '''rpGetData(''' ''lib'', ''path'', ''retData'' ''')'''; [[BR]]
int ''err'' = '''rpPutString(''' ''lib'', ''path'', ''value'', ''append'' ''')'''; [[BR]]
int ''err'' = '''rpPutDouble(''' ''lib'', ''path'', ''value'', ''append'' ''')'''; [[BR]]
int ''err'' = '''rpPutData(''' ''lib'', ''path'', ''data'', ''nbytes'', ''append'' ''')'''; [[BR]]
int ''err'' = '''rpPutFile(''' ''lib'', ''path'', ''fileName'', ''compress'', ''append'' ''')'''; [[BR]]
int ''err'' = '''rpResult(''' ''lib'' ''')'''; [[BR]]
int ''err'' = '''rpElementAsType(''' ''lib'', ''path'', ''retCStr'' ''')'''; [[BR]]
int ''err'' = '''rpElementAsComp(''' ''lib'', ''path'', ''retCStr'' ''')'''; [[BR]]
int ''err'' = '''rpElementAsId(''' ''lib'', ''path'', ''retCStr'' ''')'''; [[BR]]
!RpLibrary* ''ele'' = '''rpElement(''' ''lib'', ''path'' ''')'''; [[BR]]
!RpLibrary* ''ele'' = '''rpElementAsObject(''' ''lib'', ''path'' ''')'''; [[BR]]
!RpLibrary* ''ele'' = '''rpChildren(''' ''lib'', ''path'', ''childEle'' ''')'''; [[BR]]
!RpLibrary* ''ele'' = '''rpChildrenByType(''' ''lib'', ''path'', ''childEle'', ''type'' ''')'''; [[BR]]
const char* ''retCstr'' = '''rpXml(''' ''lib'' ''')'''; [[BR]]
__'''Constants'''__ [[BR]]
RPLIB_OVERWRITE = 0 [[BR]]
RPLIB_APPEND = 1 [[BR]]
RPLIB_NO_TRANSLATE = 0 [[BR]]
RPLIB_TRANSLATE = 1 [[BR]]
RPLIB_NO_COMPRESS = 0 [[BR]]
RPLIB_COMPRESS = 1 [[BR]]
'''RpUnits''' Class [[BR]]
This module provides an interface to Rappture Units (!RpUnits) library.
__'''Static Methods'''__ [[BR]]
const char* ''tmpStr'' = '''rpConvertStr(''' ''fromVal'', ''toUnitsName'', ''showUnits'', ''result'' ''')'''; [[BR]]
double ''retDval'' = '''rpConvertDbl(''' ''fromVal'', ''toUnitsName'', ''result'' ''')'''; [[BR]]
'''!RpUtils''' Module [[BR]]
This module provides an interface to the Rappture Utils Module
__'''Static Methods'''__ [[BR]]
int '''rpUtilsProgress(''' ''percent'', ''message'' ''')'''; [[BR]]
------------------------------------------------------------------------------------- [[BR]]
Code Synopsis & Examples: [[BR]] [[BR]]
!RpLibrary* '''rpLibrary''' (char* ''path'')
Purpose:[[BR]]
Retrieve an object reference to the file pointed to by ''path'' for accessing member functions of Rappture. [[BR]]
Input Arguments: [[BR]]
1) char* ''path'' - non-null c style string providing the path to an xml file.[[BR]]
Return Value:[[BR]]
1) Pointer to a Rappture library (!RpLibrary) object.[[BR]]
Notes: [[BR]]
1) On success the return value will be a non-null !RpLibrary pointer. [[BR]]
2) ''path'' must be a non-null c-style string. [[BR]]
int '''rpFreeLibrary''' (!RpLibrary** ''lib'')
Purpose:[[BR]]
Free the Rappture Library object.[[BR]]
Input Arguments: [[BR]]
1) !RpLibrary** ''lib'' - Pointer to a Rappture library (!RpLibrary) object.[[BR]]
Return Value:[[BR]]
1) Integer error flag, 0 on success, 1 on error.[[BR]]
Notes: [[BR]]
1) On success the !RpLibrary pointer will be deleted and set to NULL. [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This function retrieves the data held at location ''path'' in the rappture object ''lib''. [[BR]]
After the function has been invoked, the contents of ''retCStr'' [[BR]]
will point to the returned value and an integer will be returned [[BR]]
by the function. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) const char** ''retCStr'' - returned data. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
Notes: [[BR]]
1) **''retCStr'' points to a temporary string containing the result.[[BR]]
2) The returned string should not be changed or free'd.[[BR]]
3) The value stored at the returned address is only guaranteed until the next call to this function.[[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This function retrieves the data held at location ''path'' in the Rappture object ''lib''. [[BR]]
After the function has been invoked, the contents of ''retDVal'' [[BR]]
will point to the returned value and an integer will be returned [[BR]]
by the function. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) double* ''retDVal'' - returned data. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
Notes: [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This function places the data from ''value'' into the location ''path'' [[BR]]
in the rappture object ''lib'' and returns an integer representing success. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. If the [[BR]]
''append'' flag is set to 0, then any data existing at ''path'' will be overwritten. [[BR]]
If the append flag, is set to 1, then data from ''value will be appended to existing [[BR]]
data at ''path''. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) const char* ''value'' - returned data. [[BR]]
4) int ''append'' - tells if data in ''value'' should be appended to existing data at ''path''. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
Notes: [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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
K300K300K10K
*/
}}}
int '''rpPutDouble''' (!RpLibrary* ''lib'', const char* ''path'', double ''value'', int append) [[BR]]
Purpose:[[BR]]
This function places the data from ''value'' into the location ''path'' [[BR]]
in the Rappture object ''lib'' and returns an integer representing success. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. If the [[BR]]
''append'' flag is set to 0, then any data existing at ''path'' will be overwritten. [[BR]]
If the append flag, is set to 1, then data from ''value will be appended to existing [[BR]]
data at ''path''. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) double ''value'' - data to place into xml node. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
Notes: [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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
K300K300K10.0004
*/
}}}
int '''rpResult''' (!RpLibrary* ''lib'') [[BR]]
Purpose:[[BR]]
This function writes the xml of the Rappture library ''lib'' [[BR]]
to a unique run.xml file on disk, and a signal is sent to the [[BR]]
rappture graphical user interface. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char** ''retCStr'' - xml DOM object path. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
2) A unique run.xml file is generated on disk. [[BR]]
Notes: [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This method searches the Rappture Library Object ''lib'' for the [[BR]]
node at the location described by ''path'' and returns its [[BR]]
component name, a concatenation of the type, id, and index. [[BR]]
After the function has been invoked, the contents of ''retCStr'' [[BR]]
will point to the returned value and an integer will be returned [[BR]]
by the function. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) const char* ''retCStr'' - node component name. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure. [[BR]]
Notes: [[BR]]
1) **''retCStr'' points to a temporary string containing the result.[[BR]]
2) The returned string should not be changed or free'd.[[BR]]
3) The value stored at the returned address is only guaranteed until the next call to this function.[[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This method searches the Rappture Library Object ''lib'' for the [[BR]]
node at the location described by ''path'' and returns its [[BR]]
type name. After the function has been invoked, the contents of ''retCStr'' [[BR]]
will point to the returned value and an integer will be returned [[BR]]
by the function. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) const char* ''retCStr'' - node type. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure.
Notes: [[BR]]
1) **''retCStr'' points to a temporary string containing the result.[[BR]]
2) The returned string should not be changed or free'd.[[BR]]
3) The value stored at the returned address is only guaranteed until the next call to this function.[[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This method searches the Rappture Library Object ''lib'' for the [[BR]]
node at the location described by ''path'' and returns its [[BR]]
id name. After the function has been invoked, the contents of ''retCStr'' [[BR]]
will point to the returned value and an integer will be returned [[BR]]
by the function. [[BR]]
If path is an empty string, the root of the node is used. ''lib'' [[BR]]
is a pointer representing the instance of the !RpLibrary object. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char* ''path'' - xml DOM object path. [[BR]]
3) const char* ''retCStr'' - node id. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure.
Notes: [[BR]]
1) **''retCStr'' points to a temporary string containing the result.[[BR]]
2) The returned string should not be changed or free'd.[[BR]]
3) The value stored at the returned address is only guaranteed until the next call to this function.[[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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'') [[BR]]
Purpose:[[BR]]
This function returns the xml of the provided library, ''lib'' [[BR]]
After a successful function call, **''retCStr'' will point to the [[BR]]
returned data. [[BR]]
Input Arguments: [[BR]]
1) !RpLibrary* ''lib'' - user reference to the Rappture library. [[BR]]
2) const char** ''retCStr'' - xml DOM object path. [[BR]]
Return Value: [[BR]]
1) 0 on success, all other values represent failure.
Notes: [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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:
K300K300K
*/
}}}
double '''rpConvertDbl''' (const char* ''fromVal'', const char* ''toUnitsName'', int* ''result'')
Purpose:[[BR]]
Convert the numeric value and units found in the string ''fromVal'' [[BR]]
to the units named in ''toUnitsName''. A double precision value is returned. [[BR]]
An error code is placed into ''result''. A value of 0 represents success, [[BR]]
any other value is failure. [[BR]]
Input Arguments: [[BR]]
1) const char* ''fromVal'' - String representing the numeric value and units you want to convert from. [[BR]]
2) const char* ''toUnitsName'' - String representing the name of the units you want to convert to. [[BR]]
3) int* ''result'' - Error flag to tell if conversion was successful or not. [[BR]]
Return Value: [[BR]]
The converted value is provided as the return value of the function. [[BR]]
An error code is returned via the result variable. An error code of 0 represents [[BR]]
success, any other value represents failure. [[BR]]
Notes: [[BR]]
For this function, units are not displayed in the resultant converted value returned by the function. [[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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:[[BR]]
Convert the numeric value and units found in the string ''fromVal'' [[BR]]
to the units named in ''toUnitsName''. The ''showUnits'' flag tells [[BR]]
whether to attach units onto the returned const char* value. An error [[BR]]
code is placed into ''result''. A value of 0 represents success, any [[BR]]
other value is failure. [[BR]]
Input Arguments: [[BR]]
1) const char* ''fromVal'' - String representing the numeric value and units you want ot convert from. [[BR]]
2) const char* ''toUnitsName'' - String representing the name of the units you want to convert to. [[BR]]
3) int ''showUnits'' - String representing the name of the units you want to convert to. [[BR]]
4) int* ''result'' - Error flag to tell if conversion was successful or not. [[BR]]
Return Value: [[BR]]
A const char* pointer is returned on function exit. The pointer does [[BR]]
not belong to the user, it is static and temporary. If the user wants [[BR]]
to keep the string, they are responsible for copying the contents of [[BR]]
the pointer to their allocated memory. The user should not modify or [[BR]]
delete the contents of the returned pointer. [[BR]]
Notes: [[BR]]
Units are always displayed in the return value ''retText''.[[BR]]
{{{
/*
Example contents of driver.xml file
K300K300K
*/
#include
#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
*/
}}}