dmi_resource_string

Synopsis

#include <opendmi/locale.h>

const char *dmi_resource_string(dmi_resource_t *resource, const char *table, const char *key);

Description

The dmi_resource_string function looks up the string key of the table table of a resource package, in the locale the package is opened with.

Strings of a table are converted to UTF-8 on the first lookup in it, and are kept until the locale is changed or the package is closed. Tables which the package does not have are remembered as empty ones, so a lookup of a missing string is cheap as well.

Strings of a table are taken from a single bundle: a string which the table of the locale leaves out is not taken from the same table of a less specific locale, nor from the root bundle. Callers are expected to fall back to a text of their own, usually the untranslated one, when no string is found:

const char *text = dmi_resource_string(resource, "text", "Handle");

puts(text != nullptr ? text : "Handle");

The string belongs to the package, and must not be freed. It is valid until the locale is changed by dmi_set_locale, or the package is closed by dmi_resource_close.

Parameters

resource: Resource handle, or nullptr, in which case no string is found.
table: Path of the table holding the string: the name of a top-level table, e.g. a name set code, or names of nested tables separated by slashes, e.g. processor/attributes. A path with a name of 64 bytes or longer finds no table.
key: Key of the string within the table.

Return value

Returns the string in UTF-8, or nullptr if there is no such string, if an argument is nullptr, if memory is exhausted, or if the library is built without ICU4C support.

Errors

DMI_ERROR_ARGUMENT_NULL: Raised if table or key is nullptr. The function takes no context, so the error reaches no error queue. A resource of nullptr is not an error.