Reading and Writing Attributes

See also

Attributes in the Xentara user manual

Xentara plugin elements can publish certain data as attributes. Attributes can be resolved during loading using the resolver passed to the loadConfig() callback and then read using a xentara::data::ReadHandle, or written using a xentara::data::WriteHandle.

Getting a read and/or write handle to an attribute can be acheived in two ways:

1. During loading, the complete primary key of the attribute can be submitted to the resolver in loadConfig(), and the result stored in a xentara::model::AttributeReference. The read or write handle must then be fetched in prepare() using xentara::model::AttributeReference::readHandle() or xentara::model::AttributeReference::writeHandle().
2. Alternatively, the primary key of the element containing the attribute can be resolved in loadConfig(), and the result stored in an std::weak_ptr<xentara::model::GenericElement>. The read or write handle must then be resolved in prepare() using xentara::model::GenericElement::attributeReadHandle() or xentara::model::GenericElement::attributeWriteHandle(). This allows efficient access to multiple attributes of a single element.

To read the current value of the attribute, use xentara::data::ReadHandle::read(). This function returns a xentara::utils::eh::expected that either contains the value of the attribute, or an std::error_code. xentara::data::ReadHandle defines a custom error code enum called xentara::data::ReadHandle::Error, but standard error codes may be returned as well.

To write the value of the attribute, use xentara::data::WriteHandle::write(). This function takes the desired value of the attribute as a parameter and returns an std::error_code. xentara::data::WriteHandle defines a custom error code enum called xentara::data::WriteHandle::Error, but standard error codes may be returned as well. On success, a default constructed std::error_code

xentara::data::ReadHandle::Error and xentara::data::WriteHandle::Error are fully fletched C++ error code enum (see std::is_error_code_enum<::xentara::data::ReadHandle::Error> and std::is_error_code_enum<::xentara::data::WriteHandle::Error>). You can fetch the corresponding error categories by calling xentara::data::ReadHandle::Error::errorCategory() and xentara::data::WriteHandle::Error::errorCategory(), respectively. xentara::data::ReadHandle::Error and xentara::data::WriteHandle::Error can be implicitly converted to std::error_code, and you can create error codes using make_error_code(xentara::data::ReadHandle::Error) and make_error_code(xentara::data::WriteHandle::Error).

Some handles contain hard errors. Such handles can never return succeed, but will always return a specific hard-coded error code. If you call xentara::model::GenericElement::attributeReadHandle() or xentara::model::GenericElement::attributeReadHandle() with an attribute that the element does not know, for example, the returned handle will contain a hard error of xentara::data::ReadHandle::Error::Unknown or xentara::data::WriteHandle::Error::Unknown. If you call xentara::model::GenericElement::attributeWriteHandle() with a read only attribute, or xentara::model::GenericElement::attributeReadHandle() with a write only attribute, the returned handle will contain a hard error of xentara::data::WriteHandle::Error::ReadOnly or xentara::data::ReadHandle::Error::WriteOnly, respectively. You can determine whether a handle contains a hard error using the methods xentara::data::ReadHandle::hardError() and xentara::data::WriteHandle::hardError().