@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2022 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@c @defindex tl


@node FFI Interface
@subsection FFI Interface

G-Golf FFI Interface low level API.@*
girffi — TODO.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-type-tag-get-ffi-type}
@item @ref{g-type-info-get-ffi-type}
@item @ref{gi-type-info-extract-ffi-return-value}
@item @ref{gi-type-tag-extract-ffi-return-value}
@item @ref{g-callable-info-prepare-closure}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @item @ref{%g-arg-info-transfer}
@c @end table
@c @end indentedblock


@c @subheading Struct Hierarchy

@c @indentedblock
@c GIBaseInfo           	       		@*
@c @ @ +--- GIRegisteredTypeInfo  		@*
@c @ @ @ @ @ @ @ @ @ @ @  +--- GIEnumInfo
@c @end indentedblock


@subheading Description

TODO.


@subheading Procedures

@c Note: in this section, the @var{typelib} argument is [must be] a
@c pointer to a @code{GITypelib}.


@anchor{gi-type-tag-get-ffi-type}
@deffn Procedure gi-type-tag-get-ffi-type type-tag is-pointer?

Returns a (pointer to) @code{ffi-type} corresponding to the platform
default C ABI for @var{type-tag} and @var{is-pointer?}.

The @var{info} argument is (must be) a valid @ref{%gi-type-tag},
otherwise an exception is raised.

The @var{is-pointer?} argument, @code{#t} or @code{#f}, to indicate
whether or not this is a pointer type.
@end deffn


@anchor{g-type-info-get-ffi-type}
@deffn Procedure g-type-info-get-ffi-type info

Returns an (pointer to) @code{ffi-type} corresponding to the platform
default C ABI for @var{info}.

The @var{info} argument is [must be] a pointer to a @code{GITypeInfo}.
@end deffn


@anchor{gi-type-info-extract-ffi-return-value}
@deffn Procedure gi-type-info-extract-ffi-return-value type-info @
       ffi-value gi-argument

Returns nothing.

Extract the correct bits from @var{ffi-value} into @var{gi-argument}.

The @var{type-info} is the @code{GITypeInfo} of @var{ffi-value}. The
@var{ffi-value} is a pointer to a @code{GIFFIReturnValue} union
containing the value from the @code{ffi_call()}. The @var{gi-argument}
is a pointer to an allocated @code{GIArgument}.
@end deffn


@anchor{gi-type-tag-extract-ffi-return-value}
@deffn Procedure gi-type-tag-extract-ffi-return-value return-tag @
       interface-type ffi-value gi-argument

Returns nothing.

Extract the correct bits from @var{ffi-value} into @var{gi-argument}.

The @var{return-tag} is the @ref{%gi-type-tag} of @var{ffi-value}. The
@var{interface-type} is the @ref{%gi-info-type} of the underlying
interface. The @var{ffi-value} is a pointer to a @code{GIFFIReturnValue}
union containing the value from the @code{ffi_call()}. The
@var{gi-argument} is a pointer to an allocated @code{GIArgument}.

The @var{interface-type} argument only applies if @var{return-tag} is
@code{'interface}, otherwise it is ignored.
@end deffn


@anchor{g-callable-info-prepare-closure}
@deffn Procedure g-callable-info-prepare-closure info @
                 ffi-cif ffi-closure-callback user-data

Returns the native address of the closure or @code{#f} on error.

@example
The procedure has been deprecated since version @code{1.72} and should
not be used in newly-written code. Use
@ref{g-callable-info-create-closure} instead.
@end example

The return value should be freed by calling
@code{g-callable-info-free-closure}.
@end deffn
