3.2.1 Wrapping a C Function

As seen in See A Simple Example, wrapping a C function using G-Wrap’s
high-level functions is relatively simple. Essentially, it boils down
to a call to the wrap-function! GOOPS method.

method: wrap-function!(wrapset <gw-wrapset>) . args

Add the C function described by args to the list of functions to
be wrapped by wrapset. The arguments in args must contain
the following named parameters (see (ice-9 optargs) in The GNU Guile Reference Manual):

#:name

the symbol which should be bound to the wrapped function in Scheme at
runtime.

#:returns

the symbol naming the G-Wrap wrapped type of the C function result.

#:c-name

a string giving the C function’s name.

#:arguments

a list of the C function’s arguments where each element is of the form
(more details below).

#:description

a string describing the function; this string may contain Texinfo
markup.

The argument list which is passed as the #:arguments named
parameter consists of a list of argument specifiers. Each
argument specifier is itself a two-element list where:

the first element is a type specifier;

the second element is a symbol that names the parameter.

The type specifier may in turn be one of the following:

a symbol naming a wrapped type;

a list containing a symbol naming a wrapped type and type
qualifier (in G-Wrap’s code, this is usually referred to as a
typespec, although this name is quite unfortunate); the type
qualifier may be one of:

in

if the parameter in question is an input parameter;

out

if the parameter in question is an output parameter;

caller-owned

if the parameter in question is a C pointer that points to memory
controlled by the caller;

callee-owned

if the parameter in question is a C pointer that points to memory
whose control is passed to the callee (FIXME: give an example);

null-ok

if the Scheme input parameter is to be converted to a C pointer, then
let G-Wrap know that #f is a valid value for this parameter;
#f will translate to the NULL pointer in C;

aggregated

if the parameter in question points to a C object that is
aggregated by the object returned by the function being wrapped
(more on this below). By object returned, we mean a wrapped C
pointer or WCP (see Wrapping a C Pointer Type) that is either
the return value or an out argument.