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


@defindex ci


@node Callable Info
@subsection Callable Info

G-Golf Callable Info low level API.@*
GICallableInfo — Struct representing a callable.


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-callable-info-can-throw-gerror}
@item @ref{g-callable-info-get-n-args}
@item @ref{g-callable-info-get-arg}
@item @ref{g-callable-info-get-caller-owns}
@item @ref{g-callable-info-get-instance-ownership-transfer}
@item @ref{g-callable-info-get-return-type}
@item @ref{g-callable-info-invoke}
@item @ref{g-callable-info-is-method}
@item @ref{g-callable-info-may-return-null}
@item @ref{g-callable-info-create-closure}
@item @ref{g-callable-info-get-closure-native-address}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @ref{...}
@c @end table
@c @end indentedblock


@subheading Struct Hierarchy

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


@subheading Description

@code{GICallableInfo} represents an entity which is callable. Examples
of callable are: functions (@code{GIFunctionInfo}), virtual functions,
(@code{GIVFuncInfo}), callbacks (@code{GICallbackInfo}).

A callable has a list of arguments (@code{GIArgInfo}), a return type,
direction and a flag which decides if it returns null.


@subheading Procedures

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


@anchor{g-callable-info-can-throw-gerror}
@deffn Procedure g-callable-info-can-throw-gerror info

Returns @code{#t} if the callable @var{info} can throw a GError,
otherwise it returns @code{#f}.
@end deffn


@anchor{g-callable-info-get-n-args}
@deffn Procedure g-callable-info-get-n-args info

Returns the number of arguments this @var{info} expects.

Obtain the number of arguments (both IN and OUT) for this
@var{info}.
@end deffn


@anchor{g-callable-info-get-arg}
@deffn Procedure g-callable-info-get-arg info n

Returns a pointer to the @var{n}th @code{GIArgInfo} of @var{info}.

It must be freed by calling @ref{g-base-info-unref} when done accessing
the data.
@end deffn


@anchor{g-callable-info-get-caller-owns}
@deffn Procedure g-callable-info-get-caller-owns info

Returns a @code{GITransfer} enumerated value.

See whether the caller owns the return value of this callable. See
@ref{%gi-transfer} for the list of possible values.
@end deffn


@anchor{g-callable-info-get-instance-ownership-transfer}
@deffn Procedure g-callable-info-get-instance-ownership-transfer info

Returns a @code{GITransfer} enumerated value.

Obtains the ownership transfer for the instance argument. See
@ref{%gi-transfer} for the list of possible values.
@end deffn


@anchor{g-callable-info-get-return-type}
@deffn Procedure g-callable-info-get-return-type info

Returns a pointer to the @code{GITypeInfo}.

It must be freed by calling @ref{g-base-info-unref} when done accessing
the data.
@end deffn


@anchor{g-callable-info-invoke}
@deffn Procedure g-callable-info-invoke info function in-args n-in @
       out-args n-out r-val is-method throws 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{function}
a pointer to 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{is-method}
is the callable info is a method.

@item @emph{throws}
can the callable throw a @code{GError}.

@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


@anchor{g-callable-info-is-method}
@deffn Procedure g-callable-info-is-method info

Returns @code{#t} if the callable @var{info} is a method, otherwise it
return @code{#f}.

Determines if the callable @var{info} is a method. For
@code{GIVFuncInfo} and @code{GISignalInfo}, this is always
true. Otherwise, this looks at the @code{GI_FUNCTION_IS_METHOD} flag on
the @code{GIFunctionInfo}.

Concretely, this function returns whether
@ref{g-callable-info-get-n-args} matches the number of arguments in the
raw C method. For methods, there is one more C argument than is exposed
by introspection: the @samp{self} or @samp{this} object.
@end deffn


@anchor{g-callable-info-may-return-null}
@deffn Procedure g-callable-info-may-return-null info

Returns @code{#t} if the callable @var{info} could return @code{NULL}.

See if a callable could return NULL.
@end deffn


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

Returns the ffi-closure or @code{#f} on error.

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


@anchor{g-callable-info-get-closure-native-address}
@deffn Procedure g-callable-info-get-closure-native-address info @
                 ffi-closure

Returns a pointer.

Obtain and return the callable code from @var{ffi-closure} prepared by
@ref{g-callable-info-create-closure}. The return value should be freed
by calling @code{g-callable-info-destroy-closure}.
@end deffn


@c @subheading Types and Values
