Basic Operations¶
This page shows the basic operations on tree nodes: reading and writing values, waiting for changes, converting nodes to and from JSON and handling API errors.
Note
Most snippets on this page omit error handling to keep them short. It is shown separately in the Handling API Errors section below.
Reading and Writing Nodes¶
Nodes in the JSON tree are read and written through C API functions like nxLibGetInt and nxLibSetInt.
The C++, Python and .NET wrappers provide the NxLibItem class, which makes access to tree nodes more convenient. An NxLibItem object references a path in the JSON tree. Indexing it with a string or an integer descends into a child node and returns another NxLibItem. For example NxLibItem()[itmCUDA] references the path /CUDA. Values are read with methods like asDouble() and written by the assignment operator (or with Set() in C#).
The example uses the CUDA node whose structure is described in the tree reference section.
// NxLibItem() without arguments references the tree's root node at path "/".
// Reference the CUDA node at path "/CUDA".
NxLibItem cuda = NxLibItem()[itmCUDA];
// Check whether a node exists before reading it.
if (!cuda[itmEnabled].exists()) {
return;
}
// Read a value from a node. This corresponds to the C function nxLibGetBool.
bool enabled = cuda[itmEnabled].asBool();
// Write a value to a node. The assignment operator writes the value to the node
// referenced by the NxLibItem. This corresponds to the C function nxLibSetBool,
// but there are overloads for other types.
cuda[itmEnabled] = true;
// Read the number of children of a node.
int deviceCount = cuda[itmDevices].count();
// Check whether a node exists before reading it. nxLibGetType returns
// NxLibItemTypeInvalid for non-existent nodes.
NXLIBINT type = nxLibGetType(&error, "/CUDA/Enabled");
if (type == NxLibItemTypeInvalid) {
return;
}
// Read a value from a node. Other nxLibGet* functions exist for other JSON types.
NXLIBBOOL enabled = nxLibGetBool(&error, "/CUDA/Enabled");
// Write a value to a node.
nxLibSetBool(&error, "/CUDA/Enabled", NXLIBTRUE);
// Read the number of children of a node.
NXLIBINT deviceCount = nxLibGetCount(&error, "/CUDA/Devices");
# NxLibItem() without arguments references the tree's root node at path "/".
# Reference the CUDA node at path "/CUDA".
cuda = NxLibItem()[ITM_CUDA]
# Check whether a node exists before reading it.
if not cuda[ITM_ENABLED].exists():
return
# Read a value from a node. This corresponds to the C function nxLibGetBool.
enabled = cuda[ITM_ENABLED].as_bool()
# Write a value to a node. This corresponds to the C function nxLibSetBool,
# but there are overloads for other types.
cuda[ITM_ENABLED] = True
# Read the number of children of a node.
device_count = cuda[ITM_DEVICES].count()
// new NxLibItem() without arguments references the tree's root node at
// path "/". Reference the CUDA node at path "/CUDA".
NxLibItem cuda = new NxLibItem()[NxLib.itmCUDA];
// Check whether a node exists before reading it.
if (!cuda[NxLib.itmEnabled].Exists()) {
return;
}
// Read a value from a node. This corresponds to the C function nxLibGetBool.
bool enabled = cuda[NxLib.itmEnabled].AsBool();
// Write a value to a node. This corresponds to the C function nxLibSetBool, but
// there are overloads for other types.
cuda[NxLib.itmEnabled].Set(true);
// Read the number of children of a node.
int deviceCount = cuda[NxLib.itmDevices].Count();
Converting Nodes to and from JSON¶
Any subtree can be serialized to a JSON string and written back. This is useful for storing and restoring settings or for exchanging data with other tools. The underlying C functions are nxLibGetJson and nxLibSetJson.
// Reference the CUDA node at path "/CUDA".
NxLibItem cuda = NxLibItem()[itmCUDA];
// Read a subtree as a JSON string. This corresponds to the C function nxLibGetJson.
std::string json = cuda.asJson();
// Write a subtree from a JSON string. This corresponds to the C API function
// nxLibSetJson. With onlyWriteableNodes = true, the function does not attempt to
// overwrite read-only nodes, which would otherwise return an error.
cuda.setJson(json, true);
// The << operator is a shorthand for setJson with onlyWriteableNodes enabled.
cuda << json;
// Read a subtree as a JSON string. The parameters are the path, whether to
// pretty print, the number precision and whether scientific notation is
// allowed.
char const* json = nxLibGetJson(&error, "/CUDA", NXLIBTRUE, 18, NXLIBFALSE);
// Write a subtree from a JSON string. With onlyWriteableNodes = NXLIBTRUE,
// the function does not attempt to overwrite read-only nodes, which would
// otherwise return an error.
nxLibSetJson(&error, "/CUDA", json, NXLIBTRUE);
# Reference the CUDA node at path "/CUDA".
cuda = NxLibItem()[ITM_CUDA]
# Read a subtree as a JSON string. This corresponds to the C function nxLibGetJson.
json_string = cuda.as_json()
# Write a subtree from a JSON string. This corresponds to the C API function
# nxLibSetJson. With only_writable_nodes=True, the function does not attempt to
# overwrite read-only nodes, which would otherwise return an error.
cuda.set_json(json_string, only_writable_nodes=True)
# The << operator is a shorthand for set_json with only_writable_nodes enabled.
cuda << json_string
// Reference the CUDA node at path "/CUDA".
NxLibItem cuda = new NxLibItem()[NxLib.itmCUDA];
// Read a subtree as a JSON string. This corresponds to the C function
// nxLibGetJson.
string json = cuda.AsJson();
// Write a subtree from a JSON string. This corresponds to the C API function
// nxLibSetJson. With onlyWriteableNodes = true, the function does not attempt
// to overwrite read-only nodes, which would otherwise return an error.
cuda.SetJson(json, true);
Handling API Errors¶
API errors happen when a read or write operation on a tree node fails. For example, this could happen when you try to read a non-existent node or try to modify a read-only node (like the camera’s serial number).
In the C API every function returns an error code, which nxLibTranslateReturnCode converts to a symbolic name. The language wrappers convert these error codes to exceptions by default although in C++ and .NET overloads returning the error codes also exist.
try {
// Accessing a non-existent node throws an NxLibException.
NxLibItem("this path does not exist").asDouble();
} catch (NxLibException& e) {
// The exception provides the error code, a text description and the
// path of the node that caused the error.
int errorCode = e.getErrorCode();
std::string errorText = e.getErrorText();
std::string itemPath = e.getItemPath();
}
// Accessing a non-existent node returns an error code.
NXLIBERR error;
double value = nxLibGetDouble(&error, "this path does not exist");
if (error != NxLibOperationSucceeded) {
// The error code can be translated into a text description.
char const* errorText = nxLibTranslateReturnCode(error);
}
try:
# Accessing a non-existent node raises an NxLibException.
NxLibItem("this path does not exist").as_double()
except NxLibException as e:
# The exception provides the error code, a text description and the
# path of the node that caused the error.
error_code = e.get_error_code()
error_text = e.get_error_text()
item_path = e.get_item_path()
try {
// Accessing a non-existent node throws an NxLibException.
new NxLibItem("this path does not exist").AsDouble();
} catch (NxLibException e) {
// The exception provides the error code, a text description and
// the path of the node that caused the error.
int errorCode = e.GetErrorCode();
string errorText = e.GetErrorText();
string itemPath = e.GetItemPath();
}
Waiting for Commands¶
The NxLib can block the calling thread until a node reaches a specific state. The most common use is waiting for a command to finish: the command is executed by a separate thread, which sets the Command node to null when it has finished. The underlying C function for this example is nxLibWaitForType; further variants exist for waiting for changes or specific values of a node.
NxLibItem()[itmExecute][itmDefault][itmCommand].waitForType(NxLibItemTypeNull, true);
nxLibWaitForType(&error, "/Execute/Default/Command", NxLibItemTypeNull, NXLIBTRUE);
NxLibItem()[ITM_EXECUTE][ITM_DEFAULT][ITM_COMMAND].wait_for_type(NXLIB_ITEM_TYPE_NULL, True)
new NxLibItem()[NxLib.itmExecute][NxLib.itmDefault][NxLib.itmCommand].WaitForType(NxLib.ItemTypeNull, true);