1 <?xml version="1.0" encoding="utf-8"?>
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.inc">
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. This is generalized
213 and can be used with <function>setf</function>.
217 <title>Examples</title>
219 (get-slot-value foo-ptr 'foo-structure 'field-name)
220 (setf (get-slot-value foo-ptr 'foo-structure 'field-name) 10)
224 <title>Side Effects</title>
228 <title>Affected by</title>
232 <title>Exceptional Situations</title>
237 <refentry id="get-slot-pointer">
239 <refname>get-slot-pointer</refname>
240 <refpurpose>Retrieves a pointer from a slot of a structure.
242 <refclass>Macro</refclass>
245 <title>Syntax</title>
247 <function>get-slot-pointer</function> <replaceable>obj type field</replaceable> => <returnvalue>pointer</returnvalue>
251 <title>Arguments and Values</title>
254 <term><parameter>obj</parameter></term>
256 <para>A pointer to foreign structure.
261 <term><parameter>type</parameter></term>
263 <para>A name of the foreign structure.
268 <term><parameter>field</parameter></term>
270 <para>A name of the desired field in foreign structure.
275 <term><returnvalue>pointer</returnvalue></term>
277 <para>The value of the field in the structure.
284 <title>Description</title>
286 This is similar to <function>get-slot-value</function>. It
287 is used when the value of a slot is a pointer type.
291 <title>Examples</title>
293 (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr)
297 <title>Side Effects</title>
301 <title>Affected by</title>
305 <title>Exceptional Situations</title>
311 <refentry id="def-array-pointer">
313 <refname>def-array-pointer</refname>
314 <refpurpose>Defines a pointer to a array of type.
316 <refclass>Macro</refclass>
319 <title>Syntax</title>
321 <function>def-array-pointer</function> <replaceable>name type</replaceable>
325 <title>Arguments and Values</title>
328 <term><parameter>name</parameter></term>
330 <para>A name of the new foreign type.
335 <term><parameter>type</parameter></term>
337 <para>The foreign type of the array elements.
344 <title>Description</title>
346 Defines a type tat is a pointer to an array of type.
350 <title>Examples</title>
352 (def-array-pointer byte-array-pointer :unsigned-char)
356 <title>Side Effects</title>
357 <para>Defines a new foreign type.</para>
360 <title>Affected by</title>
364 <title>Exceptional Situations</title>
370 <refentry id="deref-array">
372 <refname>deref-array</refname>
373 <refpurpose>Deference an array.
375 <refclass>Macro</refclass>
378 <title>Syntax</title>
380 <function>deref-array</function> <replaceable>array type position</replaceable> => <returnvalue>value</returnvalue>
384 <title>Arguments and Values</title>
387 <term><parameter>array</parameter></term>
389 <para>A foreign array.
394 <term><parameter>type</parameter></term>
396 <para>The foreign type of the array.
401 <term><parameter>position</parameter></term>
403 <para>An integer specifying the position to retrieve from
409 <term><returnvalue>value</returnvalue></term>
411 <para>The value stored in the position of the array.
418 <title>Description</title>
420 Dereferences (retrieves) the value of an array element.
424 <title>Examples</title>
426 (def-array-pointer ca :char)
427 (let ((fs (convert-to-foreign-string "ab")))
428 (values (null-char-p (deref-array fs 'ca 0))
429 (null-char-p (deref-array fs 'ca 2))))
437 The TYPE argument is ignored for CL implementations other than
438 AllegroCL. If you want to cast a pointer to another type use
439 WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.
443 <title>Side Effects</title>
447 <title>Affected by</title>
451 <title>Exceptional Situations</title>
456 <refentry id="def-union">
458 <refname>def-union</refname>
459 <refpurpose>Defines a foreign union type.
461 <refclass>Macro</refclass>
464 <title>Syntax</title>
466 <function>def-union</function> <replaceable>name &rest fields</replaceable>
470 <title>Arguments and Values</title>
473 <term><parameter>name</parameter></term>
475 <para>A name of the new union type.
480 <term><parameter>fields</parameter></term>
482 <para>A list of fields of the union.
489 <title>Description</title>
491 Defines a foreign union type.
495 <title>Examples</title>
497 (def-union test-union
501 (let ((u (allocate-foreign-object 'test-union))
502 (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256)))
504 (ensure-char-character (get-slot-value u 'test-union 'a-char))
505 (free-foreign-object u)))
510 <title>Side Effects</title>
511 <para>Defines a new foreign type.</para>
514 <title>Affected by</title>
518 <title>Exceptional Situations</title>