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


@defindex ai


@node Arg Info
@subsection Arg Info

G-Golf Arg Info low level API.@*
GIArgInfo — Struct representing an argument.


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-arg-info-get-closure}
@item @ref{g-arg-info-get-destroy}
@item @ref{g-arg-info-get-direction}
@item @ref{g-arg-info-get-ownership-transfer}
@item @ref{g-arg-info-get-scope}
@item @ref{g-arg-info-get-type}
@item @ref{g-arg-info-may-be-null}
@item @ref{g-arg-info-is-caller-allocates}
@item @ref{g-arg-info-is-optional}
@item @ref{g-arg-info-is-return-value}
@item @ref{g-arg-info-is-skip}
@end table
@end indentedblock


@subheading Types and Values

@indentedblock
@table @code
@item @ref{%gi-direction}
@item @ref{%gi-scope-type}
@item @ref{%gi-transfer}
@end table
@end indentedblock


@subheading Struct Hierarchy

@indentedblock
GIBaseInfo           	       @*
@ @ +--- GIArgInfo	       @*
@end indentedblock


@subheading Description

@code{GIArgInfo} represents an argument. An argument is always part of a
@code{GICallableInfo}.


@subheading Procedures

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


@anchor{g-arg-info-get-closure}
@deffn Procedure g-arg-info-get-closure info

Returns the index of the user data argument or -1 if there is none.

Obtains the index of the user data argument. This is only valid for
arguments which are callbacks.
@end deffn


@anchor{g-arg-info-get-destroy}
@deffn Procedure g-arg-info-get-destroy info

Returns the index of the @code{GDestroyNotify} argument or -1 if there
is none.

Obtains the index of the @code{GDestroyNotify} argument. This is only
valid for arguments which are callbacks.
@end deffn


@anchor{g-arg-info-get-direction}
@deffn Procedure g-arg-info-get-direction info

Returns a symbol.

Obtains and returns the @ref{%gi-direction} of the argument.
@end deffn


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

Returns a symbol.

Obtains and returns the @ref{%gi-transfer} for this argument.
@end deffn


@anchor{g-arg-info-get-scope}
@deffn Procedure g-arg-info-get-scope info

Returns a symbol.

Obtains and returns the @ref{%gi-scope-type} for this argument. The
scope type explains how a callback is going to be invoked, most
importantly when the resources required to invoke it can be freed.
@end deffn


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

Returns a pointer.

Obtains the @code{GITypeInfo} holding the type information for
@var{info}.  Free it using @ref{g-base-info-unref} when done.
@end deffn


@anchor{g-arg-info-may-be-null}
@deffn Procedure g-arg-info-may-be-null info

Returns @code{#t} or @code{#f}.

Obtains if the type of the argument includes the possibility of
@code{NULL}. For 'in' values this means that @code{NULL} is a valid
value. For 'out' values, this means that @code{NULL} may be returned.
@end deffn


@anchor{g-arg-info-is-caller-allocates}
@deffn Procedure g-arg-info-is-caller-allocates info

Returns @code{#t} or @code{#f}.

Obtain if the argument is a pointer to a struct or object that will
receive an output of a function. The default assumption for
@code{out} arguments which have allocation is that the callee
allocates; if this is TRUE, then the caller must allocate.
@end deffn


@anchor{g-arg-info-is-optional}
@deffn Procedure g-arg-info-is-optional info

Returns @code{#t} or @code{#f}.

Obtains if the argument is optional. For 'out' arguments this means that
you can pass @code{NULL} in order to ignore the result.
@end deffn


@anchor{g-arg-info-is-return-value}
@deffn Procedure g-arg-info-is-return-value info

Returns @code{#t} or @code{#f}.

Obtains if the argument is a retur value. It can either be a parameter
or a return value.
@end deffn


@anchor{g-arg-info-is-skip}
@deffn Procedure g-arg-info-is-skip info

Returns @code{#t} or @code{#f}.

Obtains if an argument is only useful in C.
@end deffn


@subheading Types and Values


@anchor{%gi-direction}
@defivar <gi-enum> %gi-direction

An instance of @code{<gi-enum>}, who's members are the scheme
representation of the direction of a @code{GIArgInfo}:

@indentedblock
@emph{g-name}: GIDirection  @*
@emph{name}: gi-direction  @*
@emph{enum-set}:
@indentedblock
@table @code
@item in
in argument.

@item out
out argument.

@item inout
in and out argument.
@end table
@end indentedblock
@end indentedblock
@end defivar


@anchor{%gi-scope-type}
@defivar <gi-enum> %gi-scope-type

An instance of @code{<gi-enum>}, who's members are the scheme
representation of the scope of a @code{GIArgInfo}. Scope type of a
@code{GIArgInfo} representing callback, determines how the callback is
invoked and is used to decide when the invoke structs can be freed.

@indentedblock
@emph{g-name}: GIScopeType  @*
@emph{name}: gi-scope-type  @*
@emph{enum-set}:
@indentedblock
@table @code
@item invalid
The argument is not of callback type.

@item call
The callback and associated user_data is only used during the call to
this function.

@item async
The callback and associated user_data is only used until the callback is
invoked, and the callback. is invoked always exactly once.

@item notified
The callback and and associated user_data is used until the caller is
notfied via the destroy_notify.
@end table
@end indentedblock
@end indentedblock
@end defivar


@anchor{%gi-transfer}
@defivar <gi-enum> %gi-transfer

The transfer is the exchange of data between two parts, from the callee
to the caller. The callee is either a function/method/signal or an
object/interface where a property is defined. The caller is the side
accessing a property or calling a function. @code{GITransfer} specifies
who's responsible for freeing the resources after the ownership transfer
is complete. In case of a containing type such as a list, an array or a
hash table the container itself is specified differently from the items
within the container itself. Each container is freed differently, check
the documentation for the types themselves for information on how to
free them.

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

@indentedblock
@emph{g-name}: GITransfer  @*
@emph{name}: gi-transfer  @*
@emph{enum-set}:
@indentedblock
@table @code
@item nothing
transfer nothing from the callee (function or the type instance the
property belongs to) to the caller. The callee retains the ownership of
the transfer and the caller doesn't need to do anything to free up the
resources of this transfer

@item container
transfer the container (list, array, hash table) from the callee to the
caller. The callee retains the ownership of the individual items in the
container and the caller has to free up the container resources
@code{g_list_free}, @code{g_hash_table_destroy}, @dots{} of this transfer

@item everything
transfer everything, eg the container and its contents from the callee
to the caller. This is the case when the callee creates a copy of all
the data it returns. The caller is responsible for cleaning up the
container and item resources of this transfer

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