1 <?xml version='1.0' ?> <!-- -*- DocBook -*- -->
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.xml">
8 <reference id="aggregates">
9 <title>Aggregate Types</title>
11 <title>Overview</title>
13 Aggregate types are comprised of one or more primitive types.
17 <refentry id="def-enum">
19 <refname>def-enum</refname>
20 <refpurpose>Defines a &c; enumeration.
22 <refclass>Macro</refclass>
27 <function>def-enum</function> <replaceable>name fields &key separator-string</replaceable>
31 <title>Arguments and Values</title>
34 <term><parameter>name</parameter></term>
36 <para>A symbol that names the enumeration.
41 <term><parameter>fields</parameter></term>
43 <para>A list of field defintions. Each definition can be
44 a symbol or a list of two elements. Symbols get assigned a value of the
45 current counter which starts at <computeroutput>0</computeroutput> and
46 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
47 position is the value to assign the the symbol. The current counter gets set
48 to <computeroutput>1+</computeroutput> this value.
53 <term><parameter>separator-string</parameter></term>
55 <para>A string that governs the creation of constants. The
56 default is <computeroutput>"#"</computeroutput>.</para>
62 <title>Description</title>
64 Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant
65 values are created by the <function>concatenation</function> of the
66 enumeration name, separator-string, and field symbol. Also creates
67 a foreign type with the name <parameter>name</parameter> of type
68 <constant>:int</constant>.
72 <title>Examples</title>
74 (def-enum abc (:a :b :c))
75 ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines
76 ;; the foreign type "abc" to be :int
78 (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-")
79 ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines
80 ;; the foreign type efoo to be :int
84 <title>Side Effects</title>
85 <para>Creates a :int foreign type, defines constants.</para>
88 <title>Affected by</title>
92 <title>Exceptional Situations</title>
98 <refentry id="def-struct">
100 <refname>def-struct</refname>
101 <refpurpose>Defines a &c; structure.
103 <refclass>Macro</refclass>
106 <title>Syntax</title>
108 <function>def-struct</function> <replaceable>name &rest fields</replaceable>
112 <title>Arguments and Values</title>
115 <term><parameter>name</parameter></term>
117 <para>A symbol that names the structure.
122 <term><parameter>fields</parameter></term>
124 <para>A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type.
131 <title>Description</title>
133 Declares a structure. A special type is available as a slot
134 in the field. It is a pointer that points to an instance of the parent
135 structure. It's type is <constant>:pointer-self</constant>.
140 <title>Examples</title>
142 (def-struct foo (a :unsigned-int)
145 (next :pointer-self))
149 <title>Side Effects</title>
150 <para>Creates a foreign type.</para>
153 <title>Affected by</title>
157 <title>Exceptional Situations</title>
163 <refentry id="get-slot-value">
165 <refname>get-slot-value</refname>
166 <refpurpose>Retrieves a value from a slot of a structure.
168 <refclass>Macro</refclass>
171 <title>Syntax</title>
173 <function>get-slot-value</function> <replaceable>obj type field</replaceable> => <returnvalue>value</returnvalue>
177 <title>Arguments and Values</title>
180 <term><parameter>obj</parameter></term>
182 <para>A pointer to foreign structure.
187 <term><parameter>type</parameter></term>
189 <para>A name of the foreign structure.
194 <term><parameter>field</parameter></term>
196 <para>A name of the desired field in foreign structure.
201 <term><returnvalue>value</returnvalue></term>
203 <para>The value of the field in the structure.
210 <title>Description</title>
212 Accesses a slot value from a structure.
216 <title>Examples</title>
218 (get-slot-value foo-ptr 'foo-structure 'field-name)
222 <title>Side Effects</title>
226 <title>Affected by</title>
230 <title>Exceptional Situations</title>
235 <refentry id="get-slot-pointer">
237 <refname>get-slot-pointer</refname>
238 <refpurpose>Retrieves a pointer from a slot of a structure.
240 <refclass>Macro</refclass>
243 <title>Syntax</title>
245 <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
249 <title>Arguments and Values</title>
252 <term><parameter>obj</parameter></term>
254 <para>A pointer to foreign structure.
259 <term><parameter>type</parameter></term>
261 <para>A name of the foreign structure.
266 <term><parameter>field</parameter></term>
268 <para>A name of the desired field in foreign structure.
273 <term><returnvalue>pointer</returnvalue></term>
275 <para>The value of the field in the structure.
282 <title>Description</title>
284 This is similar to <function>get-slot-value</function>. It
285 is used when the value of a slot is a pointer type.
289 <title>Examples</title>
291 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
295 <title>Side Effects</title>
299 <title>Affected by</title>
303 <title>Exceptional Situations</title>
309 <refentry id="def-array-pointer">
311 <refname>def-array-pointer</refname>
312 <refpurpose>Defines a pointer to a array of type.
314 <refclass>Macro</refclass>
317 <title>Syntax</title>
319 <function>def-array-pointer</function> <replaceable>name type</replaceable>
323 <title>Arguments and Values</title>
326 <term><parameter>name</parameter></term>
328 <para>A name of the new foreign type.
333 <term><parameter>type</parameter></term>
335 <para>The foreign type of the array elements.
342 <title>Description</title>
344 Defines a type tat is a pointer to an array of type.
348 <title>Examples</title>
350 (def-array-pointer byte-array-pointer :unsigned-char)
354 <title>Side Effects</title>
355 <para>Defines a new foreign type.</para>
358 <title>Affected by</title>
362 <title>Exceptional Situations</title>
368 <refentry id="deref-array">
370 <refname>deref-array</refname>
371 <refpurpose>Deference an array.
373 <refclass>Macro</refclass>
376 <title>Syntax</title>
378 <function>deref-array</function> <replaceable>array type positon</replaceable> => <returnvalue>value</returnvalue>
382 <title>Arguments and Values</title>
385 <term><parameter>array</parameter></term>
387 <para>A foreign array.
392 <term><parameter>type</parameter></term>
394 <para>The foreign type of the array.
399 <term><parameter>position</parameter></term>
401 <para>An integer specifying the position to retrieve from
407 <term><returnvalue>value</returnvalue></term>
409 <para>The value stored in the position of the array.
416 <title>Description</title>
418 Dereferences (retrieves) the value of an array element.
422 <title>Examples</title>
424 (def-array-pointer ca :char)
425 (let ((fs (convert-to-foreign-string "ab")))
426 (values (null-char-p (deref-array fs 'ca 0))
427 (null-char-p (deref-array fs 'ca 2))))
435 The TYPE argument is ignored for CL implementations other than
436 AllegroCL. If you want to cast a pointer to another type use
437 WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
441 <title>Side Effects</title>
445 <title>Affected by</title>
449 <title>Exceptional Situations</title>
454 <refentry id="def-union">
456 <refname>def-union</refname>
457 <refpurpose>Defines a foreign union type.
459 <refclass>Macro</refclass>
462 <title>Syntax</title>
464 <function>def-union</function> <replaceable>name &rest fields</replaceable>
468 <title>Arguments and Values</title>
471 <term><parameter>name</parameter></term>
473 <para>A name of the new union type.
478 <term><parameter>fields</parameter></term>
480 <para>A list of fields of the union.
487 <title>Description</title>
489 Defines a foreign union type.
493 <title>Examples</title>
495 (def-union test-union
499 (let ((u (allocate-foreign-object 'test-union))
500 (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
502 (ensure-char-character (get-slot-value u 'test-union 'a-char))
503 (free-foreign-object u)))
508 <title>Side Effects</title>
509 <para>Defines a new foreign type.</para>
512 <title>Affected by</title>
516 <title>Exceptional Situations</title>