<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
  PDL HEADER START

  Public Documentation License Notice

  The contents of this Documentation are subject to the Public
  Documentation License Version 1.01 (the "License"); you may only
  use this Documentation if you comply with the terms of this License.
  A copy of the License is available at
  http://www.opensolaris.org/os/community/documentation/license.

  PDL HEADER END

  Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
-->

<section xmlns:xi="http://www.w3.org/2001/XInclude">
<title><command>radadrgen</command>-generated definitions</title>
<para>
Whether you are using <filename class='libraryfile'>libadr</filename>
in a C-based client or as part of writing a <command>rad</command>
server module, you will need to understand the data definitions
generated by <command>radadrgen</command>.  Fortunately, the definitions
are the same in both environments.
</para>

    <section><title>Running <command>radadrgen</command></title>
    <para>
    <command>radadrgen</command> is instructed to produce definitions for
    C/<filename class='libraryfile'>libadr</filename> consumers by
    using its <option>-c</option> option.  e.g.
    </para>

<example><title>Invoking <command>radadrgen</command></title>
<programlisting>
$ radadrgen -c . example.xml
</programlisting>
</example>

    <para>
    The <option>-c</option> option produces two files,
    <filename>api_APINAME.h</filename> and
    <filename>api_APINAME_impl.c</filename>, where APINAME is the
    value of the <sgmltag class='attribute'>name</sgmltag> attribute of
    the <acronym>API</acronym> document's <sgmltag 
    class='element'>api</sgmltag> element.
    <filename>api_APINAME_impl.c</filename> contains the
    implementation of the interfaces and data types
    defined by the <acronym>API</acronym>.  It should be compiled and
    linked with the software needing those definitions.
    <filename>api_APINAME.h</filename> externs the specific symbols
    defined by <filename>api_APINAME_impl.c</filename> that consumers
    will need to reference, and should be #included by those
    consumers.  <filename>api_APINAME.h</filename> contains no data
    definitions itself and may be included in as many places as
    necessary.  The definitions
    <filename>api_APINAME_impl.c</filename> are 100% data and are
    statically initialized.  There are no initialization functions to
    be called.  Neither file should be modified.
    </para>

    <para>
    For each derived type TYPE (be it <type>enumeration</type> or
    <type>structure</type>) defined in the <acronym>API</acronym>, a
    <type>type_t</type> named <symbol>t__TYPE</symbol> (two
    underscores) representing that type is generated and externed by
    the header file.  If an array of that type is used anywhere in the
    <acronym>API</acronym>, a <type>type_t</type> named
    <symbol>t_array__TYPE</symbol> (one underscore, two underscores)
    representing that array type is generated and externed.  For each
    interface, INTERFACE defined in the file, an
    <type>adr_object_t</type> named <symbol>interface_INTERFACE</symbol> is
    defined and externed.
    </para>

    <para>
    For each value VALUE of an <type>enumeration</type> named TYPE, a
    <type>data_t</type> named <symbol>e__TYPE_VALUE</symbol> is defined
    and externed.  These <type>data_t</type>s are marked as constants
    and are not affected by <function>data_ref</function> or
    <function>data_free</function>.
    </para>
    </section>

    <section><title>Example <command>radadrgen</command> output</title>
    <para>
    When we run <command>radadrgen</command> on the example given in the
    <acronym>ADR</acronym> chapter (see <xref linkend="adr.idl.example"
    />), we get two files.  One,
    <filename>api_example_impl.c</filename>, 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, <filename>api_example.h</filename>, exposes
    only the relevant symbols defined by
    <filename>api_example_impl.c</filename> and should be included by
    consumers of the <type>GrabBag</type> interface and
    its related types:
    </para>

<example>
<title>Sample <command>radadrgen</command>-generated C header file</title>
<programlisting>
<xi:include parse="text" href="api_example.h" />
</programlisting>
</example>

    <para>
    Though the function of <symbol>api_GrabBag</symbol> won't be
    discussed until the chapters on <command>rad</command> client
    programming and module development, the purpose of the other
    definitions in this file should be clear.  A consumer needing to
    create a <type>MoodStatus</type> structure indicating the
    <symbol>mood</symbol> is <constant>IRREVERENT</constant> and has
    changed would do the following:
    </para>

<example>
<title>Consuming <command>radadrgen</command>-generated definitions</title>
<programlisting><![CDATA[
status = data_new_struct(&t__MoodStatus);
struct_set(status, "mood", e__Mood_IRREVERENT);
/* struct_set(status, "mood", data_new_enum_byname(&t__Mood, "IRREVERENT")); */
struct_set(status, "changed", data_new_boolean(B_TRUE));

if (!data_verify(struct, NULL, B_TRUE)) {
        ...
]]></programlisting>
</example>

    <para>
    In addition to showing how to use the type definitions, this also
    illustrates the multiple ways of referencing an enumerated value.
    Using the defined symbols, as implemented above, is faster and can
    be checked by the compiler.  The commented out line uses
    <function>data_new_enum_byname</function> which offers flexibility
    that could be useful in some situations but necessarily defers
    error checking until runtime.  e.g. if the programmer mistyped the
    value <quote>IRREVERENT</quote> it wouldn't be detected until the
    code was run (if they were fortunate, in testing).  Obviously, it
    is preferable to use the enumerated value symbols when possible.
    </para>
    </section>

</section>