radadrgen-Generated Definitions

Whether you are using libadr in a C-based client or as part of writing a rad server module, you will need to understand the data definitions generated by radadrgen. Fortunately, the definitions are the same in both environments.

Running radadrgen

radadrgen is instructed to produce definitions for C/libadrconsumers by using its -c option, as shown in the following example.

Example 4-5 Invoking radadrgen

$ radadrgen -c output_dir example.xml

The -c option produces two files, api_APINAME.h and api_APINAME_impl.c in the output_dir, where APINAME is the value of the name attribute of the API document's api element. api_APINAME_impl.c contains the implementation of the interfaces and data types defined by the API. It should be compiled and linked with the software needing those definitions.

api_APINAME.h externs the specific symbols defined by api_APINAME_impl.c that consumers will need to reference, and should be #included by those consumers. api_APINAME.h contains no data definitions itself and may be included in as many places as necessary. The definitions api_APINAME_impl.c are 100% data and are statically initialized. There are no initialization functions to be called. Neither file should be modified.

For each derived type TYPE, whether enumeration or structure, defined in the API, a adr_type_t named t__TYPE (two underscores) representing that type is generated and externed by the header file. If an array of that type is used anywhere in the API, a adr_type_t named t_array__TYPE (one underscore, two underscores) representing that array type is generated and externed. For each interface INTERFACE defined in the file, an adr_object_t named interface_INTERFACE is defined and externed.

For each value VALUE of an enumeration named TYPE , a adr_data_t named e__TYPE_VALUE is defined and externed. These adr_data_t values are marked as constants and are not affected by adr_data_ref or adr_data_free.

Example radadrgen output

When radadrgen is run on the Example 3-10 given in the ADR chapter two files result. One, api_example_impl.c, holds the implementation of the GrabBag interface and data types it depends on, and should be simply be compiled and linked with the GrabBag consumer. The other, api_example.h, exposes only the relevant symbols defined by api_example_impl.c and should be included by consumers of the GrabBag interface and its related types as shown in the following example.

Example 4-6 Sample radadrgen-Generated C Header File

#include <rad/adr.h>
#include <rad/adr_object.h>

extern adr_type_t t__Mood;
extern adr_data_t e__Mood_IRREVERENT;
extern adr_data_t e__Mood_MAUDLIN;
extern adr_type_t t__SqrtError;
extern adr_type_t t__StringInfo;
extern adr_type_t t__MoodStatus;
extern adr_object_t interface_GrabBag;

The function of api_GrabBag is discussed later in this document, but the purpose of the other definitions in this file should be clear. A consumer needing to create a MoodStatus structure indicating the mood is IRREVERENT and has changed would issue the instructions shown in the following example.

Example 4-7 Consuming radadrgen-Generated Definitions

status = adr_data_new_struct(&t__MoodStatus);
adr_struct_set(status, "mood", e__Mood_IRREVERENT);
/* adr_struct_set(status, "mood", adr_data_new_enum_byname(&t__Mood, "IRREVERENT")); */
adr_struct_set(status, "changed", adr_data_new_boolean(B_TRUE));

if (!adr_data_verify(status, NULL, B_TRUE)) {
        ...

In addition to showing how to use the type definitions, this example also illustrates the multiple ways of referencing an enumerated value. Using the defined symbols is faster and can be checked by the compiler. The commented-out line uses adr_data_new_enum_byname which offers flexibility that could be useful in some situations but necessarily defers error checking until runtime. For example, if the programmer mistyped the value “IRREVERENT”, it would not be detected until the code was run. Obviously, using the enumerated value symbols when possible is preferable.