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();

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;

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();
}

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);