Accessor

Summary

Accesses and returns the value of a foreign object.

Package

fli

Signature

dereference pointer &key index type copy-foreign-object => value

setf (dereference pointer &key index type copy-foreign-object) value => value

Arguments

pointer

An instance of a FLI pointer.

index

An integer. If index is supplied, dereference assumes that pointer points to one element in an array of object, and returns the element at the index position in the array.

type

The foreign object type that pointer points to. If the specified type is different to the actual type, dereference returns the value of the object in the format of type where possible.

copy-foreign-object

This option is only important when dealing with aggregate FLI types, which cannot be returned by value.

If set to t, dereference makes a copy of the aggregate object pointed to by pointer and returns the copy.

If set to nil, dereference returns the aggregate object directly.

If set to :error then dereference signals an error. This is the default value for copy-foreign-object.

Values

value

The value of the dereferenced object at pointer.

Description

The accessor dereference accesses and returns the value of the FLI object pointed to by pointer, unless pointer points to an aggregate type. In the case of aggregates, the return value is specified by using the copy-foreign-object option.

An error is signaled if value is an aggregate type and copy-foreign-object is not set accordingly.

The value of an object at pointer can be changed using the setf form of dereference. See the examples section for an example of this.

An error is signaled if pointer is a null pointer. You can use null-pointer-p to detect null pointers.

Compatibility note

64-bit integer types such as (:long :long) , :int64 and :uint64 are now supported for type in dereference in 32-bit LispWorks. In 32-bit LispWorks 6.1 and earlier versions, these types could only be used by define-foreign-function.

Example

In the following example a LONG type is defined and an instance, pointed to by point, with a specified initial value of 10 is created with memory allocated using allocate-foreign-object. The dereference function is then used to get the value that point points to.

(fli:define-c-typedef LONG :long)

(setq point (fli:allocate-foreign-object

             :type 'LONG

             :initial-element 10))

(fli:dereference point)

Finally, the value of the object of type LONG is changed to 20 using the setf form of dereference.

(setf (fli:dereference point) 20)

In the next example, a boolean FLI type is defined, but is accessed as a char.

(fli:define-c-typedef BOOL (:boolean :int)) (setq point2 (fli:allocate-foreign-object :type 'BOOL)) (fli:dereference point2 :type :char)

See also

allocate-foreign-object
free-foreign-object
foreign-slot-value
null-pointer-p
FLI Types
Pointer dereferencing and coercing
Calling a C function that takes an array of strings