5 Function and Macro Reference

define-foreign-function

Macro

Summary

Defines a Lisp function which acts as an interface to a foreign function.

Package

fli

Signature

define-foreign-function name ({arg}*)
                        &key lambda-list
                             documentation result-type language
                             no-check 
                             => lisp-name

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

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

arg ::= arg-name | (arg-name arg-type) |
        (:constant value value-type)

language ::= :c | :ansi-c

calling-convention ::= :stdcall | :cdecl

Arguments

name

Either a symbol naming the defined Lisp function, or a list containing the name of the Lisp function, the corresponding foreign function name and optionally an encoding option.

lisp-name

A symbol naming the defined Lisp function.

foreign-symbol

A symbol naming the foreign function.

foreign-string

A string containing the name of the foreign function.

encoding

An option controlling how the Lisp function name is translated into the function name in the foreign object code. The encoding option can be one of the following:

:source tells LispWorks that the string foreign-string or the symbol foreign-symbol is the name of the function in the foreign source code. This is the default value of encoding.

:object tells LispWorks that the string foreign-string or the symbol foreign-symbol is the literal name of the function in the foreign object code.

:lisp tells LispWorks that the symbol foreign-symbol is a Lisp symbol and 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.

arg

Either an argument name, a list containing an argument name and a type, or a list of the form(:constant value value-type). Lisp arguments may take any name, but the types must be accurately specified and listed in the same order as in the foreign function, unless otherwise specified using lambda-list.

If only an arg-name is supplied, thendefine-foreign-function assumes that it is of type:int.

If arg is of the form(:constant value value-type) then value is always passed through to the foreign code.

lambda-list

The lambda list to be used for the defined Lisp function. If this is not specified, the lambda list is generated from the list of args. The lambda-list keyword allows you to define the order in which the Lisp function takes its arguments to be different from the order in which the foreign function takes them, and to use standard lambda list keywords such as&optional. The default value of lambda-list isnil.

documentation

A documentation string for the foreign function.

result-type

The type of the foreign function's return value.

language

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

no-check

Ifnil, 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 tot overrides this check.

If the compilation safety level is set to 0 then no-check is automatically set tot. The default value for no-check isnil.

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".

module

Specifies the module in which the foreign symbol is defined. If it is the name of a module registered usingregister-module then that module is used to look up the symbol. If the name of the module is a string then that module is automatically registered and used to look up the symbol.

Values

lisp-name: A symbol naming the defined Lisp function.

Description

The macrodefine-foreign-function defines a Lisp function which acts as an interface to a foreign language function, for example a C function. When the Lisp function is called its arguments are converted to the appropriate foreign representation before being passed to the specified foreign function. Once the foreign function exits, any return values are converted back from the foreign format into a Lisp format.

The number and types of the Lisp function's arguments must be given, and optionally the type of the return value may be specified too. The order in which the Lisp function takes its arguments can be different from the order expected by the foreign function, using the lambda-list argument.

Example

A simple example of the use ofdefine-foreign-function is given in "Defining an FLI function" on page 5. More detailed examples are given in Chapter 4, "Advanced Uses of the FLI".

See Also

define-foreign-callable

define-foreign-variable