dmi_resource_open

Synopsis

#include <opendmi/locale.h>

typedef struct dmi_resource dmi_resource_t;

dmi_resource_t *dmi_resource_open(const char *package, const void *data);

Description

The dmi_resource_open function opens a resource package, a set of ICU4C resource bundles holding the strings of a program in every language it is translated to, so that the program can look its strings up the way the library looks up printable names.

The package is embedded into the program rather than installed as a file. Bundles of the package are built from ICU4C resource sources, one <locale>.txt per locale and root.txt with the default strings, and are packaged by pkgdata into a data object which is linked into the program, e.g. by the add_resources() function of the OpenDMI build files. The data is then reachable as the <package>_dat symbol:

extern const char opendmi_dat[];

dmi_resource_t *resource = dmi_resource_open("opendmi", opendmi_dat);

The package is opened with the locale set by dmi_set_locale, and is reopened with the new one whenever the locale is changed. Locales with no bundle of their own fall back to a less specific locale, and to the root bundle at last, but never to the bundle of the locale of the environment. A package with no root bundle is opened only with the locales it has bundles for.

The package stays open until it is closed by dmi_resource_close. Strings are looked up in it by dmi_resource_string, and messages are formatted by dmi_resource_message.

Thread safety

Open packages are kept in a process-wide list, which the function changes, so it must not be called while other threads may use the library.

Parameters

package: Package name, the one passed to pkgdata --name when the package is built, e.g. opendmi for the strings of the command line tool. The data is registered with ICU4C under this name, which therefore has to be unique.
data: Package data, the <package>_dat symbol of the data object.

Return value

Returns a resource handle, or nullptr if an argument is nullptr, if ICU4C cannot be initialized or the data cannot be registered or opened, if memory is exhausted, or if the library is built without ICU4C support.

Programs are expected to leave their strings untranslated, rather than fail, when no handle is returned: the lookup functions accept a nullptr handle, and find no strings in it.

Errors

None: the function takes no context to raise errors in.