<?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) 2010, 2012, Oracle and/or its affiliates. All rights reserved.
-->

<section><title>Data</title>

<para>
All data returned, submitted to or obtained from <command>rad</command>
<acronym>API</acronym>s adheres to a strong typing system similar to
that defined by <citation>XDR</citation>.  This makes it simpler to
define interfaces that have precise semantics, and makes server
extensions (which are written in C) easier to develop.  Of course, the
rigidity of the typing exposed to an interface's consumer
is primarily a function of the client language and implementation.
</para>

    <section><title>Base Types</title>
    <para>
    <command>rad</command> supports the following base types:

	<variablelist>

	<varlistentry>
	<term><type>boolean</type></term>
	<listitem><para>
	A boolean value (i.e. true or false).
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>integer</type></term>
	<listitem><para>
	A 32-bit signed integer value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>uinteger</type></term>
	<listitem><para>
	A 32-bit unsigned integer value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>long</type></term>
	<listitem><para>
	A 64-bit signed integer value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>ulong</type></term>
	<listitem><para>
	A 64-bit unsigned integer value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>float</type></term>
	<listitem><para>
	A 32-bit floating-point value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>double</type></term>
	<listitem><para>
	A 64-bit floating-point value.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>string</type></term>
	<listitem><para>
	A UTF-8 string.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>opaque</type></term>
	<listitem><para>
	Raw binary data.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>secret</type></term>
	<listitem><para>
	An 8-bit clean <quote>character</quote> array.  The encoding is
	defined by the interface using the type.  Client/server
	implementations may take additional steps (e.g. zeroing buffers
	after use) to protect the contents of <type>secret</type>
	data.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>time</type></term>
	<listitem><para>
	An absolute <acronym>UTC</acronym> time value.
	<!-- XXX: Specify precision -->
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><type>name</type></term>
	<listitem><para>
	The name of an object in the <command>rad</command> namespace.
	</para></listitem>
	</varlistentry>

	</variablelist>
	</para>
    </section>

    <section><title>Derived Types</title>
    <para>
    In addition to the above types, <command>rad</command> supports
    several derived types.  
    </para>

    <para>
    An <type>enumeration</type> is a set of user-defined tokens.  Like
    C enumerations, <command>rad</command> enumerations may have
    specific integer values associated with them.  Unlike C
    enumerations, <command>rad</command> enumerations and integers are
    not interchangeable.  Among other things, this means that an
    enumeration data value may not take on values outside those defined
    by the enumeration.  This precludes the common but questionable
    practice of using enumerated types for bitfield values.
    </para>

    <para>
    <command>rad</command> enumerations support designating an optional
    <quote>fallback</quote> value.  A fallback value permits an
    enumeration to change without breaking compatibility between
    consumers and implementors of an <acronym>API</acronym> using
    different versions of the enumeration.  When supported by the
    programming environment in use, the connection between the consumer
    and the implementor will automatically map unrecognized enumeration
    data values to the fallback value.
    </para>

    <caution>
    Fallback values are indispensible in cases where the set of
    possible enumeration must change over time.  However, any change to
    an enumeration with a fallback value is considered to be a
    compatible change, forfeiting some of the benefits offered by
    <command>rad</command>'s versioning scheme.  Excessive use of
    fallback values will unnecessarily complicate the use and
    maintenance of a <command>rad</command> <acronym>API</acronym>.
    </caution>

    <para>
    A discriminated <type>union</type> is a data type, which can be 
    used to store polymorphic data, with typesafe access to the data.
    Like <citation>XDR</citation>, discriminated <type>union</type>'s 
    are composed of a set of <quote>arms</quote> and a 
    <quote>discriminant</quote> that selects an <quote>arm</quote>. 
    The <quote>discriminant</quote> may be a <type>boolean</type> or 
    an <type>enumeration</type> type. A default <quote>arm</quote> 
    may be specified for unions with an enumerated discriminator. 
    When no <quote>arm</quote> is defined for a specific 
    <quote>discriminant</quote> value, and no default 
    <quote>arm</quote> is defined, the <quote>arm</quote> for that 
    value is <type>void</type>.
    </para>

    <para>
    An <type>array</type> is an ordered list of data items of a fixed
    type.  <type>array</type>s do not have a pre-defined size.
    </para>

    <para>
    A <type>structure</type> is a record consisting of a fixed set of
    typed, uniquely-named fields.  A field's type may be a base type or
    derived type &mdash; even another structure type.
    </para>

    <para>
    Derived types offer almost unlimited flexibility.  There is,
    however, one important constraint imposed on derived types:
    recursive type references are prohibited.  Thus, complex
    self-referencing data types (e.g. linked lists or trees) must be
    communicated after being mapped into simpler forms.
    </para>
    </section>

    <section><title>Optional Data</title>
    <para>
    In some situations, data may be declared as nullable.  Nullable data
    can take on a <quote>non-value</quote> (e.g.  <literal>NULL</literal> 
    in C, or <literal>null</literal> in Java).  Inversely, non-nullable 
    data cannot be <literal>NULL</literal>.  Only data of type <type>opaque</type>,
    <type>string</type>, <type>secret</type>, <type>array</type>, 
    <type>union</type> or <type>structure</type> may be declared nullable.  
    Additionally, only <type>structure</type> fields and certain 
    <acronym>API</acronym> (see below) types can be nullable.  
    Specifically, <type>array</type> 
    data cannot be nullable (the <type>array</type> type is actually more
    like a list than an array).
    </para>
    </section>

</section>