define-foreign-variable

Summary

Defines a Lisp function to access a variable in foreign code.

Signature

define-foreign-variable the-name
 &key type
 accessor
 language

                                                                   
   no-check
 module
 => lisp-name

the-name
 ::= lisp-name
 | (lisp-name
 foreign-name
 [encoding
])



encoding
 ::= :source | :object | :lisp | :dbcs



accessor
 ::= :value | :address-of | :read-only | :constant

language ::= :c | :ansi-c

Arguments

the-name

Names the Lisp function which is used to access the foreign variable.

lisp-name

A symbol naming the Lisp accessor.

foreign-name

A string or a symbol specifying the foreign name of the variable.

encoding

An option controlling how the Lisp variable name is translated to match the foreign variable name in the foreign DLL. The encoding option can be one of the following:

:source tells LispWorks that foreign-name is the name of the variable in the foreign source code. This is the default value of encoding when foreign-name is a string.

:object tells LispWorks that foreign-name is the literal name of the variable in the foreign object code.

:lisp tells LispWorks that if foreign-name is a Lisp symbol, it must be translated and encoded. This is the default value of encoding if foreign-name is a symbol.

:dbcs modifies the variable name on Windows, as described for define-foreign-function.

type

The FLI type corresponding to the type of the foreign variable to which Lisp is interfacing.

accessor

An option specifying what kind of accessor is generated for the variable. It can be one of the following:

:value gets the value of the foreign variable directly. This is the default value when type is a non-aggregate type. (There is no default accessor for aggregate types.)

:address-of returns a FLI pointer to the foreign variable.

:read-only ensures that no setf method is defined for the variable, which means that its value can be read, but it cannot be set.

:constant is like :read-only and will return a constant value. For example, this is more efficient for a variable that always points to the same string.

language

The language in which the foreign source code for the variable is written. The default is :ansi-c .

no-check

If nil , the types of the arguments provided when the Lisp function is called are compared with the expected types and an error is raised if they do not match. Setting no-check to t overrides this check.

module

A string or symbol naming the module in which the foreign variable is defined.

Values

lisp-name

A symbol naming the Lisp accessor.

Description

The macro define-foreign-variable defines a Lisp accessor which can be used to get and set the value of a variable defined in foreign code.

If the foreign variable has a type corresponding to an FLI aggregate type, then accessor must be supplied (there is no default). If accessor is :value , then a copy of the object is allocated using allocate-foreign-object, and the copy is returned. In general, it is more useful to use accessor :address-of for aggregate types, to allow the original aggregate to be updated.

Notes

If you specify any of the FLI float types :float, :double, :lisp-float, :lisp-single-float and so on, then the value of language should be :ansi-c .

module is processsed as for define-foreign-function.

Example

The following example illustrates how to use the FLI to define a foreign variable, given the following C variable in a DLL:


int num;

The first example defines a Lisp variable, num1 , to interface with the C variable num .


(fli:define-foreign-variable (num1 "num") :type :int)

The following commands return the value of num , and increase its value by 1:


(num1)


(incf (num1))

In the next example, the Lisp variable num2 interfaces with num in a read-only manner.

(fli:define-foreign-variable (num2 "num")

  :type :int :accessor :READ-ONLY)

In this case, the next command still returns the value of num , but the second command raises an error, because num2 is read-only.


(num2)


(incf (num2))

The final example defines a Lisp variable, num3 , which accesses num through pointers.

(fli:define-foreign-variable (num3 "num")

  :type :int :accessor :address-of)

As a result, the next command returns a pointer to num , and to obtain the actual value stored by num , num3 needs to be dereferenced.


(num3)


(fli:dereference (num3))