<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book [
<!ENTITY % eclent SYSTEM "../ecl.ent">
%eclent;
]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <reference xml:id="uffi.aggregates">
  <title>Aggregate Types</title>
  <partintro>
   <title>Overview</title>
   <para>
    Aggregate types are comprised of one or more primitive types.
   </para>
  </partintro>

  <refentry xml:id="uffi.def-enum">
   <refnamediv>
    <refname><function>def-enum</function></refname>
    <refpurpose>Defines a &C; enumeration.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>def-enum</function> <replaceable>name fields &amp;key separator-string</replaceable>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A symbol that names the enumeration.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>fields</parameter></term>
      <listitem>
       <para>A list of field defintions. Each definition can be
       a symbol or a list of two elements. Symbols get assigned a value of the
       current counter which starts at <computeroutput>0</computeroutput> and
       increments by <computeroutput>1</computeroutput> for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second
       position is the value to assign the the symbol. The current counter gets set
       to <computeroutput>1+</computeroutput> this value.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>separator-string</parameter></term>
      <listitem>
       <para>A string that governs the creation of constants. The
       default is <computeroutput>"#"</computeroutput>.</para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Declares a &C; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
     values are created by the <function>concatenation</function> of the
     enumeration name, separator-string, and field symbol. Also creates
     a foreign type with the name <parameter>name</parameter> of type
     <constant>:int</constant>.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-enum abc (:a :b :c)) 
;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
;; the foreign type "abc" to be :int

(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
;; the foreign type efoo to be :int</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Creates a :int foreign type, defines constants.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>


  <refentry xml:id="uffi.def-struct">
   <refnamediv>
    <refname><function>def-struct</function></refname>
    <refpurpose>Defines a &C; structure.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>def-struct</function> <replaceable>name &amp;rest fields</replaceable>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A symbol that names the structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>fields</parameter></term>
      <listitem>
       <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Declares a structure. A special type is available as a slot
     in the field. It is a pointer that points to an instance of the parent
     structure. It's type is <constant>:pointer-self</constant>.

    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-struct foo (a :unsigned-int) 
  (b (* :char)) 
  (c (:array :int 10)) 
  (next :pointer-self))</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Creates a foreign type.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>


  <refentry xml:id="uffi.get-slot-value">
   <refnamediv>
    <refname><function>get-slot-value</function></refname>
    <refpurpose>Retrieves a value from a slot of a structure.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>obj</parameter></term>
      <listitem>
       <para>A pointer to foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>type</parameter></term>
      <listitem>
       <para>A name of the foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>field</parameter></term>
      <listitem>
       <para>A name of the desired field in foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><returnvalue>value</returnvalue></term>
      <listitem>
       <para>The value of the field in the structure.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Accesses a slot value from a structure. This is generalized
     and can be used with <function>setf</function>.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(get-slot-value foo-ptr 'foo-structure 'field-name)
(setf (get-slot-value foo-ptr 'foo-structure 'field-name) 10)</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>

  <refentry xml:id="uffi.get-slot-pointer">
   <refnamediv>
    <refname><function>get-slot-pointer</function></refname>
    <refpurpose>Retrieves a pointer from a slot of a structure.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>obj</parameter></term>
      <listitem>
       <para>A pointer to foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>type</parameter></term>
      <listitem>
       <para>A name of the foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>field</parameter></term>
      <listitem>
       <para>A name of the desired field in foreign structure.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><returnvalue>pointer</returnvalue></term>
      <listitem>
       <para>The value of the field in the structure.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     This is similar to <function>get-slot-value</function>. It
     is used when the value of a slot is a pointer type.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>


  <refentry xml:id="uffi.def-array-pointer">
   <refnamediv>
    <refname><function>def-array-pointer</function></refname>
    <refpurpose>Defines a pointer to a array of type.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>def-array-pointer</function> <replaceable>name type</replaceable>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A name of the new foreign type.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>type</parameter></term>
      <listitem>
       <para>The foreign type of the array elements.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Defines a type tat is a pointer to an array of type.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-array-pointer byte-array-pointer :unsigned-char)</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Defines a new foreign type.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>


  <refentry xml:id="uffi.deref-array">
   <refnamediv>
    <refname><function>deref-array</function></refname>
    <refpurpose>Deference an array.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>deref-array</function> <replaceable>array type position</replaceable> => <returnvalue>value</returnvalue>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>array</parameter></term>
      <listitem>
       <para>A foreign array.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>type</parameter></term>
      <listitem>
       <para>The foreign type of the array.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>position</parameter></term>
      <listitem>
       <para>An integer specifying the position to retrieve from
       the array.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><returnvalue>value</returnvalue></term>
      <listitem>
       <para>The value stored in the position of the array.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Dereferences (retrieves) the value of an array element.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-array-pointer ca :char)
  (let ((fs (convert-to-foreign-string "ab")))
    (values (null-char-p (deref-array fs 'ca 0))
    (null-char-p (deref-array fs 'ca 2))))
=> &nil;
   &t;</screen>
   </refsect1>
   <refsect1>
    <title>Notes</title>
    <para>
     The TYPE argument is ignored for CL implementations other than
     AllegroCL. If you want to cast a pointer to another type use
     WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
    </para>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>

  <refentry xml:id="uffi.def-union">
   <refnamediv>
    <refname><function>def-union</function></refname>
    <refpurpose>Defines a foreign union type.
    </refpurpose>
    <refclass>Macro</refclass>
   </refnamediv>
   <refsynopsisdiv>
    <title>Syntax</title>
    <synopsis>
     <function>def-union</function> <replaceable>name &amp;rest fields</replaceable>
    </synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Arguments and Values</title>
    <variablelist>
     <varlistentry>
      <term><parameter>name</parameter></term>
      <listitem>
       <para>A name of the new union type.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>fields</parameter></term>
      <listitem>
       <para>A list of fields of the union.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
   <refsect1>
    <title>Description</title>
    <para>
     Defines a foreign union type.
    </para>
   </refsect1>
   <refsect1>
    <title>Examples</title>
    <screen>
(def-union test-union
  (a-char :char)
  (an-int :int))

(let ((u (allocate-foreign-object 'test-union)))
  (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
  (prog1 
     (ensure-char-character (get-slot-value u 'test-union 'a-char))
   (free-foreign-object u)))
=> #\A</screen>
   </refsect1>
   <refsect1>
    <title>Side Effects</title>
    <para>Defines a new foreign type.</para>
   </refsect1>
   <refsect1>
    <title>Affected by</title>
    <para>None.</para>
   </refsect1>
   <refsect1>
    <title>Exceptional Situations</title>
    <para>None.</para>
   </refsect1>
  </refentry>

 </reference>
</book>
<!-- Keep this comment at the end of the file
     Local variables:
     mode: nxml
     sgml-indent-step: 1
     nxml-child-indent: 1
     nxml-outline-child-indent: 0
     fill-column: 79
     End:
-->
