5 Function and Macro Reference

define-foreign-callable

Macro

Summary

Defines a Lisp function which can be called from a foreign language.

Package

fli

Signature

define-foreign-callable (foreign-name &key encode language result-type no-check ) ({args}*) &body body => lisp-name

args ::= {arg-name} | (arg-name arg-type)

Arguments

foreign-name

A string or symbol naming the Lisp callable function created.

encode

By default, LispWorks performs automatic name encoding to translate foreign-name

If you want to explicitly specify an encoding, the encode option can be one of the following:

:source tells LispWorks that foreign-name is the function name to call from the foreign source code. This is the default value of encoding.

:object tells LispWorks that foreign-name is the literal name to be called in the foreign object code.

:lisp tells LispWorks that if foreign-name is a Lisp symbol, it must be translated and encoded.

:dbcs adds a suffix onto the function name which will automatically change depending on whether Lisp image is started up in the Windows NT or Windows 95 operating system. The suffix is "A" for Windows 95 and "W" for Windows NT.

language

The language in which the foreign calling code is written. The default is:c.

result-type

The FLI type of the Lisp foreign callable function's return value which is passed back to the calling code.

no-check

Ifnil, the result of the foreign callable function, produced by body, is checked to see if matches the result-type, and an error is raised if they do not match. Setting no-check tot overrides this check.

calling-convention

Specifies the calling convention used.

:stdcall is the calling convention used to call Win32 API functions and matches the C declarator"__stdcall".

:cdecl is the default calling convention for C/C++ programs and matches the C declarator "__cdecl".

args

The arguments of the Lisp foreign callable function. Each argument can consist either of an arg-name, in which case LispWorks assumes it is an:int, or an arg-name and an arg-type, which is an FLI type.

body

A list of forms which make up the Lisp foreign callable function.

Values

lisp-name: A string or symbol naming the Lisp callable function created.

Description

The macrodefine-foreign-callable defines a Lisp function that can be called from a foreign language, for example from a C function. When the Lisp function is called, data passed to it is converted to the appropriate FLI representation, which is translated to an appropriate Lisp representation for the Lisp part of the function. Once the callable function exits, any return values are converted back into an FLI format to be passed back to the calling language.

Example

The following example demonstrates the use of foreign callable. A foreign callable function,square, is defined, which takes an integer as its argument, and returns the square of the integer.

(fli:define-foreign-callable 
  ("square" :result-type :int)
  ((arg-1 :int)) (* arg-1 arg-1))

: The foreign callable function,square, can now be called from a foreign language. We can mimic a foreign call by using thedefine-foreign-function command to define an FLI function to callsquare.

(fli:define-foreign-function (call-two "square")
  ((in-arg :int)) :result-type :int)

: Thecall-two function can now be used to callsquare. The next command is an example of this.

(call-two 9)

See Also
: define-foreign-function
: define-foreign-variable