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


@defindex fi


@node Function Info
@subsection Function Info

G-Golf Function Info low level API.@*
GIFunctionInfo — Struct representing a function.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-function-info-is-method?}
@item @ref{g-function-info-get-flags}
@item @ref{g-function-info-get-property}
@item @ref{g-function-info-get-symbol}
@item @ref{g-function-info-get-vfunc}
@item @ref{g-function-info-invoke}
@end table
@end indentedblock


@subheading Types and Values


@indentedblock
@table @code
@item @ref{%g-function-info-flags}
@end table
@end indentedblock


@subheading Struct Hierarchy

@indentedblock
GIBaseInfoInfo         	                     @*
@ @ +--- GICallableInfo	                     @*
@ @ @ @ @ @ @ @ @ @ @ +--- GIFunctionInfo    @*
@ @ @ @ @ @ @ @ @ @ @ +--- GISignalInfo      @*
@ @ @ @ @ @ @ @ @ @ @ +--- GIVFuncInfo
@end indentedblock


@subheading Description

@code{GIFunctionInfo} represents a function, method or constructor. To
find out what kind of entity a GIFunctionInfo represents, call
@ref{g-function-info-get-flags}.

See also @ref{Callable Info} for information on how to retreive
arguments and other metadata.


@subheading Procedures

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


@anchor{gi-function-info-is-method?}
@deffn Procedure gi-function-info-is-method? info [flags #f]

Returns @code{#t} if @var{info} is a method, that is if @code{is-method}
is a member of the @var{info} flags. Otherwise, it returns @code{#f}.

The optional @var{flags} argument, if passed, must be the list of the
function info flags as returned by @ref{g-function-info-get-flags}.
@end deffn


@anchor{g-function-info-get-flags}
@deffn Procedure g-function-info-get-flags info

Returns a list of @ref{%g-function-info-flags}.

Obtain the @code{GIFunctionInfoFlags} for @var{info}.
@end deffn


@anchor{g-function-info-get-property}
@deffn Procedure g-function-info-get-property info

Returns a pointer or @code{#f}.

Obtains the @code{GIPropertyInfo} associated with @var{info}.  Only
@code{GIFunctionInfo} with the flag @code{is-getter} or
@code{is-setter} have a property set. For other cases, @code{#f} will be
returned.

The @code{GIPropertyInfo} must be freed by calling
@ref{g-base-info-unref} when done.
@end deffn


@anchor{g-function-info-get-symbol}
@deffn Procedure g-function-info-get-symbol info

Returns a string.

Obtain the @samp{symbol} of the function@footnote{As you have noticed
already, since @code{g-function-info-get-symbol} returns a string, in
the Glib, GObject and GObject Instrospection worlds, symbol has a
different meaning then in the Lisp/Scheme worlds.  However, since the
procedure is part of the G-Golf low-level API, we decided to keep its
name as close as the original name as possible, which in @code{Glib}
terms is the name of the exported function, @samp{suitable to be used as
an argument to g_module_symbol()}}.
@end deffn


@anchor{g-function-info-get-vfunc}
@deffn Procedure g-function-info-get-vfunc info

Returns a pointer or @code{#f}.

Obtains the @code{GIVFuncInfo} associated with @var{info}.  Only
@code{GIFunctionInfo} with the flag @code{wraps-vfunc} has its virtual
function set. For other cases, @code{#f} will be returned.

The @code{GIVFuncInfo} must be freed by calling @ref{g-base-info-unref}
when done.
@end deffn


@anchor{g-function-info-invoke}
@deffn Procedure g-function-info-invoke info in-args n-in @
       out-args n-out r-val g-error

Returns @code{#t} if the function has been invoked, @code{#f} if an
error occured.

Invokes the function described in @var{info} with the given
arguments. Note that i@code{nout} parameters must appear in both
argument lists. The arguments are:

@indentedblock
@table @code
@item @emph{info}
a pointer to a @code{GIFunctionInfo} describing the function to invoke.

@item @emph{in-args}
a pointer to an array of @code{GIArguments}, one for each @code{in} and
@code{inout} parameter of @var{info}. If there are no @code{in}
parameter, @var{in-args} must be the @code{%null-pointer}.

@item @emph{n-in}
the length of the @var{in-args} array.

@item @emph{out-args}
a pointer to an array of @code{GIArguments}, one for each @code{out} and
@code{inout} parameter of @var{info}. If there are no @code{out}
parameter, @var{out-args} must be the @code{%null-pointer}.

@item @emph{n-out}
the length of the @var{out-args} array.

@item @emph{r-val}
a pointer to a @code{GIArguments}, the return location for the return
value of the function. If the function returns @code{void}, @var{r-val}
must be the @code{%null-pointer}.

@item @emph{g-error}
a pointer to a newly allocated (and @samp{empty}) @code{GError} (the
recommended way for procedure calls that need such a pointer is to
@samp{surround} the call using @ref{with-gerror}).
@end table
@end indentedblock



@end deffn


@subheading Types and Values


@anchor{%g-function-info-flags}
@defivar <gi-flags> %g-function-info-flags

An instance of @ref{<gi-flags>}, who's members are the scheme
representation of the @code{GIFunctionInfoFlags}:

@indentedblock
@emph{g-name}: GIFunctionInfoFlags  @*
@emph{name}: gi-function-info-flags  @*
@emph{enum-set}:
@indentedblock
@table @code

@item is-method
Is a method.

@item is-constructor
Is a constructor.

@item is-getter
Is a getter of a @code{GIPropertyInfo}.

@item is-setter
Is a setter of a @code{GIPropertyInfo}.

@item wraps-vfunc
Represent a virtul function.

@item throws
The function may throw an error.

@end table
@end indentedblock
@end indentedblock
@end defivar
